3. CRD 版本管理：多版本支持与版本转换

在 Kubernetes 生态中，自定义资源（CR）的 API 版本管理是 Operator 长期运维的核心能力。随着资源定义演进，你可能需要同时维护 v1alpha1（实验版）、v1beta1（测试版）和 v1（稳定版）等多个版本。本章深入剖析多版本支持机制、存储版本与服务版本的区别，以及 Conversion Webhook 的实现原理。

3.1 多版本支持的必要性

Kubernetes 要求 CRD 在升级时不能破坏现有客户端。多版本支持允许你：

• 渐进式演进：新版本发布后，旧版本客户端仍可正常工作。
• 平滑迁移：用户可以在不修改 YAML 文件的情况下逐步迁移到新 API。
• 兼容性保障：通过版本转换，确保存储数据与最新服务版本一致。

3.2 存储版本与服务版本的核心区别

这是 CRD 版本管理中最容易混淆的概念。理解两者的区别是正确配置多版本的前提。

3.3 版本转换机制：Conversion Webhook

当客户端请求的版本与存储版本不一致时，Kubernetes 需要执行版本转换。转换方式有两种：

• None（默认）：仅支持相同 schema 的版本，字段名和类型必须完全一致。
• Webhook：通过外部 HTTP 服务实现自定义转换逻辑，支持不同 schema 的版本。

Conversion Webhook 的工作流程如下：

3.4 配置多版本 CRD 示例

以下是一个完整的 CRD 定义，包含 v1alpha1、v1beta1 和 v1 三个版本，并启用 Conversion Webhook：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: applications.example.com
spec:
  group: example.com
  names:
    kind: Application
    plural: applications
    singular: application
  scope: Namespaced
  versions:
  - name: v1alpha1
    served: true
    storage: false
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              name:
                type: string
              replicas:
                type: integer
  - name: v1beta1
    served: true
    storage: false
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              displayName:
                type: string
              count:
                type: integer
  - name: v1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              displayName:
                type: string
              replicas:
                type: integer
  conversion:
    strategy: Webhook
    webhook:
      conversionReviewVersions: ["v1", "v1beta1"]
      clientConfig:
        service:
          namespace: operator-system
          name: conversion-webhook-service
          path: /convert
        caBundle: <base64-encoded-ca-cert>

3.5 实现 Conversion Webhook 服务

Webhook 服务需要实现 ConversionReview 接口。以下是一个 Go 语言的核心处理逻辑片段：

func (h *ConversionHandler) Handle(ctx context.Context, req *admissionv1.ConversionReview) (*admissionv1.ConversionReview, error) {
    var convertedObjects []runtime.RawExtension

    for _, obj := range req.Request.Objects {
        // 反序列化请求对象
        unstructuredObj := &unstructured.Unstructured{}
        if err := json.Unmarshal(obj.Raw, unstructuredObj); err != nil {
            return nil, err
        }

        // 根据目标版本执行转换
        targetVersion := req.Request.DesiredAPIVersion
        switch targetVersion {
        case "example.com/v1":
            convertedObj := convertToV1(unstructuredObj)
            convertedObjects = append(convertedObjects, runtime.RawExtension{Object: convertedObj})
        case "example.com/v1beta1":
            convertedObj := convertToV1beta1(unstructuredObj)
            convertedObjects = append(convertedObjects, runtime.RawExtension{Object: convertedObj})
        case "example.com/v1alpha1":
            convertedObj := convertToV1alpha1(unstructuredObj)
            convertedObjects = append(convertedObjects, runtime.RawExtension{Object: convertedObj})
        }
    }

    return &admissionv1.ConversionReview{
        Response: &admissionv1.ConversionResponse{
            UID:              req.Request.UID,
            ConvertedObjects: convertedObjects,
            Result:           metav1.Status{Status: metav1.StatusSuccess},
        },
    }, nil
}

3.6 版本转换的常见故障与排查

3.7 存储版本迁移策略

当你需要更改存储版本时（例如从 v1beta1 迁移到 v1），推荐以下步骤：

1. 准备阶段：确保所有版本都支持双向转换，Webhook 已稳定运行。
2. 标记新存储版本：在 CRD 中将 v1 的 storage: true，同时将旧版本设为 storage: false。
3. 数据迁移：编写脚本遍历所有现有 CR 对象，通过 API Server 读取后重新写入，触发自动转换。
4. 验证：使用 kubectl get <resource> -o yaml 确认所有对象已转换为新存储版本。
5. 清理：确认无误后，可以移除旧版本的服务版本（设置 served: false）。