kubernetes-operator

Kubernetes Operator

正しく調整するオペレーターを構築します。オペレーターのバグの大半は Kubernetes のバグではなく、調整ループのバグです。ファイナライザーの不足、処理をブロックする呼び出し、一時的なエラー発生時に再キューしないこと、ステータスのずれ、過剰な RBAC 権限などが挙げられます。このスキルは、こうした問題がクラスターに到達する前に確実に検出します。

使用する場面

• 新しい Kubernetes オペレーター（CRD のコントローラー）を構築する
• 既存のオペレーターをレビューし、機能レベルの不足を確認する
• CRD の仕様について、ステータス、Conditions、ファイナライザーが適切か監査する
• フレームワーク（controller-runtime / kubebuilder / operator-sdk / metacontroller / KOPF）を選ぶ
• カスタムリソースの API サーフェスを設計する
• RBAC、リーダー選出、または Webhook の検証を強化する

使用しない場面

• 通常の Helm チャートのパッケージ化 → helm-chart-builder を使用してください
• 標準的な kubectl 操作／ブルーグリーンデプロイ → senior-devops を使用してください
• 一般的な k8s のセキュリティ態勢 → cloud-security を使用してください
• 「ワークロードを実行したい」—それはオペレーターではなく、Deployment または Job です

核となる原則：オペレーターはスクリプトではなく、調整ループです

observe(actual) → desired = read(spec) → diff(actual, desired) → act → update(status)
                                                                          ↓
                                                                   requeue / done

失敗するオペレーターには、次のような特徴があります。

1. 調整を宣言的に（実際の状態＝望ましい状態となるよう、冪等に）行わず、命令的に（これをして、次にこれをして、その次にこれをする）扱う
2. 一時的な失敗時に再キューしない
3. ファイナライザーを使用せず、リソースを孤立させる
4. スペックではなくステータスを変更してしまう
5. status サブリソースを使用しない（ステータスの更新でスペックの調整が発生し、ループする）
6. 調整中に処理をブロックする（長時間の HTTP 呼び出し、ロックなど）
7. リーダー選出を忘れ、複数レプリカのデプロイでスプリットブレインを引き起こす

以下の 3 つのツールで、これらの問題を検出できます。

クイックスタート

SKILL=engineering/kubernetes-operator/skills/kubernetes-operator

# Validate a CRD design
python "$SKILL/scripts/crd_validator.py" --crd config/crd/myapp.yaml

# Lint a Go reconcile function
python "$SKILL/scripts/reconcile_lint.py" --controller controllers/myapp_controller.go

# Score against OperatorHub Capability Levels (1-5)
python "$SKILL/scripts/operator_capability_audit.py" --operator-dir .

3 つの Python ツール

すべて標準ライブラリのみを使用します。--help を実行してください。

crd_validator.py

CRD YAML を、オペレーターのベストプラクティスに照らして検証します。

python scripts/crd_validator.py --crd config/crd/myapp.yaml
python scripts/crd_validator.py --crd config/crd/ --format json

チェック項目：

• spec.versions[*].subresources.status が設定されている（status サブリソース）
• 明示的な根拠がない限り、spec.scope が Cluster ではなく Namespaced である
• singular と listKind が定義されている
• spec.versions[*].schema.openAPIV3Schema に型定義がある（トップレベルで x-kubernetes-preserve-unknown-fields: true を使用していない）
• バージョンの 1 つが served: true AND storage: true に設定されている
• スキーマに Conditions 配列が含まれている（metav1.Conditions を使用可能）
• プリンター列に Age と Status／Phase が含まれている

reconcile_lint.py

Go コントローラーの調整関数を、アンチパターンについて lint します。

python scripts/reconcile_lint.py --controller controllers/myapp_controller.go

チェック項目（正規表現ベースのヒューリスティック）：

