Kubernetes CRD

真实场景看 cert-manager:它向集群注册了一个叫 Certificate 的自定义资源。业务用户要 HTTPS 证书,不写任何签发逻辑,只 apply 一段声明:

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: my-tls
spec:
  secretName: my-tls
  dnsNames: [api.example.com]
  issuerRef: { name: letsencrypt, kind: ClusterIssuer }

几秒后 controller 自动向 Let's Encrypt 申请、做 ACME 校验、把证书写进 my-tls Secret。业务用户从头到尾没碰 ACME 协议——这就是 CRD 的价值:把『一个领域的操作』变成『声明式对象』,再交给 controller 履约。你也完全可以为自己业务发明一个名词,重复这个模式。

造一个叫 Website 的 CRD,只有三部分:names(怎么称呼它)、scope(集群级还是命名空间级)、schema(它长什么样)。

01apiVersion: apiextensions.k8s.io/v1
02kind: CustomResourceDefinition
03metadata:
04  name: websites.example.com
05spec:
06  group: example.com
07  names: { plural: websites, singular: website, kind: Website }
08  scope: Namespaced
09  versions:
10    - name: v1
11      served: true
12      storage: true
13      schema:
14        openAPIV3Schema:
15          type: object
16          properties:
17            spec:
18              type: object
19              properties:
20                image: { type: string }
21                replicas: { type: integer, minimum: 1 }

kubectl apply -f 之后,集群就认识 websites 这个名词了:kubectl get websites 是空列表;再 kubectl apply -f 一个 website.yaml(里面写 spec.image、spec.replicas),就创建出一条自定义对象,和创建 Pod 一样能 get/describe/delete。注意:到这里还没有任何 Pod 会跑起来——CRD 只定义了『名词和它长什么样』,真正干活的人(盯着它 reconcile 的 controller)还没出场。

Controller 是盯着 Website 对象、把现实拨向 spec 的程序。用 kubebuilder 起脚手架:

kubebuilder init --domain example.com
kubebuilder create api --group web --version v1 --kind Website

生成的骨架里,Reconcile 函数是这么一段循环(Website 增删改、或它管理的 Deployment 变化,都会触发一次):

func (r *WebsiteReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
  var w webv1.Website
  if err := r.Get(ctx, req.NamespacedName, &w); err != nil {
    return ctrl.Result{}, client.IgnoreNotFound(err)
  }
  // 确保 spec.image + spec.replicas 对应的 Deployment 存在:没有就建,规格不对就改
  // 把观察结果写回 status,比如 Ready: True
  return ctrl.Result{}, r.Status().Update(ctx, &w)
}

make install 把 CRD 装进集群,make run 在本地跑 controller。然后 apply 一个 Website:controller 侦测到新对象,生成对应 Deployment;删除 Website,它再回收资源。这就是『契约是 CRD,履约是 controller』的全部含义。

光有 Reconcile 还不够生产用。status 条件:把健康状态写成 conditions 数组(像 Pod 的 Ready 那样),kubectl get website 和 UI 才能读到『现在到底咋样』,否则别人只能猜。finalizer:在对象删除前先做清理(比如回收云盘),在 metadata.finalizers 里挂一个名字,Reconcile 里做完清理再移除它——finalizer 没移除,对象永远卡在 Terminating。admission webhook:复杂校验和默认值注入用 validating/mutating webhook,能跨字段校验、能自动填默认值,比内联 schema 强得多;而 CEL 校验(1.25+)把一部分规则直接写进 schema,连 webhook 服务都不用起。

CRD 的 schema 一旦成为 storage 版本,就是持久承诺:etcd 里已存的对象按旧 schema 序列化。想改结构,要么加新版本(served + storage 切过去),要么写 conversion webhook 在版本间转换。所以社区惯例:v1alpha1 明示『随时推翻』,敢改 schema;v1 才承诺稳定。升级 CRD 时最痛的坑:改 storage version 后老对象读不出来,或 schema 收紧导致老对象校验失败。多版本共存 + conversion 是唯一正路。