Operatorパターンとカスタムリソースの設計

Operatorとは何を自動化するのか

Kubernetes は標準で Deployment や Service を「望ましい状態」として宣言すると、コントローラが収束させてくれます。しかし PostgreSQL のフェイルオーバー、Kafka のパーティション再分散、証明書のローテーションといった「アプリ固有の運用知識」までは知りません。これらは従来、人間が Runbook（手順書）を見ながら手で実行していました。

Operator は、その運用知識をソフトウェアに埋め込んだものです。「熟練の運用者が、対象アプリの状態を監視し、必要な操作を判断・実行する」というループを、Kubernetes のコントローラとして常駐させます。人が kubectl を叩く代わりに、コントローラが 24 時間アプリの面倒を見る、という発想です。

Operator は二つの部品から成ります。

1. CRD（CustomResourceDefinition）：Kubernetes の API を拡張し、PostgresCluster のような独自リソース種別を追加する。
2. カスタムコントローラ：その独自リソースを監視し、宣言された状態へ実体を収束させる収束ループ。

CRD：APIを拡張する

CRD は「新しいリソース種別の定義」そのものです。これを登録すると、kube-apiserver はその種別の CRUD・バリデーション・etcd への永続化・watch を標準リソースと同じ仕組みで受け付けるようになります。つまり利用者は kubectl get postgrescluster や kubectl apply -f を、組み込みリソースと区別なく使えます。

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  name: postgresclusters.db.example.com
spec:
  group: db.example.com
  scope: Namespaced
  names:
    kind: PostgresCluster
    plural: postgresclusters
  versions:
    - name: v1
      served: true
      storage: true          # etcd に保存する版（複数版なら1つだけ true）
      schema:
        openAPIV3Schema:       # ここで型・必須・範囲を定義（apiserver が検証）
          type: object
          properties:
            spec:
              type: object
              properties:
                replicas: { type: integer, minimum: 1 }
                version:  { type: string }
              required: ["replicas", "version"]

設計の要は spec と status の分離です。spec は利用者が書く「望ましい状態（こうあってほしい）」、status はコントローラが書く「観測された実際の状態（いま実際こう）」。利用者は spec だけを触り、status は読むだけ。この役割分担が Operator の規律の土台になります。

カスタムコントローラ：収束ループの原理

コントローラの中核は reconcile（調整）関数です。引数はただ一つ、対象リソースの識別子（名前空間 と 名前）。この関数は「今この瞬間のあるべき姿」を計算し、実体をそこへ寄せます。

reconcile(name):
    desired = apiserver から spec を読む       # 望ましい状態
    actual  = 実際の Pod/PVC/Secret 等を観測    # 実際の状態
    diff    = desired と actual の差分
    diff があれば必要な操作だけを適用する        # create / update / delete
    status を観測結果で上書きする
    return  # 必要なら「N秒後に再実行」を要求

ここで決定的に重要なのが level-triggered（状態駆動）であって edge-triggered（イベント駆動）ではないという点です。

Kubernetes のコントローラは watch でイベントをきっかけ（トリガー）にしますが、受け取ったイベントの中身では判断しません。トリガーを受けたら改めて現在の状態を丸ごと観測し直し、あるべき姿との差分から行動を決めます。だからイベントを取りこぼしても、apiserver と通信が一時的に切れても、コントローラが再起動しても、次の reconcile で現状を見れば正しく収束できます。これが Operator が運用に耐える理由です。

冪等な調整の作法

reconcile は同じ入力に対して何度呼ばれても同じ結果に収束しなければなりません（冪等性）。watch の再送、リーダー切り替え、リトライなどで reconcile は容易に重複実行されるからです。具体的な作法は次の通りです。

• 作成は「あれば作らない」で書く：create を無条件に呼ぶと二回目で「既に存在」エラーになる。「期待する子リソースが無ければ作る／あれば spec を期待値へ更新する」という形（apply 的な発想）にする。名前を決定的に（例 <cluster>-0）すれば重複生成を避けられる。
• 生成済みリソースの帰属を明示する：作った Pod や PVC に OwnerReference を付ける。親リソースが消えたとき子も連鎖削除（garbage collection）され、孤児が残らない。
• 副作用は観測で確かめる：外部 API 呼び出しなど巻き戻せない操作は、「やったかどうか」を毎回 status や外部状態の観測で確認してから判断する。フラグを内部メモリだけに持つと再起動で失われる。
• エラー時は requeue で再試行：失敗したら部分的な状態のまま return し、バックオフ付きで再キューする。次の reconcile が差分を見て続きを進める。リトライ戦略の考え方は /devops/retry-backoff-jitter/ と同じ発想。

状態機械として設計する

Operator は本質的に有限状態機械です。status.phase のようなフィールドに現在地（Pending → Provisioning → Running → Degraded …）を持たせ、reconcile はその状態と観測結果から「次に進めるべき一歩」だけを実行して return します。一回の reconcile で全部やり切ろうとしないのがコツです。

複雑な収束は Condition の配列で表すのが定番です。Ready Progressing Degraded などの条件ごとに True/False/Unknown と理由を持たせ、利用者や上位の自動化がそれを読んで判断できるようにします。これは Pod や Deployment の status と同じ語彙で、エコシステムと噛み合います。

どこまで自動化するか（成熟度）

Operator は「インストールできる」だけでは価値が薄く、どこまで運用を肩代わりするかで段階があります。一般に、デプロイ → 設定の維持 → バックアップ・復旧 → 障害時の自動修復 → 性能に応じた自動チューニング、と高度化します。とくに自動修復は強力ですが、GitOps の自己修復と同様に諸刃の剣で、人が緊急対応中の状態まで「ドリフト」として巻き戻す危険があります（GitOps の収束モデルとの関係は /devops/gitops/ を参照）。

まとめ

• 二点セット：CRD で API を拡張し、カスタムコントローラで収束させる。spec（望ましい状態）と status（観測結果）を分離するのが規律の土台。
• level-triggered：イベントの中身でなく現在の状態を毎回観測して差分を埋める。取りこぼし・再起動・重複に強い。
• 冪等な調整：reconcile は手順書ではなく状態機械の遷移関数。何度呼ばれても同じ結果に収束し、一歩ずつ進める。
• 安全装置を内蔵：リーダー選出で多重起動を防ぎ、自動操作には上限を設ける。運用知識をコード化するからこそ、その判断の質がそのまま本番の信頼性になる。