📚 课程目录第3章自定义资源(CRD)设计

3. 自定义资源（CRD）设计：CRD定义规范、版本管理（v1alpha1/v1beta1/v1）、字段校验与默认值

在Kubernetes Operator开发中，自定义资源（CRD）是声明式API的核心载体。一个设计良好的CRD不仅决定了Operator的易用性，更直接影响跨环境迁移、重试队列与对账系统的数据一致性。本节从定义规范、版本演进策略、字段校验与默认值三个维度展开，确保CRD在生产级流水线中具备可扩展性与稳定性。

3.1 CRD定义规范

CRD遵循OpenAPI v3.0 schema规范，通过openAPIV3Schema定义资源结构。核心规范包括：

group/names：API组（如pipeline.example.com）、复数名（migrationruns）、单数名（migrationrun）、短名（mr）。
scope：Namespaced（推荐）或Cluster，跨环境迁移通常使用Namespaced隔离租户。
versions：每个版本包含独立的schema、subresources、additionalPrinterColumns。
subresources：/status和/scale子资源，分离用户期望（spec）与系统状态（status）。

规范要点： 所有CRD必须定义spec和status两个顶级字段，禁止在spec中混入运行时状态。status字段仅由Operator控制器写入，用户只读。

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: migrationruns.pipeline.example.com
spec:
  group: pipeline.example.com
  names:
    plural: migrationruns
    singular: migrationrun
    shortNames:
    - mr
    kind: MigrationRun
    listKind: MigrationRunList
  scope: Namespaced
  versions:
  - name: v1alpha1
    served: true
    storage: false
    subresources:
      status: {}
    schema:
      openAPIV3Schema:
        type: object
        required: ["spec"]
        properties:
          spec:
            type: object
            required: ["sourceCluster", "targetCluster", "workloadRef"]
            properties:
              sourceCluster:
                type: string
                description: "源集群名称"
              targetCluster:
                type: string
                description: "目标集群名称"
              workloadRef:
                type: object
                required: ["kind", "name"]
                properties:
                  kind:
                    type: string
                    enum: ["Deployment", "StatefulSet", "DaemonSet"]
                  name:
                    type: string
              retryPolicy:
                type: object
                properties:
                  maxRetries:
                    type: integer
                    minimum: 0
                    maximum: 10
                    default: 3
                  backoffSeconds:
                    type: integer
                    minimum: 1
                    default: 5
          status:
            type: object
            properties:
              phase:
                type: string
                enum: ["Pending", "Running", "Succeeded", "Failed", "Retrying"]
              observedGeneration:
                type: integer
              conditions:
                type: array
                items:
                  type: object
                  required: ["type", "status", "lastTransitionTime"]
                  properties:
                    type:
                      type: string
                    status:
                      type: string
                      enum: ["True", "False", "Unknown"]
                    lastTransitionTime:
                      type: string
                      format: date-time
                    message:
                      type: string
              retryCount:
                type: integer
              lastRequeueTime:
                type: string
                format: date-time

3.2 版本管理策略：v1alpha1 → v1beta1 → v1

CRD版本管理遵循Kubernetes API弃用策略，每个版本对应不同的稳定性承诺。跨环境迁移流水线中，版本演进直接影响重试队列的序列化兼容性与对账字段的映射。

版本	稳定性	字段变更自由度	存储版本	典型使用场景
v1alpha1	实验性	可任意增删改字段	否	内部原型验证、快速迭代
v1beta1	Beta	可新增字段，删除需转换	否	跨环境迁移测试、重试队列集成
v1	稳定GA	仅允许新增可选字段	是	生产级对账、长期存储

版本演进最佳实践： 始终将最新稳定版本（v1）设为storage: true，旧版本通过内部转换Webhook将存储数据升级。重试队列中的历史CR对象在读取时自动转换，避免对账逻辑处理多版本。

版本转换通过Conversion Webhook实现，Operator需实现Convert()方法处理字段映射。以下为v1alpha1到v1的转换示例：

// v1alpha1 → v1 字段映射
func (h *MigrationRunConverter) Convert(in *v1alpha1.MigrationRun, out *v1.MigrationRun) error {
    out.Spec.SourceCluster = in.Spec.SourceCluster
    out.Spec.TargetCluster = in.Spec.TargetCluster
    // v1alpha1中workloadRef为字符串，v1中为结构化对象
    out.Spec.WorkloadRef = v1.WorkloadRef{
        Kind: "Deployment",
        Name: in.Spec.WorkloadName,
    }
    // 默认值填充
    if in.Spec.RetryPolicy == nil {
        out.Spec.RetryPolicy = &v1.RetryPolicy{
            MaxRetries:      3,
            BackoffSeconds:  5,
        }
    }
    return nil
}

