装完 CRD 集群毫无反应?K8s 扩展模型是个套娃

2026-10-07 21:18:1994 阅读量

装完 CRD,集群毫无反应:K8s 扩展是个套娃,你只拿到了一半

CRD + 控制器:K8s 扩展模型|K8s 深入理解

相关服务:美国站群服务器

第一次玩 CRD 的人,几乎都经历过同一个时刻:kubectl apply 完一个 CustomResourceDefinition,返回 created,然后——什么都没发生。不报错、不干活、status 永远是空的。

更早入坑的那批人,则在 Operator 上撞过另一堵墙:Reconcile 明明写对了,日志却无限刷屏,同一个对象一分钟被调谐几十次。

这两个现象是同一个根源。K8s 的扩展模型是个套娃:CRD 和控制器是解耦的两半,apply CRD 只是把一个"名词"登记进 apiserver,"动词"从来不会随 CRD 附赠。今天把这只套娃逐层拧开,讲五件事:控制环、幂等、schema 校验、ServiceMonitor 真实链路,以及——什么时候不该写 Operator。读完能带走:一张控制环骨架图、一套可直接复制执行的验证命令、一张"该不该写 Operator"的判断表。

全景:四个扩展点,各改请求链的一段

先回忆 apiserver 的写请求链:认证 → 鉴权 → 变更准入(mutating)→ 对象 schema 校验 → 验证准入(validating)→ 落 etcd。注意准入拆成两道:mutating 在校验前改对象(含内置默认值填充),validating(ValidatingWebhook / CEL 策略)在校验后拒绝。想让集群"原生理解"一个新东西,K8s 给的不是插件槽,而是链条上四段可以各自挂载的位置:

扩展点改哪一段一句话分工
CRD对象层:登记新类型加"名词"
自定义控制器控制器层:list-watch 并调谐加"动词"
聚合 API读路径:整个 group 交给外部进程 serve换掉一整本词典
准入扩展写路径进门检查管"做成什么样"

Operator 不是第五种扩展点,官方口径很朴素:用 CRD 管理复杂有状态应用的软件,控制器把人类运维的知识编码了进去。拆开是三件套——CRD 描述"应用期望长什么样"(版本、副本、备份策略),控制器把部署、扩缩容、failover、备份、升级变成 reconcile 里的分支,交付则把 CRD 清单和控制器 Deployment 打包成 Helm chart,装完即得。本文主角就是它。

聚合 API 为什么存在?因为 metrics.k8s.io 这种"数据是派生的、易变的瞬时值"不适合走 CRD 落 etcd,那是另一个故事,这里按下不表。

这张表也解释了一个常见困惑:为什么有人把"注入 sidecar"叫扩展 K8s,有人把"写个 Operator"叫扩展 K8s——他们改的是链条上不同的段,不冲突。

CRD 只是名词:但注册完,免费送一整套 API 待遇

CRD(CustomResourceDefinition)描述"一种新对象长什么样";照着它创建出来的实例叫 CR(Custom Resource)。注册之后,etcd 存储、REST 端点、RBAC、label/annotation、finalizer、ownerReferences、kubectl get/explain 全部自动获得——这就是"K8s 原生"的含义。

一段可直接跑的完整演示:

kubectl apply -f - <<'EOF'
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: maintenancewindows.ops.example.com   # 固定格式:<复数>.<group>
spec:
  group: ops.example.com
  scope: Namespaced
  names:
    plural: maintenancewindows
    kind: MaintenanceWindow
    shortNames: ["mw"]
  versions:
  - name: v1
    served: true
    storage: true                            # 多版本并存只能有一个 storage 版本
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              windowStart:
                type: string
              mode:
                type: string
                enum: ["drain", "cordon-only"]  # 值域校验
                default: "drain"
              nodes:
                type: array
                items:
                  type: string
            required: ["windowStart"]
    subresources:
      status: {}                             # spec/status 分离读写
EOF
# 注册立刻生效,不需要重启任何组件
kubectl wait --for=condition=Established crd/maintenancewindows.ops.example.com --timeout=30s

建一个实例,然后看它的 status:

