Kubernetes CRD 设计与版本演进
CustomResourceDefinition(CRD)向 Kubernetes API 注册新的资源类型,Custom Resource(CR)是该类型的实例。CRD 解决的是 API 结构、校验、版本、存储和通用元数据,不会自动创建 Deployment,也不会凭空获得备份、升级或恢复逻辑;这些行为必须由控制器实现。
假设平台用AppRelease声明订单服务。用户把replicas从3改成5后,API接受请求只代表意图已保存;控制器创建了几个副本、几个已经Ready,要分别写进status。API契约必须让这几个状态能被区分。
先判断是否需要 CRD
CRD 适合表达低频、声明式、需要被控制器观察的平台意图,例如 DatabaseCluster、Application 或 Certificate。以下内容通常不适合写进 CR:
- 高频指标、日志、追踪或事件流。
- 业务交易、用户数据或大体量应用状态。
- 需要复杂自定义存储、子资源协议或非声明式交互的数据服务。
- 只为减少几份 YAML 重复而创建、却没有稳定 API 契约的包装层。
简单模板优先使用 Helm 或 Kustomize;需要更灵活 API 行为时再评估 Aggregated API。
定义结构与子资源
下面展示API结构,尚不包含控制器实现。CRD是集群级对象,AppRelease实例受namespace约束;安装CRD本身不会启动订单服务。
yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
name: appreleases.platform.example.com
spec:
group: platform.example.com
scope: Namespaced
names:
kind: AppRelease
plural: appreleases
singular: apprelease
shortNames: [ar]
versions:
- name: v1alpha1
served: true
storage: true
schema:
openAPIV3Schema:
type: object
required: [spec]
properties:
spec:
type: object
required: [image, replicas]
properties:
image:
type: string
minLength: 1
replicas:
type: integer
minimum: 1
maximum: 20
status:
type: object
properties:
observedGeneration:
type: integer
format: int64
readyReplicas:
type: integer
minimum: 0
replicas:
type: integer
minimum: 0
selector:
type: string
conditions:
type: array
x-kubernetes-list-type: map
x-kubernetes-list-map-keys: [type]
items:
type: object
required: [type, status, reason, message, lastTransitionTime]
properties:
type: { type: string }
status: { type: string, enum: ["True", "False", "Unknown"] }
reason: { type: string }
message: { type: string }
observedGeneration: { type: integer, format: int64 }
lastTransitionTime: { type: string, format: date-time }
subresources:
status: {}
scale:
specReplicasPath: .spec.replicas
statusReplicasPath: .status.replicas
labelSelectorPath: .status.selectorCRD 名称必须是 <plural>.<group>。schema 不只是文档,它在 API Server 端拒绝无效输入,并影响默认值、字段裁剪、Server-Side Apply 和客户端生成。
scale的实际副本数指向 status.replicas,不能用 readyReplicas 代替。控制器还应维护字符串selector,例如 app=order-api,且与它实际管理的Pod集合一致;对接HPA/VPA时必须提供selector。只暴露scale子资源不会自动创建Pod或实现伸缩,控制器仍需消费 spec.replicas。
未知字段可能被schema裁剪,也可能在严格字段校验下被拒绝;不要把“请求成功但字段不见了”当成字段已生效。对必须保留的自由结构要明确设计保留范围,避免把整个spec设成无校验字典。
Spec、Status 和 Conditions
spec 描述用户期望,status 描述控制器已经观察到的事实。控制器不应修改用户声明来表示执行结果。
Conditions 适合表达多个可独立判断的方面,例如 Ready、Progressing、Degraded。每个 Condition 应包含稳定的 type、机器可判断的 status 和 reason、供人阅读的 message,并记录 observedGeneration。
当 status.observedGeneration 小于 metadata.generation 时,现有 Ready 可能属于旧 spec。平台界面如果忽略这个差异,就会在新发布尚未处理时显示错误的绿色状态。
CEL 校验与不可变规则
OpenAPI schema 负责类型、必填、范围和格式;跨字段或更新前后比较可以使用 CRD 的 CEL validation rules。规则应快速、确定且不依赖外部网络。
以下为另一个包含弹性范围和区域的spec schema片段,放在该spec的 openAPIV3Schema.properties.spec 下;不是直接追加到上方只有image/replicas的示例:
yaml
type: object
required: [minReplicas, maxReplicas, region]
properties:
minReplicas: { type: integer, minimum: 1, maximum: 20 }
maxReplicas: { type: integer, minimum: 1, maximum: 20 }
region:
type: string
maxLength: 32
x-kubernetes-validations:
- rule: "self == oldSelf"
message: "region 创建后不可修改"
x-kubernetes-validations:
- rule: "self.minReplicas <= self.maxReplicas"
message: "minReplicas 不能大于 maxReplicas"这里self绑定到规则所在的schema位置:区域规则比较字符串自身,范围规则比较spec的两个字段。引用oldSelf的迁移规则用于更新;创建时仍由required和类型约束检查。对字符串、数组和嵌套遍历设置长度上限,避免校验成本无限增长。
业务上允许但暂时无法执行的状态,不应伪装成 schema 错误。例如外部云配额不足应由控制器写入 Condition,而不是要求 API Server 调用外部服务校验。
served、storage 与版本转换
一个 CRD 可以同时提供多个 API 版本,但任意时刻只能有一个 storage 版本。
| 字段 | 含义 |
|---|---|
served: true | 客户端可以通过该版本读写对象 |
storage: true | 新写入对象以该版本保存 |
status.storedVersions | 历史上仍可能存在于存储中的版本 |
把 storage 从 v1alpha1 切到 v1beta1 不会自动重写旧对象。迁移应按以下顺序进行:
- 新版本先
served: true,保持旧版本可用。 - 部署并验证双向转换;无 schema 变化可以使用
None,复杂变化需要 Conversion Webhook。 - 切换 storage 版本,新写入开始使用新表示。
- 用已验证的迁移程序枚举并重写历史对象,保留冲突重试和完成证据;仅GET不会改变存储版本。
- 检查所有客户端和控制器不再使用旧版本,再停止 served。
手工重写对象不会自动把旧条目从 status.storedVersions 中删掉;确认所有旧对象迁移完成后,再受控更新该状态。支持StorageVersionMigration的集群也可使用对应迁移控制器,并按其完成状态核对结果。不能先删除storedVersions条目来“制造迁移成功”,也不能在旧存储尚未清理时直接移除旧version定义。
Conversion Webhook 不可用可能阻断对应 CR 的读取、写入和删除。它需要高可用、短超时、证书轮换、监控和不依赖自身 CR 才能启动的部署路径。
复杂版本转换宜采用 hub-and-spoke:所有 served 版本先转换到一个内部 hub,再由 hub 转到目标版本。这样新增版本只需实现与 hub 的双向转换,不必维护每两个版本之间的组合。转换必须保留当前版本无法表达但未来往返仍需要的数据,否则旧客户端读写一次就可能造成字段丢失。
版本迁移实验至少包含:创建旧版本对象、通过新版本读取、修改后再用旧版本读取、切换 storage、重写历史对象、停用旧 served 版本,最后验证备份恢复。只测试“新对象能创建”无法证明兼容性。
删除与 Finalizer
Finalizer 把删除变成一个状态机。对象收到删除请求后出现 deletionTimestamp,控制器完成外部清理,再移除自己负责的 finalizer。
可靠实现需要:
- 清理动作可重复,外部资源不存在也视为成功。
- 清理失败写入 Condition/Event,并进入限速重试。
- 不阻塞与该对象无关的控制循环。
- 提供人工接管步骤,但不把“强删 finalizer”当常规恢复手段。
用户手工删除 finalizer 只会让 Kubernetes 忘记等待,不会自动清理云数据库、DNS 或密钥。
验证清单
bash
kubectl apply -f apprelease-crd.yaml
kubectl wait --for=condition=Established crd/appreleases.platform.example.com --timeout=60s
kubectl explain apprelease.spec
kubectl get crd appreleases.platform.example.com -o yaml
kubectl get apprelease -A -o custom-columns='NS:.metadata.namespace,NAME:.metadata.name,GEN:.metadata.generation,OBS:.status.observedGeneration,READY:.status.conditions[?(@.type=="Ready")].status'- 无效字段、越界值和跨字段错误会在 API Server 端被拒绝。
- 普通更新不能借主资源接口改写status;仅向状态维护者授予对应子资源更新权限。RBAC实际授权到身份,并不会按“是不是控制器进程”自动识别。
- 重复创建、修改、删除和控制器重启后对象仍能收敛。
- 新旧版本往返转换不丢字段,历史对象完成存储迁移。
- 删除外部依赖失败时对象保留证据,而不是永久无解释地 Terminating。
