Operatorのベストプラクティスとアンチパターン

# 悪い例 — 内部実装が漏れた肥大なAPI
spec:
  statefulSetName: my-db-sts
  podAntiAffinityWeight: 100
  replicationProtocol: streaming
  walSegmentSize: 16MB
  checkpointTimeout: 300s
  # ... 数十個の低レベルオプション

# 良い例 — 意図だけを宣言
spec:
  replicas: 3
  version: "16.3"
  storage: { size: 50Gi }
  highAvailability: true

// 悪い例 — 呼び出しごとに新リソースを作る(非冪等)
func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	job := newBackupJob()             // 毎回新しい名前のJobを生成
	r.Create(ctx, job)                // reconcile 100回 = Job 100個
	return ctrl.Result{}, nil
}

// 良い例 — 望ましい状態を宣言し、なければ作る
func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
	desired := desiredBackupJob(req)
	_, err := controllerutil.CreateOrUpdate(ctx, r.Client, desired, mutateFn)
	return ctrl.Result{}, err
}

観測の三チャネル
 1. status.conditions  — 現在の状態と理由を宣言的に
 2. Kubernetesイベント  — 出来事のタイムライン(kubectl describe)
 3. Prometheusメトリクス — reconcile回数/遅延/エラー、ドメイン指標

安全なアップグレードの条件
 - CRD: 新フィールドはoptional + default、既存フィールドの意味は不変
 - 複数のAPIバージョンが共存(v1alpha1, v1beta1, v1)+ conversion
 - 管理ワークロード: ヘルスゲートを通過してから次のステップ
 - ロールバック経路の存在(バックアップ、旧バージョンイメージの保存)

// 悪い例 — reconcileごとに通知爆弾
func (r *Reconciler) Reconcile(...) (ctrl.Result, error) {
	r.slackNotify("deployment started!")  // 再呼び出しごとにSlackを荒らす
	// ...
}

正しい役割分離
  spec   : ユーザーが書く -> Operatorが読む(desired)
  status : Operatorが書く -> ユーザーが読む(observed)

壊れたパターン(避けること)
  - ユーザーがstatus.replicasを編集できるようにする
  - Operatorがstatus.targetVersionを入力として信頼する

// 悪い例 — エラー時に即時無限再試行
if err != nil {
	return ctrl.Result{Requeue: true}, nil  // CPU/API暴走
}

// 良い例 — エラーを返すとcontroller-runtimeが指数バックオフ
if err != nil {
	return ctrl.Result{}, err  // 自動バックオフ再試行
}

// 意図的な遅延も明示的に
return ctrl.Result{RequeueAfter: 30 * time.Second}, nil

// 悪い例 — すべてに対するすべての権限
// +kubebuilder:rbac:groups="*",resources="*",verbs="*"

// 良い例 — 必要なリソースに必要な動詞だけ
// +kubebuilder:rbac:groups=apps,resources=statefulsets,verbs=get;list;watch;create;update;patch
// +kubebuilder:rbac:groups=core,resources=services,verbs=get;list;watch;create;update;patch
// +kubebuilder:rbac:groups=batch,resources=cronjobs,verbs=get;list;watch;create;update;patch;delete

スコープ選択ガイド
 - 単一チーム/ネームスペース対象 -> ネームスペーススコープ推奨
 - マルチテナントプラットフォーム -> クラスタスコープ + 強い隔離が必要
 - watch対象を特定ネームスペースに制限するとメモリ/負荷も削減

webhookの安全設計
 - failurePolicyを慎重に: Failは安全だが可用性リスク、
   Ignoreは可用性優先だが検証回避リスク
 - webhook対象範囲をnamespaceSelector/objectSelectorで狭める
 - webhook自身のネームスペースは除外(自己ブートストラップのデッドロック防止)
 - webhookを複数レプリカでHA構成

// 悪い例 — 毎回全PodをAPIサーバーから直接List
pods := &corev1.PodList{}
r.APIReader.List(ctx, pods)  // キャッシュ迂回 + セレクタなし

// 良い例 — キャッシュから、セレクタで絞って
pods := &corev1.PodList{}
r.List(ctx, pods,
	client.InNamespace(req.Namespace),
	client.MatchingLabels{"app": req.Name})

// ユーザーが要求した作業に対する権限を委譲検証
sar := &authzv1.SubjectAccessReview{
	Spec: authzv1.SubjectAccessReviewSpec{
		User: requestingUser,
		ResourceAttributes: &authzv1.ResourceAttributes{
			Namespace: ns,
			Verb:      "create",
			Resource:  "databases",
			Group:     "db.example.com",
		},
	},
}
if err := r.Create(ctx, sar); err != nil {
	return err
}
if !sar.Status.Allowed {
	// ユーザーに権限なし -> Operatorも代わりに実行を拒否
	return fmt.Errorf("user %s is not allowed to create databases", requestingUser)
}