• 戻り値が (ctrl.Result, error) の形式である
• エラー時にゼロ以外の再キューを指定する（return ctrl.Result{Requeue: true}, err）
• スペックオブジェクトに対する client.Update() を検出する（コントローラーはステータスのみを更新する必要があります）
• 調整内の time.Sleep を検出する（RequeueAfter を使用してください）
• コンテキストによるキャンセル処理のない HTTP 呼び出しを検出する
• ファイナライザー追加後の defer がない
• CRD に Conditions がある場合に IsConditionTrue／SetCondition の呼び出しがない
• 調整関数が 80 行を超えている（サブルーチンに切り出してください）

operator_capability_audit.py

OperatorHub の 5 つの機能レベルに照らして、オペレーターを評価します。

python scripts/operator_capability_audit.py --operator-dir .

レベル：

• L1 — 基本的なインストール： CRD が定義され、コントローラーがデプロイされる
• L2 — シームレスなアップグレード： PDB、変換 Webhook、バージョン間の互換性戦略
• L3 — ライフサイクル全体への対応： バックアップ、復元、障害復旧
• L4 — 詳細な分析情報： メトリクスエンドポイント、Prometheus ルール、アラート
• L5 — 自動運転： 自動スケーリング、自動チューニング、異常検知

現在のレベルと、次のレベルに進むための具体的な手順を報告します。

ツールの選択肢

言語と複雑さに基づいてフレームワークを選んでください。references/tooling_landscape.md を参照してください。

フレームワーク	言語	最適な用途	メンテナンス
controller-runtime	Go	本番環境向けの低レベルな制御	活発（sig-api-machinery）
kubebuilder	Go	標準的なスキャフォールディング、意見の強い設計	活発（Kubernetes SIGs）
operator-sdk	Go / Helm / Ansible	OpenShift／複数パラダイムのチーム	活発（Red Hat）
metacontroller	Any (webhook-based)	多言語チーム、Go を避けたい場合	やや低調
KOPF	Python	Python を主に使うチーム、非同期優先	活発（コミュニティ）
java-operator-sdk	Java	JVM を主に使うチーム	活発（Red Hat / Java SIG）

選択基準：

• 新しいオペレーター ＋ Go を主に使うチーム → kubebuilder
• 新しいオペレーター ＋ Python を主に使うチーム → KOPF
• 新しいオペレーター ＋ 言語を選べない場合 → metacontroller
• OpenShift が対象 → operator-sdk

CRD の設計原則

詳しくは references/crd_design.md を参照してください。要点は次のとおりです。

1. status は、コントローラーから見た世界の真実の情報源です。 Spec はユーザーが望む状態、status はコントローラーが観測した状態です。
2. status サブリソースを使用してください。 使用しないと、status の更新によって reconcile が再実行されます（ループ）。
3. Conditions を使用してください。 Ready、Reconciling、Degraded を指定します。それぞれに reason と message が含まれます。
4. finalizer を追加してください。 finalizer がないと、削除処理とコントローラーの処理が競合し、外部リソースが取り残されます。
5. 初日から CRD をバージョン管理してください。 v1alpha1 → v1beta1 → v1。変換 webhook を計画してください。
6. OpenAPI v3 スキーマで検証してください。 admission 時に失敗させるべき検証をコントローラー任せにしないでください。
7. kubectl get では additionalPrinterColumns を使用してください。 最低限、Age、Phase、Ready を表示します。
8. クラスター範囲のリソースを管理する場合を除き、CRD は名前空間に属するようにしてください。

reconcile ループの原則

詳しくは references/reconcile_loop.md を参照してください。要点は次のとおりです。

1. 冪等にしてください。 同じ状態を 2 回 reconcile した場合も、結果は同じで副作用はゼロです。
2. 一度読み取り、判断し、実行してください。 reconcile 中に繰り返し状態を確認しないでください。
3. spec ではなく status を更新してください。 spec はユーザーが管理します。
4. 再キューイングにつながるエラーを返してください。 既知の一時的なケースには ctrl.Result{RequeueAfter: ...} を使用します。
5. 処理をブロックしないでください。 time.Sleep は使用しないでください。コンテキストなしで長時間の HTTP 呼び出しを行わないでください。
6. キャッシュを使用してください。 コントローラーのキャッシュされたクライアント経由で読み取り、特別な理由がある場合にのみキャッシュを迂回してください。
7. レプリカを 2 つ以上実行する場合はリーダー選出を有効にしてください。 それ以外の場合は、単一レプリカモードを有効にしてください。
8. OwnerReferences を設定してください。 カスケード削除は、オペレーターパターンのうれしい特典です。

