《Kubernetes 分布式系统原理深入解析》13.2 CRD 与多版本转换

比聚合层更简单的扩展路径是 CRD(CustomResourceDefinition):只写 YAML 声明一个资源类型,apiserver 就提供完整的 REST 端点。CRD 的多版本是关键语义:一个 storage version 落盘 etcd,多个 served version 对外可见,版本间用转换函数互转。本节解剖 CRD 的存储/服务版本模型与版本转换。lab 用 api/crd.go 验证 v1alpha1 与 v1 的转换。

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
}

关键规则:

  1. 只有一个 storage 版本:etcd 里的对象只用一种表示存储。
  2. 可以有多个 served 版本:客户端可以用任一 served 版本读写。
  3. 写请求:到达 served 版本 → 转成 storage 版本 → 落盘。
  4. 读请求:从 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 的版本拒绝写入——「版本生命周期」的边界。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图