3. API 版本转换机制：内部版本与外部版本、转换函数、版本间字段映射与默认值填充

Kubernetes 的 API 版本转换机制是控制平面实现多版本共存与平滑演进的核心枢纽。当集群中同时存在 v1、v1beta1、v1alpha1 等多个 API 版本时，APIServer 必须能够将任意请求版本转换为统一的内部版本进行处理，再根据客户端期望的版本序列化响应。这一过程依赖内部版本、外部版本、转换函数、字段映射与默认值填充四大要素。

3.1 内部版本与外部版本

Kubernetes 采用“双版本”资源模型：

• 内部版本（Internal Version / Hub Version）：存储在 etcd 中的规范版本，通常对应 __internal 包，不对外暴露。所有版本转换都以内部版本为枢纽。
• 外部版本（External Version）：客户端通过 REST API 交互的版本，如 v1、v1beta1。每个外部版本都有独立的 Go 类型定义。

3.2 转换函数（Convert）

转换函数是版本转换的执行单元。Kubernetes 使用 conversion-gen 代码生成器自动生成大部分转换函数，开发者只需在特定场景下手动实现 Convert() 方法。

3.2.1 自动生成 vs 手动实现

3.2.2 转换函数注册流程

1. 定义转换函数：在 zz_generated.conversion.go 或手动文件中编写 Convert_<internal>_To_<external>。
2. 注册到 Scheme：通过 AddConversionFunc() 将函数注册到全局 Scheme。
3. APIServer 调用：请求处理时，Scheme.Convert() 根据源/目标类型查找注册表并执行转换。

// 手动实现转换函数示例
func Convert_foo_Deployment_To_v1_Deployment(in *foo.Deployment, out *v1.Deployment, s conversion.Scope) error {
    // 调用自动生成的基础转换
    if err := autoConvert_foo_Deployment_To_v1_Deployment(in, out, s); err != nil {
        return err
    }
    // 手动处理字段映射：内部版本 Replicas 默认值为 1
    if in.Spec.Replicas == nil {
        out.Spec.Replicas = pointer.Int32(1)
    }
    return nil
}

// 注册到 Scheme
func RegisterConversions(s *runtime.Scheme) error {
    if err := s.AddConversionFunc(
        (*foo.Deployment)(nil),
        (*v1.Deployment)(nil),
        Convert_foo_Deployment_To_v1_Deployment,
    ); err != nil {
        return err
    }
    return nil
}

3.3 版本间字段映射与默认值填充

版本演进过程中，字段名、类型、结构层次可能发生变化。字段映射与默认值填充确保不同版本间的数据完整性和语义一致性。

3.3.1 字段映射模式

3.3.2 默认值填充机制

默认值填充发生在两个阶段：

• 转换时填充：在 Convert() 函数中，当源版本字段为 nil 或零值时，为目标版本设置默认值。
• 准入时填充：通过 MutatingAdmissionWebhook 或内置的 defaulting 函数，在资源持久化前补充默认值。

3.4 版本转换的完整生命周期

以 Deployment 资源为例，一次完整的版本转换流程如下：

1. 客户端发起请求：使用 v1beta1 版本创建 Deployment。
2. APIServer 解码：根据 Content-Type 将请求体反序列化为 v1beta1.Deployment 对象。
3. 准入控制：执行 Mutating 和 Validating Admission，包括默认值填充。
4. 版本转换：调用 Scheme.Convert()，将 v1beta1.Deployment 转为内部版本 foo.Deployment。
5. 字段映射：在转换函数中处理字段重命名、类型转换、默认值填充。
6. 存储到 etcd：内部版本序列化为 Protobuf 或 JSON 写入 etcd。
7. 读取时反向转换：从 etcd 读取内部版本，根据客户端请求的 Accept 版本转为对应外部版本。
8. 响应客户端：返回指定版本的资源对象。

3.5 版本转换的常见陷阱与避坑指南