kubectl apply -f - <<'EOF'
apiVersion: ops.example.com/v1
kind: MaintenanceWindow
metadata:
  name: kernel-patch-0919
spec:
  windowStart: "2026-09-19T22:00:00+08:00"
  nodes: ["worker1"]
EOF
kubectl get mw kernel-patch-0919 -o jsonpath='{.status}'; echo
# 输出:空 —— 数据进了 etcd,但没有任何控制器写 status

此刻没有任何控制器认识它。对象安静地躺在 etcd 里,status 恒为空。数据模型(CRD)与自动化逻辑(控制器)是解耦的两半——这就是"装了 Gateway API 的 CRD,还要再装 Envoy Gateway 实现"的原因:GatewayClass 需要一个控制器来认领。

顺带两句。CR 沿用 K8s 的三套通用机制:generation/observedGeneration(控制器把它抄进 status,外界才能判断"期望到达了吗")、finalizer、ownerReferences(CR 作属主,级联删除自动完成)。另外自定义资源同样要配 RBAC——Role 里 apiGroups 填你的 group,新类型不免检。

schema:说了算的留下,没说的静默剪掉

CRD 的 openAPIV3Schema 不只是文档,它是 apiserver 里的执法者:

机制行为什么时候关心
字段剪枝(pruning)schema 未声明的字段直接丢弃,默认剪掉不报错(kubectl patch / Helm 等走 PATCH 的路径;kubectl ≥1.25 的 apply 默认 strict 校验,会直接报 Unknown field)"apply 的字段怎么不见了"几乎都栽这
x-kubernetes-preserve-unknown-fields子树声明 true 后不再剪枝该子树想原样透传一段任意结构给控制器
x-kubernetes-validations字段上写 CEL 表达式,违反直接拒字段间约束,比 webhook 便宜

肉眼验证,接着上一节的 CR:

kubectl patch mw kernel-patch-0919 --type=merge -p '{"spec":{"owner":"sre-a"}}'
kubectl get mw kernel-patch-0919 -o jsonpath='{.spec.owner}'; echo
# 输出:空 —— PATCH 请求默认不校验未知字段(fieldValidation=Ignore),owner 被静默剪除
# 注意:kubectl ≥1.25 的 apply 默认 strict 校验(server 端 ServerSideFieldValidation,v1.27 起 GA),
# 同样的字段会直接报 "Unknown field" 错。"静默剪掉"发生在 patch / --validate=ignore 或 warn / Helm 等
# 以 PATCH 提交的路径上
kubectl patch mw kernel-patch-0919 --type=merge -p '{"spec":{"mode":"reboot"}}'
# 报错:spec.mode: Unsupported value: "reboot": supported values: "drain", "cordon-only"

字段间约束用 CEL,直接写在 schema 里(片段):

              duration:
                type: string
                x-kubernetes-validations:
                - rule: "self == '2h' || self == '4h'"
                  message: "duration 只允许 2h 或 4h"

两条工程纪律。其一,CRD 不是数据库:对象最终存进 etcd,单次请求约 1.5 MiB 是硬上限,把日志、批次数据塞进 CR 是最常见的滥用——大块数据走专用存储,CR 只放期望状态。

其二,正经项目别手写 schema。kubebuilder 从 Go 类型生成 CRD:json tag 是 schema 的直接来源,//+kubebuilder: 注释(markers)声明 status 子资源、RBAC、打印列,三条命令闭环:

make manifests    # Go 类型 + markers → CRD 与 RBAC 清单
make install      # 把 CRD apply 进集群
make run          # 本地跑控制器进程,连上集群,日志直接可见

字段改名或删掉时编译器立刻报错;手写 YAML 的剪枝是静默的,排查极难。

控制环:declarative + level-triggered,一对拆不开的搭档

你写的控制器与 kube-controller-manager 里几十个内置循环是同构的,骨架就四步:

① observe: list-watch CR 与相关对象,Informer 本地缓存兜底
② diff:    期望(CR.spec)与实际有差距吗?没有就退出本轮
③ act:     补差值 —— cordon/drain 同样走 Eviction API,照样尊重 PDB
④ requeue: 固定周期 / 相关事件到来时重新进入循环

