技能介绍

为什么大多数 Operator 会出错

构建 Kubernetes Operator 的难点通常不在于 Kubernetes 本身，而在于调和循环（Reconcile Loop）的实现。在实际工程中，绝大多数线上故障源于调和逻辑的设计缺陷：比如未设置 finalizers 导致删除时外部资源变成孤儿；在 reconcile 过程中执行长耗时的 HTTP 调用或 time.Sleep，阻塞了整个控制循环；错误地修改 spec 而非 status 引发死循环；或者在多副本部署时忘记启用 Leader Election 导致脑裂。

工具如何捕获这些问题

为了在代码合并前确定性地拦截这些故障，该技能提供了三款仅依赖 Python 标准库的静态检查工具。你可以直接使用 --help 参数运行它们：

crd_validator.py：用于校验 CRD YAML 是否符合最佳实践。它会检查 spec.versions 是否正确配置了 status 子资源、scope 是否合理、是否定义了 Conditions 数组，以及 additionalPrinterColumns 是否包含了基本的 Age 和 Phase。
reconcile_lint.py：针对 Go 编写的 controller 代码进行静态扫描。通过正则启发式规则，它会捕获如“直接使用 client.Update() 修改 spec 对象”、“reconcile 函数内没有对错误进行 requeue”、“缺失 defer 来管理 finalizer”，以及“reconcile 函数超过 80 行”等反模式。
operator_capability_audit.py：将你的 Operator 与 OperatorHub 的 5 级能力标准进行对标打分。从 L1 的基础安装到 L5 的自动调优，它会生成当前级别报告并给出达到下一级别所需的具体升级步骤。

此外，技能内含 references/ 目录提供框架选择指南，assets/ 目录则提供了包含幂等性、状态条件和重试模式的 CRD 模板与 Go 控制器骨架代码。

适用边界与注意点

调和循环不是脚本：核心原则是让 Actual State 无限逼近 Desired State，而不是写一串“如果 A 则执行 B”的命令式逻辑。
启发式检查的局限：reconcile_lint.py 基于正则匹配，适合作为 CI 中的快速守门员，但不能替代深度的人工代码审查。
场景区分：该技能仅针对需要编写 CRD 和自定义控制器的复杂生命周期管理场景。如果你只是想打包 Helm Chart 或进行常规的 Cluster Security 审计，请使用对应的专项技能。