Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Config Connector 控制器類型

Config Connector 採用分層架構，可根據 Kubernetes 規格，協調Google Cloud 環境中的資源。頂層父項控制器會將每個資源的協調作業，轉送至四個基礎控制器實作項目之一。

瞭解各控制器類型、技術差異，以及如何控制命名空間範圍的路由，有助於最佳化效能及排解設定問題。

基礎控制器類型

Config Connector 使用下列控制器類型：

直接控制器：這個控制器使用標準 Kubernetes controller-runtime 程式庫，並透過官方 Google Cloud Go SDK 直接與 Google Cloud API 通訊。我們建議您盡可能使用直接控制器。並非所有資源都支援直接控制器。新資源預設會使用直接控制器，現有資源則會定期遷移。詳情請參閱版本資訊。
以 Terraform 為基礎的控制器 (TF)：這個控制器可做為 Terraform Google 供應商的「包裝函式」。控制器會將 Kubernetes 資源模型 (KRM) 規格轉換為與 Terraform 相容的狀態，並實作 plan 和 apply Terraform 作業。
以 DCL 為基礎的控制器：這類控制器可做為Google Cloud 宣告式用戶端程式庫 (DCL) 的「包裝函式」。
IAM 專屬控制器：這些是專門設計的控制器，用於管理身分與存取權管理 (IAM) 資源，包括 IAMPolicy、IAMPartialPolicy、IAMPolicyMember 和 IAMAuditConfig。部分 IAM 資源可選擇性支援直接控制器。

直接控制器的好處

部分資源類型支援多種控制器類型。如果資源支援直接控制器，建議您使用直接控制器，而非其他控制器類型，原因如下：

減少資源耗用：直接控制器不會有與執行及翻譯以 Terraform 或 DCL 為基礎的狀態相關聯的 CPU 和記憶體管理負擔。
縮短對帳延遲時間：直接控制器可對 Google Cloud 端點執行直接作業，縮短達到資源狀態一致性所需的平均時間。
詳細狀態和結構化差異：直接控制器會在 cnrm-controller-manager 記錄檔中提供結構化差異報表。這些記錄包含啟動錯誤的精確欄位變更，例如對帳迴圈，有助於簡化疑難排解程序。
原生觀察到的狀態：直接控制器會在資源狀態中填入 status.observedState，提供透明的伺服器端檢視畫面，顯示Google Cloud API 直接傳回的資源欄位。
改善生命週期處理方式：直接控制器包含其他功能，例如正常刪除孤立項目。

父項路徑控制器

無論資源類型為何，Config Connector 都會攔截中央父項控制器內的所有協調要求。父項控制器會做為路由器，根據下列優先順序規則評估哪個子項邏輯會處理有效同步：

命名空間覆寫：父項控制器會先檢查目標資源命名空間中的 ConfigConnectorContext 資源設定，確認是否有任何明確的控制器覆寫。
靜態預設值：如果未指定任何本機覆寫，父項控制器會預設為 Config Connector 靜態對應設定中定義的建構時間協調器。

找出資源的控制器

如要判斷特定Google Cloud 資源設定或啟用的控制器類型，可以使用有效程式碼對應，或檢查 Google Kubernetes Engine (GKE) 中的 CustomResourceDefinition (CRD) 結構。

如要查詢資源的靜態設定，請在 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：指出未指定命名空間層級內容覆寫規則時使用的預設協調器。
SupportedControllers：列出已實作的所有協調器，以及適用於這項資源的協調器。覆寫會切換至這裡列出的協調器。

如要檢查 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 中，覆寫控制器類型的方法主要有兩種。這兩種方法的主要差異在於作業範圍、維護負擔，以及在協調期間採取的優先順序。

下表摘要列出這兩種做法的差異：

功能	資源註解	ConfigConnectorContext 覆寫
範圍	單一資源執行個體	命名空間中某種類的所有資源
優先順序	最高 (覆寫 ConfigConnectorContext)	中 (覆寫靜態預設值)
建議使用？	否	是
適用情境	單次測試	在團隊或專案中全面推出

覆寫特定資源的控制器

如要強制特定資源執行個體使用特定調解器，請將 alpha.cnrm.cloud.google.com/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。

覆寫命名空間的控制器

如要使用 ConfigConnectorContext 自訂資源設定命名空間範圍的覆寫，請完成下列步驟：

從資源定義中擷取名稱和群組。舉例來說，如果是 BigQueryDataset 資源，資源種類為 BigQueryDataset，群組為 bigquery.cnrm.cloud.google.com。
在包含受管理資源的命名空間中，編輯 ConfigConnectorContext 物件：
```
kubectl edit configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME
```
將 NAMESPACE_NAME 替換為目標命名空間。

新增目標覆寫。舉例來說，如要覆寫這個命名空間中的所有 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

儲存並套用資源。父項控制器會自動將新的直接調和器路由規則，動態套用至這個命名空間中所有相符的資源。

命名空間覆寫限制和用途

明確支援需求：如要成功覆寫，必須為資源種類實作目標控制器類型。如要檢查是否支援控制器類型，請參閱「識別資源的控制器」。如果您在覆寫中指定的控制器類型不受支援，父項控制器會忽略覆寫，預設的協調器會繼續處理資源。
命名空間限制：ConfigConnectorContext 下的覆寫會集體套用至該特定命名空間內的所有資源類型執行個體。您無法使用命名空間範圍的覆寫，指定個別資源執行個體。
存取控管：更新 ConfigConnectorContext 物件通常需要比標準資源編輯更高的平台團隊權限。
覆寫狀態回報：如果在 ConfigConnectorContext 覆寫中指定無效或不支援的控制器類型，父項控制器會將內容標示為不正常。您可以執行 kubectl get configconnectorcontext configconnectorcontext.core.cnrm.cloud.google.com -n NAMESPACE_NAME -o yaml 並檢查 .status.healthy 和 .status.errors 欄位，確認這項資訊。
使用時機：建議採用這種方法覆寫控制器。您可以使用這項功能，為整個命名空間選擇採用新式控制器 (例如直接控制器)，或在專案中強制執行架構一致性。