两个必须内化的词:

术语含义工程后果
declarative 声明式用户只写"想要什么"(spec),从不写"怎么做"控制器可随时被杀掉重启,重启后对比期望与实际就能续上,不存在"脚本执行到一半"的悬空状态
level-triggered 电平触发每轮处理"当前全量状态",不依赖"恰好收到某次事件"丢事件无害,下一轮重算差值自然补上;代价是循环必须幂等

对照脚本思维最清楚:脚本问"发生了什么",Reconcile 问"现在该是什么样"。

为什么必须幂等?因为事件是 edge 语义:会丢(watch 断线重连缝隙里发生的增删改,全部丢失且无从感知)、会重(至少一次投递)、会乱序。Informer 还有个兜底设计叫 resync——定期把缓存对象重推一遍回调,专门对付"事件丢了、处理器出错了"。

用 controller-runtime 的话说,事件先进 workqueue(按 key 去重、限速、指数退避)再进你的 Reconcile;同一 key 同时只有一个 Reconcile 在跑,不用对自己加锁——但重复调谐躲不掉。Reconcile(ctx, req) (Result, error) 这个签名本身就是三条铁律:

铁律含义
req 只有名字拿 namespace/name 自己 Get 最新对象,不假设"为什么被触发"
返回值三态返回 error 走指数退避重试;返回 RequeueAfter 做周期对账;全空则本轮结束
幂等同一对象跑 N 次结果一致,重复调谐是常态

第一行值得多嚼几下:为什么传名字而不传事件对象?因为对象名是 level 的锚点——拿着名字 Get 一次,永远拿到当前真相;若直接传事件,控制器的正确性就依赖"我没错过任何事件"这个不成立的前提。Cache 断线重连对 Reconcile 完全透明,恢复后涌来的一批调谐,恰好是 level-triggered 不怕的形态。

由此得到写代码前就要接受的推论:reconcile 会被并发地、重复地调用;一切外部动作都要能安全地做第二遍。写"确保 DaemonSet 存在",不要写"创建 DaemonSet";重启数据库、调云 API、cordon 节点,都要经得起跑两遍。

违反幂等最经典的现场是 status 死循环,事件链长这样:

Reconcile 无条件写 status → resourceVersion 变化 → informer 收到 Update 事件
→ 同一 key 再入队 → 再写 status → 无限循环

表现为日志刷屏、apiserver 写 QPS 异常。解法一句话:status 只在值变化时写;必要时再在事件入口加 predicates,过滤掉纯 status 变化的事件。

套娃的真相:你的输出,是内置控制器的输入

现在可以回答"套娃"套在哪了。假设你写了个 CronTab Operator,把 CR 调谐成 CronJob——故事没完,反而刚刚开始:

CronTab(CR) ──你的控制器──► CronJob ──内置控制器──► Job ──► Pod ──kubelet──► 容器

你的控制器不直接创造现实,它创建的是内置对象,交给内置控制器继续调谐;内置控制器再创建 Pod,交给 kubelet 执行。每一层的输出都是下一层的输入,每一层都是同一个"期望 vs 实际"的环。

整个 K8s 就是一组同构控制环的递归嵌套,扩展模型只是允许你在最外层再包一层——所谓扩展 K8s,全部真相就是"注册一对新 API + 新控制循环",没有更多魔法。

两个直接推论:

  • Operator 不是 apiserver 的插件。它就是用 client-go 机制 watch 集群的普通进程,跑在 Deployment 里。挂了只影响"没人调谐 CR",集群本身无恙。
  • 删除路径基本不用写。子资源带 ownerReferences,级联回收外包给 garbage collector。只有清理集群外资源(云盘、外部 DNS 记录)才需要 finalizer——而"卸载 Operator 后 CR 卡在 Terminating",就是控制器加了 finalizer 后自己没了、没人摘。另外,删 CRD 会级联删光该类型所有 CR,不可恢复,当高危操作管好权限。

finalizer 卡删除可以亲手复现,就用前面的 MaintenanceWindow:

