Config Connector コントローラのタイプ

Config Connector は、階層化されたアーキテクチャを使用して、環境内のリソースと Kubernetes の仕様を調整します。Google Cloud 最上位の親コントローラは、各リソースの調整を 4 つの基盤となるコントローラ実装のいずれかにルーティングします。

各コントローラのタイプ、技術的な違い、Namespace 全体のルーティングを制御する方法を理解すると、パフォーマンスを最適化し、構成の問題をトラブルシューティングできます。

基盤となるコントローラのタイプ

Config Connector は、次のコントローラ タイプを使用します。

  • 直接コントローラ: このコントローラは、標準の Kubernetes controller-runtime ライブラリを使用し、 Google Cloud 公式の Google Cloud Go SDK を使用して API と 直接通信します。可能な限り、直接コントローラを使用することをおすすめします。一部のリソースは直接コントローラをサポートしていません。新しいリソースはデフォルトで直接コントローラを使用します。既存のリソースは定期的に移行されます。詳細については、 リリースノートをご覧ください。
  • Terraform ベースのコントローラ（TF）: このコントローラは、Terraform Google プロバイダの「ラッパー」として機能します。コントローラは、Kubernetes Resource Model（KRM）の仕様を Terraform と互換性のある状態に変換し、plan と apply の Terraform オペレーションを実装します。
  • DCL ベースのコントローラ: このコントローラ タイプは、 Google Cloud Declarative Client Library（DCL）の「ラッパー」として機能します。
  • IAM 固有のコントローラ: これらは、IAMPolicy、IAMPartialPolicy、IAMPolicyMember、IAMAuditConfig など、Identity and Access Management（IAM）リソースを管理するために特別に設計された特殊なコントローラです。一部の IAM リソースは、直接コントローラをオプションでサポートしています。

直接コントローラのメリット

一部のリソースタイプは、複数のコントローラ タイプをサポートしています。 リソースが直接コントローラをサポートしている場合は、次の理由から、別のコントローラ タイプではなく直接コントローラを使用することをおすすめします。

  • リソース消費量の削減: 直接コントローラには、Terraform ベースまたは DCL ベースの状態の実行と変換に関連する CPU とメモリのオーバーヘッドがありません。
  • 調整レイテンシの改善: 直接コントローラは エンドポイントに対して直接オペレーションを実行できるため、リソース状態の一貫性を実現するために必要な平均時間を短縮できます。 Google Cloud
  • きめ細かいステータスと構造化された差分: 直接コントローラは、cnrm-controller-manager ログに構造化された差分レポートを提供します。これらのログには、調整ループなどのエラーを開始した正確なフィールド変更が含まれているため、トラブルシューティングが容易になります。
  • ネイティブの観測状態: 直接コントローラは、リソース ステータスの status.observedStateに入力し、透過的な サーバーサイド ビューを、 Google Cloud API から直接返されるリソース フィールドに提供します。
  • ライフサイクル処理の改善: 直接コントローラには、孤立した削除などの追加機能が含まれています。

親ルーティング コントローラ

リソースタイプに関係なく、Config Connector は中央の親コントローラ内のすべての調整リクエストをインターセプトします。親コントローラはルーターとして機能し、次の優先順位ルールを使用して、アクティブな同期を処理する子ロジックを評価します。

  1. Namespace のオーバーライド: 親コントローラは、まずターゲット リソースの Namespace 内の ConfigConnectorContext リソース構成で、明示的なコントローラのオーバーライドを確認します。
  2. 静的デフォルト: ローカル オーバーライドが指定されていない場合、親コントローラは、Config Connector の静的マッピング構成で定義されたビルド時の Reconciler をデフォルトで使用します。

リソースのコントローラを特定する

特定のコード マッピングを使用するか、Google Kubernetes Engine（GKE）で CustomResourceDefinition（CRD）構造を調べることで、特定の Google Cloud リソースに構成またはアクティブなコントローラ タイプを特定できます。

リソースの静的構成を調べるには、 GitHub の pkg/controller/resourceconfig/static_config.go でリソースを調べて、 次の例のようなリソースの構成ブロックを探します。

{Group: "alloydb.cnrm.cloud.google.com", Kind: "AlloyDBCluster"}: {
    DefaultController:    k8s.ReconcilerTypeTerraform,
    SupportedControllers: []k8s.ReconcilerType{k8s.ReconcilerTypeDirect, k8s.ReconcilerTypeTerraform},
}
  • DefaultController: Namespace レベルのコンテキスト オーバーライド ルールが指定されていない場合に使用されるデフォルトの Reconciler を示します。
  • SupportedControllers: このリソースに実装され、使用可能なすべての Reconciler を一覧表示します。オーバーライドは、ここにリストされている Reconciler に切り替わります。

CRD ラベルを調べるには、kubectl get crd コマンドを使用します。

kubectl get crd RESOURCE_NAME -o jsonpath='{.metadata.labels}'