ワークフロー

ワークフロー 1：新しいオペレーターをセットアップする（Go ＋ kubebuilder）

1. Pick a Group/Version/Kind: e.g., apps.example.com/v1alpha1, kind=MyApp
2. kubebuilder init --domain example.com --repo github.com/org/myapp-operator
3. kubebuilder create api --group apps --version v1alpha1 --kind MyApp
4. Run crd_validator.py on config/crd/bases/apps.example.com_myapps.yaml
   → Fix every WARN before writing controller code
5. Implement the reconcile function (Karpathy principle 2: simplest correct version first)
6. Run reconcile_lint.py on controllers/myapp_controller.go
7. Run operator_capability_audit.py --operator-dir . — confirm L1
8. Test in a kind cluster: kubectl apply -f config/samples/
9. Add status conditions; aim for L2 in the same PR

ワークフロー 2：既存のオペレーターを監査する

1. Run operator_capability_audit.py --operator-dir <path>
2. Run crd_validator.py --crd config/crd/
3. Run reconcile_lint.py --controller controllers/
4. Triage findings:
   - FAIL → block release; fix before next deploy
   - WARN → file an issue; fix in next 30 days
5. Document current capability level in README; commit
6. Plan one capability level advancement per quarter

ワークフロー 3：フレームワークを選ぶ

1. Identify primary language constraint (team skill)
2. Identify deployment target (vanilla k8s vs OpenShift)
3. Identify operator complexity (single CRD vs multi-CRD vs cluster-wide)
4. Cross-reference with references/tooling_landscape.md
5. Build a 1-week proof-of-concept before committing

参考資料

• references/operator_pattern.md — オペレーターとは何か、いつ使用するか、代替手段との比較
• references/crd_design.md — CRD の設計原則、バージョン管理、変換 webhook
• references/reconcile_loop.md — reconcile パターン、エラー処理、冪等性
• references/tooling_landscape.md — フレームワークの比較 ＋ 選択ツリー

スラッシュコマンド

/operator-audit — オペレーターのリポジトリで 3 つすべてのツールを実行し、Markdown レポートを作成します。

アセットテンプレート

• assets/crd_template.yaml — status サブリソース、Conditions、finalizer のヒント、プリンター列を含む CRD
• assets/reconcile_skeleton.go — 冪等性、Conditions、finalizer、再キューイングのパターンを備えた Go コントローラーの reconcile 関数

アンチパターン

• time.Sleep(30 * time.Second)をreconcile内で呼び出す — 他のreconcileをブロックします。RequeueAfterを使用してください。
• ステータスの設定にr.Client.Update(ctx, obj)を使用する — 代わりにr.Status().Update(ctx, obj)を使用してください。
• リーダー選出なしでレプリカが2つ以上ある — スプリットブレインが発生します。
• ファイナライザーがない — 削除時に外部リソースが孤立します。
• statusサブリソースのないCRD — ステータスの更新によってspecのreconcileが実行されます（無限ループ）。
• 200行を超えるReconcile関数 — 条件ごとにreconcileXxxサブルーチンを切り出してください。
• specルートにx-kubernetes-preserve-unknown-fields: trueを設定する — バリデーションが無効になります。
• 命令型のreconcile — 「作成中ならAを実行、更新中ならBを実行、削除中ならCを実行」という形です。これは適切ではありません。reconcileとは、ここに至った経緯にかかわらず、実際の状態を望ましい状態に一致させることです。

検証可能な成功基準

このスキルを使用するチームは、以下を達成する必要があります。

• 新しいCRDの100%が、マージ前にcrd_validator.pyを通過する
• すべてのReconcile関数がreconcile_lint.pyのstrictモードを通過する
• Operatorが公開リリース前にOperatorHub Capability Level 3（Full Lifecycle）に到達する
• Reconcileのバグ修正にかかる平均時間が1日未満（本番環境で無限ループが発生しない）