kubectl patch mw kernel-patch-0919 --type=merge -p '{"metadata":{"finalizers":["ops.example.com/cleanup"]}}'
kubectl delete mw kernel-patch-0919 &
sleep 3; kubectl get mw
# kernel-patch-0919 仍在 —— deletionTimestamp 已打,但 finalizer 没人摘
kubectl patch mw kernel-patch-0919 --type=merge -p '{"metadata":{"finalizers":null}}'
# 这条一执行,对象立即真正消失

ServiceMonitor:一条真实链路把前面全串起来

装 kube-prometheus-stack 会带来一组 CRD,最常打交道的是 ServiceMonitor——声明"照 label 找 Service,抓它背后的 Pod":

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: web-sm
  labels:
    release: prom        # 必须被 Prometheus CR 的 serviceMonitorSelector 选中
spec:
  selector:
    matchLabels:
      app: web           # 圈定要抓取的 Service
  endpoints:
  - port: http           # 对应 Service 的 port 名

YAML 里那行注释是整条链最脆的一环:Prometheus CR 用 serviceMonitorSelector 挑选 ServiceMonitor,label 对不上,后面环节全白搭——下文排障三连的第二步查的就是它。

从 apply 到抓取生效,是一条标准控制环:

你 apply ServiceMonitor ──► Prometheus Operator watch 到它
  ──► diff: 这条 SM 体现在抓取配置里了吗?
  ──► act: 重新生成抓取配置并触发热加载
  ──► Prometheus 按 selector 找 Service → Endpoints → Pod, 开抓 /metrics
  (新 Pod 上线下线 Operator 不用动 —— 目标列表由发现机制自动维护)

注意最后一行括号,这是声明式的红利:Operator 只负责把"声明"翻译成"配置",目标集合的动态维护交给了 Prometheus 自己的发现机制——又一层套娃。没人手改 prometheus.yml,全是 CR 驱动。

同构的例子还有 cert-manager,换个领域你就能举一反三:Certificate 描述"我要一张什么证书、存进哪个 Secret",Issuer/ClusterIssuer 描述"去哪个 CA、用什么方式签"。控制器盯着有效期,到期前自动把"签发 → CA 回访验证 → 写入 Secret"整个环再跑一遍。没有它,证书续期是某个运维的日历提醒;有了它,续期是控制环的常态——这就是"把运维知识编码进控制环"的含义。

ServiceMonitor 建了却不抓,排障三连:

kubectl get servicemonitor -A                                          # CR 在吗
kubectl get prometheus -A -o yaml | grep -A4 serviceMonitorSelector    # label 匹配吗
# 第三步:打开 Prometheus UI 的 Service Discovery 页,看 target 进列表了吗

三步走完,问题一定停在某一格:要么 CR 根本没建成(回 schema 一节查剪枝),要么 label 断链,要么目标没进发现列表——每格对应一个完全不同的修法。

顺便一个升级坑:Helm 升级默认不更新已存在的 CRD、卸载也不删。于是"chart 升到新版、旧 CRD 缺新字段"是一类经典故障——新字段被静默剪掉或报 no matches for kind。纪律:CRD 当独立发布物,升级前先 apply 新版 CRD 并 diff。

什么时候不该写 Operator

讲了这么多,最实用的一节反而是这节。朴素判断就两条:这套运维有没有清晰的期望状态?能不能写成一轮轮可重入的对比与修补?两个都是——Operator 合适;有一个含糊——别写。

而且你大概率早就在用 Operator 而不自知:Gateway API 的实现控制器、Calico 的 IP Pool、Prometheus 整套可观测栈,背后都是 CRD + 控制器。判断"该不该"的能力,比"会不会写"更常被用到。

具体到几类常见需求:

需求该用什么
定时跑个脚本(备份、清理、对账)Job/CronJob,别上 Operator
配置分发、一次性动作,没有持续对账需求ConfigMap + 一段消费它的脚本
部署/扩缩/failover/证书续期这类持续对账CRD + 控制器,值得
给派生数据一个 API(如指标)聚合 API,不是 CRD

第二行展开一句【从业者判断】:配置渲染这类一次性动作没有"持续维护期望状态"的需求,ConfigMap 加十几行脚本就闭环了;为它引入新类型、新控制器、新 RBAC,换来的只是排障面变大。判断标准始终是"有没有清晰的期望状态要持续收敛",而不是"Operator 显得高级"。

