4. 自定义资源定义（CRD）版本管理

自定义资源定义（CRD）是 Kubernetes 扩展能力的基础。随着业务迭代，CRD 的 API 版本也需要演进。Kubernetes 从 1.16 开始要求 CRD 必须支持多版本管理，包括版本转换、存储版本与 serving 版本的策略选择。本章深入剖析 CRD 版本管理的核心机制与最佳实践。

4.1 CRD 多版本支持的核心概念

CRD 多版本支持允许一个自定义资源同时存在多个 API 版本（如 v1alpha1、v1beta1、v1），客户端可以按需使用不同版本进行读写操作。Kubernetes 在 etcd 中只存储一个版本（存储版本），但通过版本转换 Webhook 或内置转换策略，将其他版本的数据转换为存储版本后再持久化。

4.2 版本转换 Webhook 配置

当 CRD 的多个版本之间字段结构差异较大时，内置的 None 转换策略无法满足需求，必须配置版本转换 Webhook。Webhook 负责在请求到达 API 服务器时，将请求版本的数据转换为存储版本的数据格式。

4.2.1 Webhook 配置示例

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: crontabs.stable.example.com
spec:
  group: stable.example.com
  names:
    kind: CronTab
    listKind: CronTabList
    plural: crontabs
    singular: crontab
  scope: Namespaced
  versions:
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              cronSpec:
                type: string
              image:
                type: string
  - name: v1beta1
    served: true
    storage: false
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              cron:
                type: string
              containerImage:
                type: string
  conversion:
    strategy: Webhook
    webhook:
      conversionReviewVersions: ["v1", "v1beta1"]
      clientConfig:
        service:
          namespace: default
          name: crd-conversion-webhook
          path: /convert
        caBundle: <base64-encoded-ca-cert>

4.2.2 Webhook 工作原理

4.3 存储版本与 Serving 版本选择策略

存储版本和 serving 版本的选择直接影响集群的兼容性、升级成本和运维复杂度。以下是三种常见策略及其适用场景。

4.3.1 存储版本切换注意事项

• 存储版本变更后，etcd 中已有对象不会自动转换。需要手动或通过控制器触发重新写入，才能将旧存储版本的对象转换为新版本。
• 转换 Webhook 必须处理所有 serving 版本到存储版本的转换。如果 Webhook 只实现了部分版本转换，会导致请求失败。
• 建议在 CRD 定义中为每个版本提供完整的 OpenAPI v3 schema，确保 API 服务器能正确校验不同版本的请求。

4.4 版本转换的两种模式对比

4.5 版本管理最佳实践

1. 版本命名规范： 遵循 v<major><minor><alpha/beta/stable> 模式，如 v1alpha1、v1beta1、v1。
2. 存储版本选择： 始终选择最稳定、最成熟的版本作为存储版本。避免将 alpha 或 beta 版本设为存储版本。
3. 转换 Webhook 健壮性： 为 Webhook 配置 failurePolicy: Fail 以确保数据一致性；同时设置合理的 timeoutSeconds（默认 30s）。
4. 版本废弃流程： 先设置 served: false 停止 serving，确认无客户端使用后再从 CRD 定义中移除该版本。
5. 自动化测试： 为每个版本编写转换测试用例，覆盖正向转换和反向转换，确保数据不丢失。

4.6 常见问题与排查