版本转换陷阱： 不要在v1版本中删除v1alpha1已存在的必填字段，否则旧CR读取时会丢失数据。推荐使用x-kubernetes-preserve-unknown-fields: true保留未知字段，或通过Conversion Webhook做默认值填充。

3.3 字段校验与默认值

CRD的字段校验在API Server层拦截非法请求，避免无效数据进入etcd。默认值机制减少用户输入负担，同时保证重试队列与对账逻辑的确定性。

3.3.1 校验规则类型

类型校验：type: string/integer/boolean/array/object，配合format: date-time / int-or-string。
枚举校验：enum: ["Deployment", "StatefulSet"]，限制workload类型。
范围校验：minimum / maximum / minLength / maxLength，控制重试次数与超时时间。
模式校验：pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"，校验集群名称格式。
必填校验：required: ["sourceCluster", "targetCluster"]，确保关键字段非空。

3.3.2 默认值实现方式

CRD原生不支持OpenAPI default关键字（Kubernetes v1.16+实验性支持，但不推荐生产使用）。推荐通过以下两种方式实现默认值：

方式	实现位置	优点	缺点
Mutating Webhook	API Server准入阶段	统一默认值逻辑，用户无感知	增加API延迟，需部署Webhook服务
Operator Reconciler	控制器Reconcile循环	无需额外组件，逻辑简单	默认值写入status或annotation，spec不变

生产推荐： 使用Mutating Webhook为CRD设置默认值，确保spec字段在etcd中即包含完整默认值。重试队列的maxRetries和backoffSeconds必须通过Webhook填充，避免对账时出现nil指针。

// Mutating Webhook 默认值注入示例
func (w *MigrationRunDefaulter) Default(ctx context.Context, obj runtime.Object) error {
    mr := obj.(*v1.MigrationRun)
    if mr.Spec.RetryPolicy == nil {
        mr.Spec.RetryPolicy = &v1.RetryPolicy{
            MaxRetries:     3,
            BackoffSeconds: 5,
        }
    }
    if mr.Spec.TimeoutSeconds == 0 {
        mr.Spec.TimeoutSeconds = 600 // 默认10分钟超时
    }
    if mr.Spec.WorkloadRef.Kind == "" {
        mr.Spec.WorkloadRef.Kind = "Deployment"
    }
    return nil
}

3.4 CRD版本演进与字段校验SVG架构图

下图展示了CRD从v1alpha1到v1的版本演进路径，以及字段校验与默认值在API请求生命周期中的位置：

3.5 对账系统视角的CRD设计要点

跨环境迁移的重试队列与对账系统对CRD有额外要求，设计时需考虑以下字段：

幂等键（idempotencyKey）：在spec中增加idempotencyKey字段，用于重试去重，避免对账时重复处理。
对账时间戳：status中记录lastRequeueTime和reconciliationAttempts，支持对账系统判断重试间隔。
环境标签：通过labels标记environment: production/staging，便于跨环境迁移时过滤资源。
最终状态快照：status中保留finalSnapshot字段，记录迁移完成时的资源状态，用于对账校验。

对账优化建议： 在CRD的additionalPrinterColumns中增加Phase、RetryCount、Age列，方便运维人员通过kubectl get mr快速查看重试队列状态，无需频繁查询status详情。

additionalPrinterColumns:
- name: Phase
  type: string
  jsonPath: .status.phase
- name: Retries
  type: integer
  jsonPath: .status.retryCount
- name: Age
  type: date
  jsonPath: .metadata.creationTimestamp

3.6 字段校验与默认值实战对比

场景	无校验/默认值	有校验/默认值	对账影响
重试次数未设置	retryCount为nil，控制器panic	默认3次，控制器正常重试	避免对账死循环
workload类型错误	传入"CronJob"，控制器不识别	枚举校验拒绝，返回400	无效CR不入队
集群名称含特殊字符	etcd存储脏数据，对账匹配失败	正则校验拒绝非法名称	保证对账key一致性
超时时间负数	Reconcile循环死等	minimum:1 校验拒绝	避免队列阻塞

通过以上CRD设计规范、版本管理策略与字段校验默认值机制，Operator的跨环境迁移流水线能够在重试队列与对账系统中保持数据一致性，同时具备长期演进的灵活性。下一节将基于此CRD结构，深入实现Operator的控制器逻辑与重试队列调度。