预埋一个反方观点,评论区一定有人提:"kubebuilder 半小时就能脚手架出一个 Operator,AI 还能写代码,成本已经很低,为什么不统一都用 Operator?"【从业者判断】我的回应是:脚手架生成的是骨架,成本大头在骨架之外——schema 演进、多版本转换、RBAC 边界、Helm CRD 升级、webhook 证书轮换,以及凌晨三点 on-call 的人能不能看懂你的调谐逻辑。工具降低的是第一天的成本,降低不了之后三年的负债。

症状速查:先存这张表

症状原因第一动作
CR 里写的字段 get 出来不见了schema 未声明,被默认剪枝补 schema;确需透传加 x-kubernetes-preserve-unknown-fields。若 apply 直接报 Unknown field,是新版 kubectl 默认 strict 校验拦下的,同一根源
chart 升级后报 no matches for kindHelm 默认不更新已存在的 CRD先手动 apply 新版 CRD 再升级 chart
ServiceMonitor 建了但 Prometheus 不抓label 没被 serviceMonitorSelector 选中,或 port 名不匹配上文排障三连逐级查
卸载 Operator 后 CR 一直 Terminating加 finalizer 的控制器没了,没人摘确认外部资源已处理,patch 清空 finalizers
误删 CRD 后该类型实例全没了删 CRD 级联清理全部 CR,不可恢复灾备靠 etcd 快照,事前管好删除权限

这张表覆盖了 CRD 相关故障的绝大多数现场,比背十篇概念文管用。

一分钟版本

背这段(约一分钟)

K8s 的扩展模型是套娃:CRD 把新"名词"登记进 apiserver,etcd、RBAC、kubectl 全部免费,但没有控制器时 CR 只是躺在 etcd 里的空壳。控制器每轮 list-watch 拿到当前全量状态,对比期望与实际、补差值、requeue——这是 level-triggered:丢事件无害,所以 Reconcile 必须幂等,一切外部动作都要能安全地做第二遍。你的控制器的输出(如 CronJob)是内置控制器的输入,环环相扣。Operator 就是 CRD 加控制器的打包,只有存在需要持续收敛的清晰期望状态时才值得写。

现在就能做的事

三档任选:

  • 零门槛档:把"一分钟版本"背下来。下次面试聊 Operator,你能从控制环讲到幂等,再讲到什么时候不该写——多数人答不到第三层。
  • 动手档(任意集群,5 分钟):把"CRD 只是名词"一节的演示跑起来,亲眼看看没有控制器的世界——CR 进了 etcd、kubectl 能查、status 恒为空;再跑 schema 一节的 patch,看字段被静默剪掉。
  • 排障档(装有 kube-prometheus-stack 的集群):对任何一个"建了却不抓"的 ServiceMonitor 跑一遍三连排查,大概率停在 label 没被 serviceMonitorSelector 选中。
# 动手档收尾:体验完删干净。注意:会级联删光该类型所有 CR,不可恢复
kubectl delete crd maintenancewindows.ops.example.com

一句话收束:**CRD 加名词,控制器加动词,Operator 是打包;套娃的每一层,都是同一个控制环。**下次见到一个新 Operator,先看它的 CRD 问"期望状态长什么样",再看它的 Reconcile 问"它把期望翻译成了哪个内置对象"——两问下去,任何 Operator 你都能十分钟读个大概。

评论区聊两件事:一,你们生产里自研了几个 Operator,最难缠的是哪个?二,你见过最"大炮打蚊子"的 Operator 是为什么需求写的?我先说方向:答案里"每天定时改一个 ConfigMap"这种的一定不少。

K8s 深入理解系列从 Pod、Service 一路讲到控制面,都在专栏合集里。这一篇整理自我在维护的学习仓库,里面还有用 kubebuilder 从零写一个完整 Operator 的实操路线,CRD 章节带着完整的实战演练——GitHub 搜 sre-learning-hub,觉得有用点个 star 不迷路。

本文地址:https://www.idc504.com/news/9_233910.html