Kubernetes Operator 技能面向构建和审查 Kubernetes Operator 的开发者，核心目标是让 Operator 的协调循环正确工作。资料指出，大多数 Operator 缺陷并非 Kubernetes 本身的问题，而是协调循环的问题：缺少 finalizer、阻塞调用、瞬时错误未重新入队、状态漂移、RBAC 过度授权。该技能通过三个确定性工具在进入集群前捕获这些问题。
适用场景包括：构建新的 Kubernetes Operator（CRD 的控制器）；审查现有 Operator 的能力级别缺口；审计 CRD spec 的 status/conditions/finalizer 正确性；选择框架（controller-runtime / kubebuilder / operator-sdk / metacontroller / KOPF）；设计自定义资源的 API 表面；加固 RBAC、领导者选举或 webhook 校验。不适用场景：纯 Helm chart 打包应使用 helm-chart-builder；标准 kubectl 操作/蓝绿部署应使用 senior-devops；通用 k8s 安全态势应使用 cloud-security；仅想运行工作负载应使用 Deployment/Job 而非 Operator。
核心原则：Operator 是协调循环，不是脚本。流程为 observe(actual) → desired = read(spec) → diff(actual, desired) → act → update(status)，然后 requeue 或 done。失败的 Operator 通常把协调当作命令式（先做这个再做那个）而非声明式（幂等地使 actual=desired）；不重新入队瞬时失败；不使用 finalizer 导致孤儿资源；修改 spec 而非 status；不使用 status 子资源（status 更新触发 spec 协调形成循环）；在协调中阻塞（长 HTTP 调用、锁）；忘记领导者选举导致多副本脑裂。
快速开始：设置 SKILL=engineering/kubernetes-operator/skills/kubernetes-operator，然后运行三个工具。crd_validator.py 校验 CRD YAML：python "$SKILL/scripts/crd_validator.py" --crd config/crd/myapp.yaml。reconcile_lint.py 检查 Go 协调函数：python "$SKILL/scripts/reconcile_lint.py" --controller controllers/myapp_controller.go。operator_capability_audit.py 按 OperatorHub 能力级别评分：python "$SKILL/scripts/operator_capability_audit.py" --operator-dir .。三个工具均仅依赖标准库，可用 --help 查看用法。
crd_validator.py 检查项：spec.versions[*].subresources.status 是否设置；spec.scope 是否为 Namespaced（除非明确说明理由）；是否定义 singular 和 listKind；openAPIV3Schema 是否有类型定义（顶层不应有 x-kubernetes-preserve-unknown-fields: true）；是否有版本标记 served: true 且 storage: true；schema 中是否有 Conditions 数组；printer columns 是否包含 Age 和 Status/Phase。
reconcile_lint.py 基于正则启发式检查：返回是否为 (ctrl.Result, error) 形状；错误是否触发非零重新入队；是否对 spec 对象调用 client.Update()；协调中是否有 time.Sleep；HTTP 调用是否缺少 context 取消；添加 finalizer 后是否缺少 defer；CRD 有 conditions 时是否缺少 IsConditionTrue / SetCondition 调用；协调函数是否超过 80 行。
operator_capability_audit.py 按 OperatorHub 五级评分：L1 基础安装（CRD 定义、控制器部署）；L2 无缝升级（PDB、转换 webhook、版本偏差策略）；L3 完整生命周期（备份、恢复、故障恢复）；L4 深度洞察（指标端点、Prometheus 规则、告警）；L5 自动驾驶（自动扩缩、自动调优、异常检测）。报告当前级别和升级到下一级的具体步骤。
工具生态：controller-runtime（Go，生产级低层控制，sig-api-machinery 维护）；kubebuilder（Go，标准脚手架，Kubernetes SIGs 维护）；operator-sdk（Go/Helm/Ansible，OpenShift/混合范式团队，Red Hat 维护）；metacontroller（任意语言，基于 webhook，多语言团队，活跃度较低）；KOPF（Python，Python 团队，异步优先，社区维护）；java-operator-sdk（Java，JVM 团队，Red Hat/Java SIG 维护）。决策规则：新 Operator + Go 团队选 kubebuilder；Python 团队选 KOPF；无法选语言选 metacontroller；OpenShift 目标选 operator-sdk。
CRD 设计原则：status 是控制器视角的事实来源，spec 是用户想要的，status 是控制器观察到的；使用 status 子资源；使用 Conditions（Ready、Reconciling、Degraded，各带 reason 和 message）；添加 finalizer；从第一天起版本化 CRD（v1alpha1 → v1beta1 → v1，规划转换 webhook）；通过 OpenAPI v3 schema 校验；使用 additionalPrinterColumns 至少显示 Age、Phase、Ready；除非管理集群级资源，否则 CRD 使用命名空间作用域。
协调循环原则：幂等（协调同一状态两次结果相同、零副作用）；一次读取、决策、行动；更新 status 而非 spec；返回会重新入队的错误，已知瞬时情况用 ctrl.Result{RequeueAfter: ...}；绝不阻塞（无 time.Sleep，无缺少 context 的长 HTTP 调用）；使用缓存；多副本时领导者选举，否则单副本模式；设置 OwnerReferences 实现级联删除。
工作流：工作流 1 引导新 Operator（Go + kubebuilder）：选择 Group/Version/Kind；kubebuilder init；kubebuilder create api；对生成的 CRD 运行 crd_validator.py 并修复所有 WARN；实现协调函数；运行 reconcile_lint.py；运行 operator_capability_audit.py 确认 L1；在 kind 集群测试；添加 status conditions 争取 L2。工作流 2 审计现有 Operator：依次运行三个工具；分类发现（FAIL 阻止发布，WARN 30 天内修复）；在 README 记录当前能力级别；每季度规划提升一级。工作流 3 选择框架：识别语言约束、部署目标、Operator 复杂度，交叉参考 tooling_landscape.md，先做一周概念验证。
参考文档：references/operator_pattern.md（Operator 是什么、何时使用）；references/crd_design.md（CRD 设计原则、版本化、转换 webhook）；references/reconcile_loop.md（协调模式、错误处理、幂等性）；references/tooling_landscape.md（框架比较与决策树）。斜杠命令：/operator-audit 对 Operator 仓库运行全部三个工具并生成 markdown 报告。资产模板：assets/crd_template.yaml（含 status 子资源、conditions、finalizer 提示、printer columns 的 CRD）；assets/reconcile_skeleton.go（含幂等、conditions、finalizers、requeue 模式的 Go 协调函数）。
反模式：协调中 time.Sleep 阻塞其他协调；用 r.Client.Update 设置 status 而非 r.Status().Update；无领导者选举 + 2 个以上副本导致脑裂；无 finalizer 导致外部资源孤儿；CRD 无 status 子资源导致无限循环；协调函数超过 200 行；spec 根上 x-kubernetes-preserve-unknown-fields: true 破坏校验；命令式协调（“如果创建做 A，如果更新做 B，如果删除做 C”）形状错误。
可验证成功标准：新 CRD 100% 在合并前通过 crd_validator.py；所有协调函数通过 reconcile_lint.py 严格模式；Operator 在公开发布前达到 OperatorHub 能力级别 3（完整生命周期）；修复协调缺陷的平均时间小于 1 天（生产无无限循环）。