Config Connector

解決する課題

Google Cloud のリソースを宣言的に管理したいが、バッチ的に「適用して終わり」ではなく、実際の状態を常に望ましい状態へ保ち続けたいという要求があります。手動変更や設定ドリフトが起きても、気づかないまま放置されがちです。Config Connector は Kubernetes の調整ループ（リコンサイル）を使って、この継続的な同期を引き受けます。

• GCP リソースを Kubernetes と同じ宣言的モデルで管理し、アプリと一緒に GitOps で扱いたい
• 一度適用したら終わりではなく、ドリフトを継続的に検知して自動で是正したい
• 既存の Kubernetes ツールチェーン（kubectl・Argo CD・Flux など）をインフラ管理にも流用したい
• アプリと依存する GCP リソース（Pub/Sub・Cloud SQL・バケットなど）を同じマニフェスト群で一元管理したい

主要概念と用語

• カスタムリソース（CR）: GCP リソースを表す Kubernetes オブジェクト。PubSubTopic や StorageBucket のような種類があり、spec に望ましい状態を書く
• CRD（カスタムリソース定義）: Config Connector が提供する各 GCP リソースのスキーマ定義。これにより kubectl から GCP リソースを宣言できるようになる
• コントローラ（コントローラマネージャ）: CR の望ましい状態と実際の GCP リソースを比較し、差分を埋めるよう API を呼び出す常駐プロセス
• リコンサイル（調整ループ）: 望ましい状態と実際の状態を継続的に突き合わせ、ずれを是正する Kubernetes の中核的な仕組み
• ConfigConnector / ConfigConnectorContext: アドオンの動作モード（クラスタ単位 / Namespace 単位）や認証方法を設定するためのリソース
• Workload Identity: コントローラが GCP API を呼ぶ際の認証方式。Kubernetes のサービスアカウントを GCP のサービスアカウントに紐づけ、鍵ファイルを使わずに権限を得る
• Config Connector アドオン: GKE で有効化できるマネージド版。アドオンとして導入すると、コントローラの稼働とアップグレードを GKE 側が面倒を見る

仕様・制限・クォータ

• 動作には Kubernetes クラスタが必要: コントローラは Kubernetes 上で動くため、GKE クラスタ（または任意の Kubernetes 環境）が前提になる
• GKE アドオンとして提供: GKE では Config Connector をアドオンとして有効化できる。利用には Rapid または Regular リリースチャネル、Workload Identity、システムログとシステムモニタリングが必要
• 対応リソースは広いが網羅ではない: 多数の GCP リソース種別に対応するが、すべての GCP サービス・全フィールドを表現できるわけではない。対応状況は公式のリソースリファレンスで確認する
• 動作モード: クラスタ全体で動くモードと、Namespace 単位で別々のプロジェクト・権限にひも付けるモードがある
• 認証は Workload Identity が基本: コントローラの GCP 権限は Workload Identity 経由で付与するのが推奨で、鍵ファイルの配布を避けられる
• 同期間隔: コントローラは定期的にリコンサイルする。即時反映ではなく、ループの周期で収束する点に注意する

内部の仕組み

横にスクロール

Config Connector は Kubernetes のカスタムリソース + コントローラというパターンで動きます。利用者が CR を kubectl apply すると、コントローラがその spec（望ましい状態）を読み取り、対応する GCP API を呼んで実リソースを作成・更新します。以後もループで実際の状態を観測し、ずれていれば是正します。

• CRD によって StorageBucket などの種類が Kubernetes に登録され、CR として宣言できるようになる
• コントローラは CR を監視し、望ましい状態と実際の GCP リソースの差分を計算して GCP API を呼ぶ
• 手動で GCP コンソールから変更してドリフトが生じても、次のリコンサイルで CR の宣言に引き戻される
• CR を削除すると、対応する GCP リソースも削除される（保持の挙動はアノテーションで制御できる）
• GCP API の呼び出しはコントローラに紐づくサービスアカウントの権限で行われ、その権限が作用範囲の上限になる

設計パターン / ベストプラクティス

