2. Kubernetes 存储版本机制：理解 API 版本、存储版本、内部版本的概念与关系

在 Kubernetes 中，资源对象（如 Deployment、Pod、CustomResource）的版本管理并非单一维度。为了支持 API 演进、向后兼容以及数据持久化，Kubernetes 引入了三个核心版本概念：API 版本、存储版本 和 内部版本。理解这三者的关系，是掌握存储版本漂移检测的前提。

2.1 三个核心版本的定义与职责

2.2 三者的关系与数据流

下图展示了用户请求从提交到持久化，再到读取的完整数据流，清晰呈现了三个版本之间的协作关系。

2.3 存储版本的特殊性与漂移风险

存储版本是 etcd 中数据的“真实来源”，其特殊性体现在：

• 唯一性： 每个资源类型（GroupVersionResource）只能有一个存储版本，由 API Server 启动时通过 --storage-versions 或代码注册决定。
• 持久性： 一旦数据写入 etcd，其版本格式就固定下来，除非显式迁移。
• 升级敏感性： 集群升级时，如果旧存储版本被废弃，API Server 会自动将存储版本迁移到新版本，但迁移过程可能失败或遗留旧数据。

2.4 版本转换的代码示例

以下代码展示了 Kubernetes API Server 内部如何通过内部版本进行转换。这是理解存储版本漂移检测机制的基础。

// 伪代码：API Server 的版本转换流程
// 1. 用户提交一个 apps/v1 的 Deployment
deploymentV1 := &appsv1.Deployment{...}

// 2. 转换为内部版本（__internal）
internalDeployment := &appsapi.Deployment{}
scheme.Convert(deploymentV1, internalDeployment, nil)

// 3. 从内部版本转换为存储版本（假设存储版本是 apps/v1）
storageDeployment := &appsv1.Deployment{}
scheme.Convert(internalDeployment, storageDeployment, nil)

// 4. 序列化并写入 etcd
etcdClient.Put("/registry/deployments/default/my-deployment", storageDeployment)

// 5. 读取时反向操作
// 从 etcd 读取存储版本数据
// 转换为内部版本
// 再转换为用户请求的 API 版本

2.5 版本关系总结表