RESOURCE_NAME は、Config Connector CRD の正確な名前に置き換えます（bigquerydatasets.bigquery.cnrm.cloud.google.com など）。

結果で次の情報を確認します。

  • cnrm.cloud.google.com/tf2crd: "true": Terraform ベース （TF）コントローラがリソースを管理します。
  • cnrm.cloud.google.com/dcl2crd: "true": DCL ベースの コントローラがリソースを管理します。
  • これらのラベルがない場合: 直接コントローラがリソースを管理します。

デフォルトのコントローラをオーバーライドする

Config Connector でコントローラ タイプをオーバーライドするには、主に 2 つの方法があります。 これらの違いは、主にオペレーションの範囲、メンテナンスのオーバーヘッド、調整時の優先順位です。

次の表に、2 つの方法の違いをまとめます。

機能 リソース アノテーション ConfigConnectorContext のオーバーライド
範囲 単一のリソース インスタンス Namespace 内の特定の種類のリソースすべて
優先度 最高（ConfigConnectorContext をオーバーライド） 中（静的デフォルトをオーバーライド）
推奨 いいえ はい
最適な用途 1 回限りのテスト チームまたはプロジェクト全体のロールアウト

特定のリソースのコントローラをオーバーライドする

リソース メタデータに alpha.cnrm.cloud.google.com/reconciler アノテーションを追加すると、特定のリソース インスタンスを特定の Reconciler で強制的に実行できます。この方法は、前のセクションで説明した理由からおすすめしませんが、単一のリソース インスタンスの構成をテストする場合や、レガシー構成を維持する必要がある場合は必要になることがあります。

apiVersion: bigquery.cnrm.cloud.google.com/v1beta1
kind: BigQueryDataset
metadata:
  name: my-bq-ds
  namespace: NAMESPACE_NAME
  annotations:
    alpha.cnrm.cloud.google.com/reconciler: direct
spec:
  ...

アノテーションでサポートされている値は、direct、tf、dcl です。

Namespace のコントローラをオーバーライドする

ConfigConnectorContext カスタム リソースを使用して Namespace 全体のオーバーライドを構成するには、次の操作を行います。

  1. リソース定義から名前とグループを取得します。たとえば、BigQueryDataset リソースの場合、リソースの種類は BigQueryDataset、グループは bigquery.cnrm.cloud.google.com です。

  2. 管理対象リソースを含む Namespace 内の ConfigConnectorContext オブジェクトを編集します。

    kubectl edit configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME

    NAMESPACE_NAME は、ターゲット Namespace に置き換えます。

  3. ターゲットのオーバーライドを追加します。たとえば、この Namespace 内のすべての BigQueryDataset インスタンスをオーバーライドして直接コントローラで実行するには、次のように構成を定義します。

    apiVersion: core.cnrm.cloud.google.com/v1beta1
kind: ConfigConnectorContext
metadata:
  name: configconnectorcontext.core.cnrm.cloud.google.com
  namespace: NAMESPACE_NAME
spec:
  googleServiceAccount: "kcc-sa@my-project.iam.gserviceaccount.com"
  experiments:
    controllerOverrides:
      BigQueryDataset.bigquery.cnrm.cloud.google.com: direct

  4. リソースを保存して適用します。親コントローラは、この Namespace 内の一致するすべてのリソースに、新しい直接 Reconciler ルーティング ルールを自動的に動的に適用します。

Namespace のオーバーライドの制約とユースケース

  • 明示的なサポート要件: オーバーライドを成功させるには、ターゲット コントローラ タイプがリソースの種類に実装されている必要があります。コントローラ タイプがサポートされているかどうかを確認するには、リソースのコントローラを特定するをご覧ください。オーバーライドで指定したコントローラ タイプがサポートされていない場合、親コントローラはオーバーライドを無視し、デフォルトの Reconciler がリソースの処理を続行します。
  • Namespace の上限: ConfigConnectorContext のオーバーライドは、特定の Namespace 内にあるそのリソースタイプのすべてのインスタンスにまとめて適用されます。Namespace スコープのオーバーライドで個々のリソース インスタンスをターゲットにすることはできません。
  • アクセス制御: 通常、ConfigConnectorContext オブジェクトを更新するには、標準のリソース編集よりも高いレベルのプラットフォーム チーム権限が必要です。
  • オーバーライド ステータスのレポート: ConfigConnectorContext のオーバーライドで無効またはサポートされていないコントローラ タイプが指定されている場合、親コントローラはコンテキストを異常とマークします。これを確認するには、kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml を実行して、.status.healthy フィールドと .status.errors フィールドを確認します。
  • 使用する場合: これは、コントローラをオーバーライドする場合におすすめの方法です。これを使用して、Namespace 全体を最新のコントローラ（直接など）にオプトインしたり、プロジェクト全体でアーキテクチャの一貫性を適用したりします。