• マニフェストを Git で管理し、Argo CD や Flux などの GitOps ツールで継続的に適用してインフラとアプリを同じ流儀で扱う
• Namespace 単位で対象プロジェクトやサービスアカウントを分け、チーム・環境ごとに権限を分離する
• コントローラの認証は Workload Identity を使い、鍵ファイルの配布・保管を避ける
• リソースの依存関係は参照（references）で表現し、ID のハードコードを避けて再現性を高める
• 既存リソースを Config Connector の管理下に移す場合は、取り込み（acquire）の手順を踏み、いきなり削除・再作成されないようにする
• CR の削除後も実リソースを残す必要がある場合は、cnrm.cloud.google.com/deletion-policy: abandon を付与する。既定では CR の削除に伴って実リソースも削除される

運用・監視

• CR の status フィールドで同期状態（適用済み・エラーなど）を確認し、失敗時は条件（conditions）のメッセージから原因を追う
• 適用が失敗する場合は、まずコントローラのサービスアカウントの IAM 権限の不足を疑う
• コントローラのログと Kubernetes のイベントで、リコンサイルの試行とエラーを追跡する
• GCP API 側の操作は Cloud Audit Logs に記録されるため、誰の権限でいつ変更されたかを監査できる
• 大量の CR を抱えるとリコンサイルの負荷が上がるため、コントローラのリソース割り当てと処理状況を監視する

コスト

Config Connector アドオン自体の利用料という形ではなく、コントローラを動かす Kubernetes クラスタの費用と、宣言して作成された GCP リソースの実費を分けて捉えるのが基本です。

セキュリティ

• コントローラのサービスアカウント権限が、Config Connector の作用範囲の上限になる。広すぎる権限を与えない
• 認証は Workload Identity を使い、鍵ファイルを Pod に配布する方式を避けて漏洩リスクを下げる
• Namespace 単位でプロジェクト・サービスアカウントを分け、テナント間の権限分離を徹底する
• 機密値は CR に直書きせず、Secret Manager 等を参照する形にして平文の散在を避ける
• GCP リソースへの変更は Cloud Audit Logs で監査し、宣言と実態のずれや不正な変更を追跡できるようにする

関連サービス・比較

宣言的に GCP リソースを管理する点で Infrastructure Manager と比較されます。バッチ適用か継続同期かで使い分けます。

ハンズオン / CLI例

# GKE クラスタ作成時に Config Connector アドオンと Workload Identity を有効化
gcloud container clusters create cc-cluster \
  --addons ConfigConnector \
  --workload-pool PROJECT_ID.svc.id.goog \
  --release-channel regular \
  --logging SYSTEM \
  --monitoring SYSTEM \
  --region asia-northeast1

# コントローラ用 GCP サービスアカウントを作成し権限を付与（最小権限が原則）
gcloud iam service-accounts create cc-controller
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:cc-controller@PROJECT_ID.iam.gserviceaccount.com \
  --role roles/pubsub.admin

# Kubernetes のサービスアカウントと GCP サービスアカウントを Workload Identity で紐づけ
gcloud iam service-accounts add-iam-policy-binding \
  cc-controller@PROJECT_ID.iam.gserviceaccount.com \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[cnrm-system/cnrm-controller-manager]" \
  --role roles/iam.workloadIdentityUser

# クラスタモードと、コントローラが使う GCP サービスアカウントを設定
cat <<'EOF' | kubectl apply -f -
apiVersion: core.cnrm.cloud.google.com/v1beta1
kind: ConfigConnector
metadata:
  name: configconnector.core.cnrm.cloud.google.com
spec:
  mode: cluster
  googleServiceAccount: cc-controller@PROJECT_ID.iam.gserviceaccount.com
---
# GCP リソースをカスタムリソースとして宣言（例: Pub/Sub トピック）
apiVersion: pubsub.cnrm.cloud.google.com/v1beta1
kind: PubSubTopic
metadata:
  name: orders-topic
  namespace: default
spec:
  resourceID: orders-topic
EOF

# 同期状態を確認（status の conditions で成否を見る）
kubectl describe pubsubtopic orders-topic