3、版本转换原理：Conversion Webhook 的工作流程与配置

当 CRD 存在多个版本（如 v1alpha1、v1beta1、v1）时，Kubernetes API Server 需要一种机制来在不同版本之间转换存储对象。Conversion Webhook 正是承担这一职责的核心组件，它作为 API Server 与 Operator 之间的 HTTP 回调，负责将请求中的资源版本转换为存储版本，或从存储版本转换为响应版本。

3.1 为什么需要 Conversion Webhook

CRD 的版本迁移面临一个根本矛盾：存储版本只有一个，但客户端可能请求任意版本。Kubernetes 要求所有 CRD 必须指定一个版本作为存储版本（storage version），所有写入 etcd 的数据都使用该版本。当客户端读取或写入非存储版本时，API Server 必须进行版本转换。

Kubernetes 提供两种转换策略：None（无转换，仅允许存储版本被请求）和 Webhook（通过外部服务转换）。对于生产级 Operator，Webhook 策略是唯一可行的选择。

3.2 Conversion Webhook 工作流程

Conversion Webhook 的完整请求-响应流程分为五个阶段，每个阶段都有明确的职责和边界。

3.3 ConversionReview 对象结构

Conversion Webhook 的通信载体是 ConversionReview 对象，它属于 apiextensions.k8s.io/v1 API 组。该对象包含请求和响应两部分：

// ConversionReview 是 Webhook 请求/响应的顶层对象
apiVersion: apiextensions.k8s.io/v1
kind: ConversionReview
request:                    // API Server → Webhook
  uid: "a1b2c3d4-e5f6-..."
  desiredAPIVersion: "example.io/v1"    // 目标版本
  objects:                              // 需要转换的对象列表
    - apiVersion: example.io/v1alpha1
      kind: MyResource
      metadata:
        name: my-resource-1
      spec:
        oldField: "value1"
    - apiVersion: example.io/v1alpha1
      kind: MyResource
      metadata:
        name: my-resource-2
      spec:
        oldField: "value2"
response:                   // Webhook → API Server
  uid: "a1b2c3d4-e5f6-..." // 必须与 request.uid 一致
  convertedObjects:         // 转换后的对象列表
    - apiVersion: example.io/v1
      kind: MyResource
      metadata:
        name: my-resource-1
      spec:
        newField: "value1"
    - apiVersion: example.io/v1
      kind: MyResource
      metadata:
        name: my-resource-2
      spec:
        newField: "value2"
  result:                   // 转换结果状态
    status: "Success"       // 或 "Failure"
    message: "conversion succeeded"

3.4 Webhook 配置清单

在 CRD 定义中启用 Conversion Webhook 需要在 spec.conversion 字段中配置。以下是完整的配置示例：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: myresources.example.io
spec:
  group: example.io
  names:
    kind: MyResource
    plural: myresources
  versions:
    - name: v1alpha1
      served: true
      storage: false
      schema: ...
    - name: v1beta1
      served: true
      storage: false
      schema: ...
    - name: v1
      served: true
      storage: true       # 存储版本
      schema: ...
  conversion:
    strategy: Webhook
    webhook:
      conversionReviewVersions: ["v1"]   # 支持的 ConversionReview 版本
      clientConfig:
        service:
          namespace: operator-system
          name: operator-webhook-service
          path: /convert
          port: 443
        caBundle: <base64-encoded-ca-cert>  # 用于 TLS 验证
      matchPolicy: Exact                    # 或 Equivalent

3.5 配置字段详解

3.6 Webhook 服务端实现要点

Operator 的 Webhook 服务端需要处理 /convert 路径的 HTTP POST 请求，并实现以下核心逻辑：

1. 请求解析： 反序列化 HTTP Body 为 ConversionReview 对象，验证 request.uid 和 request.desiredAPIVersion。
2. 版本映射： 根据 desiredAPIVersion 确定目标版本，遍历 request.objects 中的每个对象。
3. 字段转换： 执行版本间的字段映射逻辑，包括字段重命名、类型转换、默认值填充、字段删除等。
4. 响应构造： 将转换后的对象填入 response.convertedObjects，设置 response.result.status 为 Success 或 Failure。
5. 错误处理： 如果某个对象转换失败，应在 response.result 中返回错误信息，并设置 status: "Failure"。

3.7 版本转换的幂等性与兼容性

Conversion Webhook 必须保证 幂等性：对同一对象反复执行版本转换，结果应保持一致。此外，Webhook 应支持 前向兼容 和 后向兼容：

• 前向兼容： 旧版本对象转换为新版本时，新版本中新增的字段应填充默认值。
• 后向兼容： 新版本对象转换为旧版本时，旧版本不存在的字段应被丢弃或映射到 annotation。
• 无损转换： 对于关键业务字段，应避免在转换过程中丢失信息。可以使用 annotation 暂存无法映射的字段。

3.8 生产环境最佳实践

Conversion Webhook 是 CRD 版本迁移的核心基础设施，它决定了 Operator 能否平滑演进 API 版本而不中断现有客户端。正确理解其工作流程和配置细节，是构建生产级 Operator 的必备能力。