## 一、四个词：GVK / GVR / 内部版本 / 存储版本

![ver-1-words.png](https://developer.qcloudimg.com/http-save/yehe-11479707/f3c394715cbad766b9bd637f0ed155b8.png)

*图 1：同一个对象在链路上有四副面孔。*

| 词 | 例子 | 用在哪 |
| --- | --- | --- |
| **GVK** | `apps/v1, Kind=Deployment` | 序列化、解码、转换 |
| **GVR** | `apps/v1, Resource=deployments` | URL 路由、RBAC、审计 |
| **内部版本** | `__internal`（不对外） | 校验、默认值、业务逻辑 |
| **存储版本** | etcd 里真正落盘的版本，如 `apps/v1` | 持久化 |

一次写请求走的是：

```
URL → 按 GVR 路由 → 解码成 GVK → 转内部版本 → 校验/准入 → 编码成存储版本 → etcd
```

一次读请求反过来：

```
etcd 读出存储版本 → 转内部 → 转成客户端要的版本 → 编码响应
```

**最容易错的一点：你写进去的版本，几乎从来不是 etcd 里存的版本。** 哪怕你用 `v1beta1` 提交，落盘的也可能一直是 `v1`——读的时候再实时转回去。

## 二、为什么需要"内部版本"

![ver-3-hub.png](https://developer.qcloudimg.com/http-save/yehe-11479707/0eed5de529c6ad18508f6916bdbf1346.png)

*图 3：把两两直连的 N×(N-1)/2 条，压缩成 N 条。*

假设有 `v1`、`v1beta2`、`v1beta1` 三个外部版本。如果两两直接转换，需要 3 种；有 10 个版本就是 45 种。

Kubernetes 用 **hub-and-spoke**：所有外部版本只和内部版本互转。N 个版本只需要 N 个转换器。

```go
// 每个 group 下都有 __internal，例如 pkg/apis/apps/install/install.go
utilruntime.Must(apps.AddToScheme(scheme))       // 内部版本
utilruntime.Must(appsv1.AddToScheme(scheme))     // 外部版本
utilruntime.Must(appsv1beta1.AddToScheme(scheme))
```

内部版本还有一个好处：**它是"字段最全"的**。某个字段只在 `v1beta1` 里存在，内部版本保留它，转成 `v1` 时再丢掉——这样跨版本读写的语义才有地方承载。

代价是：内部版本不能直接暴露给用户（没有 JSON tag），所有对外通信都必须经过一次转换。

## 三、转换发生在四个时刻

![ver-2-moments.png](https://developer.qcloudimg.com/http-save/yehe-11479707/fd1fc4550ebb7252aaeea457b09d95d9.png)

*图 2：解码、响应、落盘、watch——其中两个不写盘，但都要求无损。*

1. **解码**：外部版本 → 内部版本（读请求体）
2. **编码响应**：内部版本 → 客户端请求的版本
3. **写 etcd**：内部版本 → 存储版本
4. **watch 事件**：存储版本 → 每个客户端各自订阅的版本

第 4 点最容易被忽略：**两个客户端 watch 同一个对象的不同版本，收到的 JSON 是不一样的**。所以转换必须无损，否则 watch 的语义就破了。

## 四、内置类型与 CRD 的差别：hub 与直连

内置类型的转换函数由 `conversion-gen` 生成，手写的部分放在每个 group 的 `conversion.go` 里：

```go
// pkg/apis/apps/v1/conversion.go（节选）
func Convert_v1_Deployment_To_apps_Deployment(in *v1.Deployment, out *apps.Deployment, s conversion.Scope) error {
    // 字段级映射，或者调用自动生成的函数
    return autoConvert_v1_Deployment_To_apps_Deployment(in, out, s)
}
```

而 CRD **没有内部版本**。它的版本之间只有两条路：

- `strategy: None`：所有版本结构必须完全等价，只是 `apiVersion` 不同；
- `strategy: Webhook`：由你的服务做两两转换。

这是内置类型和自定义资源在架构上最大的不同：前者有"枢纽"，后者只有"直连"。所以 CRD 每加一个版本，转换 webhook 就要多处理一对关系。

## 五、无损转换与 roundtrip 测试

既然转换必须无损，Kubernetes 用模糊测试来保证：任意对象 `v1beta1 → internal → v1beta1`，必须和原始对象逐字段相等。

```go
// pkg/api/testing/roundtrip.go（节选）
roundtrip.RoundTripTestForScheme(t, scheme, func() runtime.Object { ... })
```

这套测试能抓住两类问题：

- **丢字段**：新字段加在外部版本，内部版本没加，转换一圈就没了；
- **默认值污染**：转换过程中被塞了默认值，再转回去就多出了字段。

## 六、版本优先级与弃用策略

多个版本同时 `served: true` 时，谁排在前面？规则是：**稳定性优先（GA > beta > alpha），同级别比版本号**。`kubectl get --raw /apis/apps` 返回的 `preferredVersion` 就是这个顺序的第一个。

弃用承诺：

| 级别 | 承诺 |
| --- | --- |
| **alpha**（`v1alpha1`） | 随时可能删、可能改，默认关闭 |
| **beta**（`v1beta1`） | 不会删字段，但可能改语义；弃用后至少保留 3 个 release / 9 个月 |
| **GA**（`v1`） | 永不删除；弃用后至少 12 个月 / 3 个 release |

这条政策决定了"版本转换"不是可选项：**客户端不可能和集群同步升级**，老客户端会一直用老版本访问新集群。所以每个版本都得能读、能写、能转。

## 七、版本时间线

| 时间 | 版本 | 变化 |
| --- | --- | --- |
| 2015 | 1.0 | 外部版本 + `__internal` + 存储版本的模型定型 |
| 2016 | 1.2 | Third Party Resource（TPR） |
| 2017 | 1.7 | CRD 取代 TPR |
| 2018 | 1.13 | CRD 转换 webhook alpha |
| 2019 | 1.16 | `apiextensions.k8s.io/v1` GA，structural schema 强制 |
| 2022 | 1.25 | 内置类型 CSI 迁移完成（存储层的"版本转换"） |

## 八、排障清单

| 现象 | 先查什么 |
| --- | --- |
| `no matches for kind` | CRD 没装，或该版本 `served: false` |
| 写入成功但读出来字段变少 | structural schema 剪掉了未知字段；用 `x-kubernetes-preserve-unknown-fields` |
| 升级后老客户端报 404 | 旧版本被移除；看 `kubectl api-resources` 里还有没有 |
| `conversion webhook failed` | 转换服务不可达、`caBundle` 过期、`conversionReviewVersions` 不匹配 |
| 切换存储版本后读性能下降 | 存量对象仍是旧编码，读时实时转换；跑迁移工具重写 |
| 同一对象两个客户端看到的字段不同 | 正常现象：各自版本不同，转换结果不同 |

## 九、设计追问

**1. 为什么内置类型要有内部版本，CRD 却没有？**
内置类型是 Go 结构体，需要一个"最全"的中间表示来承载跨版本字段；CRD 是 JSON，转换发生在 schema 层，不需要中间类型。代价是 CRD 只能把转换交给 webhook，不能写字段级逻辑在 apiserver 里。

**2. 为什么存储版本只能有一个？**
多个存储版本意味着同类对象在 etcd 里有不同编码，读的时候要先判断"这条是什么版本"，复杂度指数上升。一个存储版本 + 读时转换，是更简单的模型。

**3. 为什么转换必须无损？**
因为 watch。客户端拿到的每个事件都要能被它理解的版本正确解释；丢一个字段，控制器就可能基于错误状态做决策。

**4. 为什么弃用期要按"月或 release"取更长？**
因为集群升级和客户端升级是两条独立的时间线。只按 release 算，对一年才升级一次的客户不公平；只按月算，对跟进快的客户又太慢。

---

**一句话收尾**：版本转换是把 N×N 的兼容矩阵压成 N 的工程手段。它的全部复杂度，都来自一个现实约束——**客户端永远不会和集群同时升级**。

---

## 参考资料

1. Kubernetes 文档：[API Concepts](https://kubernetes.io/docs/reference/using-api/api-concepts/)、[Deprecation Policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/)
2. Kubernetes 源码（v1.34.0）：`staging/src/k8s.io/apimachinery/pkg/runtime/`、`pkg/apis/*/install/`
3. Kubernetes 文档：[Custom Resource Definitions](https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)

> 本文为原创内容，基于 Kubernetes v1.34.0 源码整理；版本号以对应 release note 为准。

最容易错的一点：你写进去的版本，几乎从来不是 etcd 里存的版本。 哪怕你用 v1beta1 提交，落盘的也可能一直是 v1——读的时候再实时转回去。

kubernetes 进阶知识-API 版本转换：把 N×N 的兼容矩阵压成 N

前面几篇讲的都是"请求怎么被处理"，这一篇讲一个更底层的机制：同一个对象，在不同版本、不同客户端、不同存储之间，是怎么保持一致的。
结论先给：Kubernetes 用一个不对外暴露的"内部版本"做枢纽，把 N 个外部版本之间的两两转换，压缩成 N 条转换。源码引用基于 **v1.34.0**。

运维开发工程师

编程语言

Kubernetes版本转换机制核心解析：内部版本作为枢纽，将N×N兼容矩阵压缩为N条转换路径。外部版本仅用于API交互，存储版本独立落盘，读时实时转换。内置类型与CRD架构差异显著，转换必须无损以保障watch语义。掌握版本优先级、弃用策略及转换测试，是理解k8s多版本兼容的关键。

代码解释

Kubernetes

路由

JSON

让每一个 Agent，都跑在云上

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

kubernetes 进阶知识-API 版本转换：把 N×N 的兼容矩阵压成 N-腾讯云开发者社区-腾讯云

kubernetes 进阶知识-API 版本转换：把 N×N 的兼容矩阵压成 N

kubernetes 进阶知识-API 版本转换：把 N×N 的兼容矩阵压成 N

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