効率化テクニック
 - キャッシュ範囲を制限: 特定ネームスペース/ラベルだけwatch
 - predicateでイベントをフィルタ: 関心のない変更はreconcileしない
 - MaxConcurrentReconcilesで並行性を調節(高すぎるとAPI暴走、
   低すぎると処理遅延)
 - field/labelセレクタでList範囲を縮小

// spec変更(generation増加)だけreconcile
builder.WithPredicates(predicate.GenerationChangedPredicate{})

テストピラミッド
 1. ユニットテスト: reconcileロジック、ヘルパー関数(fake client活用)
 2. envtest: 本物のAPIサーバー + etcdでreconcile統合検証
    (controller-runtimeが提供、kube-apiserverバイナリ使用)
 3. e2e: kindクラスタに実際にデプロイしてシナリオ検証
 4. カオス/障害注入: Pod強制削除、ネットワーク分断時の動作

Operatorの運用指標の例
 - reconcileエラー率(controller_runtime_reconcile_errors_total)
 - reconcile遅延(ワークキュー待機時間)
 - ワークキュー深さ(滞った作業が積もるか)
 - ドメインSLI(例:フェイルオーバー成功率、バックアップ鮮度)

アラートルールの例
 - reconcileエラー率が5分間高い -> 警告
 - ワークキューが増え続ける -> コントローラー停止を疑う
 - バックアップが24時間以上ない -> 呼び出し

 1. CRが実際に存在しspecが正しいか
    kubectl get database orders-db -o yaml
 2. status.conditionsが何を言っているか
    -> Reason/Messageに手がかりがある場合がほとんど
 3. Operator Podが生きていてreconcileしているか
    kubectl logs -n operator-system deploy/db-operator
 4. RBACが阻んでいないか(Forbiddenログ)
    kubectl auth can-i create statefulsets --as=system:serviceaccount:operator-system:db-operator
 5. ワークキューが滞っているか(メトリクス確認)
    workqueue_depth, reconcile_errors_total
 6. イベントタイムライン
    kubectl describe database orders-db

func (r *Reconciler) reconcileDelete(ctx context.Context, db *dbv1alpha1.Database) (ctrl.Result, error) {
	// 外部リソース整理 — すでになくてもエラーとみなさない
	if err := r.cleanupExternalBackupBucket(ctx, db); err != nil {
		if !isNotFound(err) {
			return ctrl.Result{}, err // 本当のエラーだけ再試行
		}
	}
	// 整理完了 -> finalizer除去 -> Kubernetesが実際に削除
	controllerutil.RemoveFinalizer(db, dbFinalizer)
	return ctrl.Result{}, r.Update(ctx, db)
}

Level 1: 基本インストール
  - CRでインストール/設定。helmでデプロイ可能。

Level 2: 円滑なアップグレード
  - 管理対象のバージョンアップグレードを安全に行う。

Level 3: フルライフサイクル
  - バックアップ/復元、スケール、障害復旧を自動化。

Level 4: 深いインサイト
  - メトリクス/アラート/ログで観測可能。性能分析を提供。

Level 5: オートパイロット
  - オートスケール、自動チューニング、異常検知、自己治癒。

[API設計]
[ ] specが小さく意図(what)中心か
[ ] 新フィールドがoptional + defaultで後方互換を守るか
[ ] 複数APIバージョン + conversion戦略があるか

[reconcile]
[ ] 冪等か(二回呼び出しの二回目が無変化)
[ ] 外部副作用が遷移時点だけ一度発生するか
[ ] エラーは返してバックオフに任せるか(無限requeueなし)
[ ] finalizerで整理ロジックを保証するか

[観測]
[ ] status.conditionsが人に読めるか
[ ] 重要な出来事をeventに残すか
[ ] ドメインメトリクスを公開するか

[セキュリティ]
[ ] RBACが最小権限か(ワイルドカードなし)
[ ] シークレットをstatus/event/logに露出しないか
[ ] 可能な限りネームスペーススコープか

[効率]
[ ] キャッシュ/watch範囲を制限したか
[ ] predicateで不要なreconcileをフィルタするか
[ ] MaxConcurrentReconcilesを適切に設定したか

[テスト/運用]
[ ] envtestで統合検証するか
[ ] 冪等性/削除テストがあるか
[ ] アラートルールとランブックがあるか