13.2 CRD 与多版本转换
聚合层(13.1 节)适合「挂外部服务」。而自定义资源本身,K8s 给了更简单的路径:CRD——写一个 YAML 声明资源类型,apiserver 就提供完整的 REST API。本节解剖 CRD 的版本模型——尤其是存储版本与服务版本的区分。
CRD:声明一个资源类型
CRD(CustomResourceDefinition)是「定义自定义资源」的清单:
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: widgets.example.com
spec:
group: example.com
names:
plural: widgets
kind: Widget
versions:
- name: v1
served: true
storage: true
定义后,apiserver 自动提供:
/apis/example.com/v1/widgets → GET/POST/PUT/DELETE/LIST/WATCH
CRD 的魔力:不用写一行 Go 代码,就得到一个完整的、符合 K8s 语义的资源类型(乐观锁、watch、子资源都自动具备)。它比聚合层(要自己写 API 服务)简单得多——CRD 是「声明式地扩展 API」。
存储版本 vs 服务版本:核心区分
CRD 支持多个版本,其中有两个特殊角色:
| 角色 | 含义 |
|---|---|
storage: true(存储版本) | 对象实际落盘 etcd 用的版本 |
served: true(服务版本) | 客户端可见可调的版本 |
lab 的 CRD/Version 结构忠实建模:
type Version struct {
Name string
Served bool
Storage bool
ToStorage func(obj map[string]any) map[string]any
FromStorage func(obj map[string]any) map[string]any
}
关键规则:
- 只有一个 storage 版本:etcd 里的对象只用一种表示存储。
- 可以有多个 served 版本:客户端可以用任一 served 版本读写。
- 写请求:到达 served 版本 → 转成 storage 版本 → 落盘。
- 读请求:从 storage 版本 → 转回请求的 served 版本 → 返回。
为什么搞两套版本:存储的稳定性 vs 接口的演进。etcd 里的表示要稳定(迁移成本高),但对外版本要能演进(加字段、改字段)。「存储稳定、服务演进」是版本策略的核心。
版本转换:两个方向的映射
版本之间用转换函数互转。lab 的测试 TestCRDVersionConversion 演示:
// v1alpha1 用 spec.size;storage v1 用 spec.quantity
ToStorage: func(o map[string]any) map[string]any {
spec := o["spec"].(map[string]any)
spec["quantity"] = spec["size"] // size → quantity
delete(spec, "size")
return o
},
FromStorage: func(o map[string]any) map[string]any {
spec := o["spec"].(map[string]any)
spec["size"] = spec["quantity"] // quantity → size
delete(spec, "quantity")
return o
},
写路径:客户端提交 v1alpha1(带 size)→ ToStorage 转成 v1(带 quantity)→ 落盘。
读路径:从 etcd 读 v1 → FromStorage 转回 v1alpha1(带 size)→ 返回客户端。
两个方向都要定义:写要能转进 storage,读要能转回 served。转换是「字段映射」——不同版本表达同一概念的不同字段名/结构。
转换的分布式意义:客户端无感
版本转换对客户端是透明的:
| 客户端 | 看到的 | 实际存储 |
|---|---|---|
| 用 v1 写 | 提交 v1 对象 | 以 v1 落盘 |
| 用 v1alpha1 写 | 提交 v1alpha1 对象 | 转成 v1 落盘 |
| 用 v1alpha1 读 | 拿到 v1alpha1 表示 | 从 v1 转回 |
每个客户端用自己的版本读写,存储统一用 storage 版本——这正是「一个集群里新旧客户端共存」的基础:旧客户端用 v1alpha1、新客户端用 v1,共享同一份 etcd 数据,谁也不用改。
served 与未 served:版本的生命周期
版本有生命周期:
| 阶段 | served | 行为 |
|---|---|---|
| 活跃 | true | 客户端可用 |
| 废弃 | false | 客户端不可用(读写被拒) |
| 移除 | - | 从 CRD 删除该版本 |
lab 的 TestCRDUnserved:请求一个未 served 的版本(v2),ToStorage 报错——未 served 的版本拒绝写入。
版本下架的过程:先设为 served: false(客户端停用),迁移数据到新版本,再删除旧版本。这保证「停用版本」不破坏「已存数据」——数据还在(storage 版本没变),只是新请求不再用旧版本。
schema 校验:CRD 也能「声明式地把关」
CRD 不仅能提供 REST 端点,还能声明结构校验(openAPIV3Schema)——apiserver 在写请求落盘前校验对象结构:
spec:
versions:
- name: v1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
required: ["spec"]
properties:
spec:
type: object
required: ["size"]
properties:
size: { type: integer, minimum: 1 }
schema 让「合法对象」是声明出来的,不是写代码校验出来的:size 必须存在、必须是正整数——不满足的写请求被 apiserver 拒绝(400)。这是「声明式」精神在扩展 API 上的延续(13.1 节 CRD 不需要后端代码,校验也声明式)。
schema 与版本转换的关系:每个 served 版本可以有自己的 schema,转换函数在版本间搬字段——schema 管「这个版本的合法形状」,转换管「版本间的搬家」。两件事都在 apiserver 里完成,客户端无感(13.2 节「转换透明」的延续)。
三个常见误解
- 「每个版本各存一份」——错误。只有一个 storage 版本落盘;served 版本是「看/写的视图」。
- 「版本转换可以不做」——错误。served 版本 ≠ storage 版本时必须定义转换,否则读写报错。
- 「CRD 要写后端服务」——错误。CRD 由 apiserver 直接提供 REST,不需要写 API 服务(那是聚合层的事)。
本节 lab
本节验证 CRD 的版本转换与 served 约束:
cd private/labs/k8s-ctrl-lab
go test ./api -run 'TestCRDVersionConversion|TestCRDUnserved' -v
TestCRDVersionConversion:v1alpha1 写 → 转 storage v1 落盘 → 读回 v1alpha1——「存储稳定、服务演进」的双向转换。TestCRDUnserved:未 served 的版本拒绝写入——「版本生命周期」的边界。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。