排解 Config Connector 問題

本頁說明疑難排解技巧，協助您排解 Config Connector 問題，以及使用產品時可能遇到的常見問題。

檢查 Config Connector 狀態和條件

檢查 Config Connector 版本

執行下列指令，取得已安裝的 Config Connector 版本，並參照版本資訊，確認執行中的版本支援您要使用的功能和資源：

kubectl get ns cnrm-system -o jsonpath='{.metadata.annotations.cnrm\.cloud\.google\.com/version}'

查看資源的狀態和事件

通常，您可以檢查 Kubernetes 中的資源狀態，判斷 Config Connector 資源的問題。檢查資源的狀態和事件，有助於判斷 Config Connector 是否無法調解資源，以及調解失敗的原因。

確認 Config Connector 是否正在執行

如要檢查 Config Connector 是否正在執行，請確認所有 Pod 皆為 READY 狀態：

kubectl get pod -n cnrm-system

輸出內容範例：

NAME                                            READY   STATUS    RESTARTS   AGE
cnrm-controller-manager-0                       1/1     Running   0          1h
cnrm-deletiondefender-0                         1/1     Running   0          1h
cnrm-resource-stats-recorder-77dc8cc4b6-mgpgp   1/1     Running   0          1h
cnrm-webhook-manager-58496b66f9-pqwhz           1/1     Running   0          1h
cnrm-webhook-manager-58496b66f9-wdcn4           1/1     Running   0          1h

如果您以命名空間模式安裝 Config Connector，則每個命名空間都會有一個控制器 (cnrm-controller-manager) Pod，負責管理該命名空間中的 Config Connector 資源。

如要檢查負責特定命名空間的控制器 Pod 狀態，請執行下列指令：

kubectl get pod -n cnrm-system \
    -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager

將 NAMESPACE 替換為命名空間名稱。

檢查控制器記錄

控制器 Pod 會記錄與 Config Connector 資源協調相關的資訊和錯誤。

您可以執行下列指令，檢查控制器 Pod 的記錄：

kubectl logs -n cnrm-system \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager \
    -c manager

如果您以命名空間模式安裝 Config Connector，上一個指令會顯示所有控制器 Pod 的合併記錄。如要檢查特定命名空間的控制器 Pod 記錄，請執行下列指令：

kubectl logs -n cnrm-system \
    -l cnrm.cloud.google.com/scoped-namespace=NAMESPACE \
    -l cnrm.cloud.google.com/component=cnrm-controller-manager \
    -c manager

將 NAMESPACE 替換為命名空間名稱。

進一步瞭解如何檢查及查詢 Config Connector 的記錄。

放棄並取得資源

在某些情況下，您可能需要更新資源中的不可變更欄位。由於您無法編輯不可變動的欄位，因此必須放棄資源，然後再取得：

1. 更新 Config Connector 資源的 YAML 設定，並將 cnrm.cloud.google.com/deletion-policy 註解設為 abandon。
2. 套用更新後的 YAML 設定，更新 Config Connector 資源的刪除政策。
3. 捨棄 Config Connector 資源。
4. 在 YAML 設定中，更新需要變更的不可變更欄位。
5. 將更新後的 YAML 設定套用至取得遭捨棄的資源。

依問題類型排解問題

請根據症狀類型，參考下表排解問題。

問題類型	常見問題
對帳	資源每 5 到 15 分鐘就會更新一次 資源沒有狀態 KNV2005：同步器過度更新資源 Config Connector 刪除的資源 控制器 Pod OOMKilled
刪除	命名空間刪除作業停滯在 Terminating 專案刪除後，資源刪除作業停滯在 DeleteFailed
權限	未定義 Compute Engine 中繼資料 錯誤 403：要求驗證範圍不足 403 Forbidden：呼叫者沒有權限 錯誤 403：呼叫端缺少 IAM 權限 更新 IAMPolicy、IAMPartialPolicy 和 IAMPolicyMember 時發生錯誤
安裝和升級	Config Connector 外掛程式安裝作業不支援此版本 failed calling webhook PodSecurityPolicy 阻止升級
設定	無法變更不可變更的欄位 沒有與種類「Foo」相符的項目 標籤不會傳播至 Google Cloud 資源 資源名稱含有特殊字元，導致發生錯誤 無法從資源規格中移除欄位

協調

下節列出 Config Connector 資源協調作業的常見問題。

資源每 5 到 15 分鐘就會更新一次

問題

Config Connector 資源每 5 到 10 分鐘就會從 UpToDate 狀態切換為 Updating 狀態。

原因

Config Connector 可能會偵測到資源的期望狀態與實際狀態之間出現非預期的差異，因此不斷更新資源。

解析度

首先，請確認您沒有任何外部系統會持續修改 Config Connector 或 Google Cloud 資源 (例如 CI/CD 管道、自訂控制器、cron 工作等)。

如果行為並非外部系統所致，請檢查 Google Cloud 是否變更 Config Connector 資源中指定的任何值。舉例來說，在某些情況下， Google Cloud 會變更欄位值的格式 (例如大寫)，導致資源的所需狀態與實際狀態之間出現差異。

使用 REST API (例如 for ContainerCluster) 或 Google Cloud CLI 取得 Google Cloud 資源的狀態。然後，將該狀態與 Config Connector 資源進行比較。找出值不相符的欄位，然後更新 Config Connector 資源以符合這些欄位。請特別留意 Google Cloud重新格式化的值。舉例來說，請參閱 GitHub 問題 #578 和 #294。

請注意，由於設定連接器和Google Cloud 資源模型不同，因此這並非完美的方法，但應該能讓您發現大多數非預期的差異。

如果無法解決問題，請參閱其他說明。

資源沒有狀態

問題

您的資源沒有 status 欄位。

原因

這可能是因為 Config Connector 無法正常運作。

解析度

確認設定連接器正在執行。

KNV2005：同步器過度更新資源

問題

您使用 Config Sync，但看到 Config Connector 資源的 KNV2005 錯誤，類似於下列情況：

KNV2005: detected excessive object updates, approximately 6 times per
minute. This may indicate Config Sync is fighting with another controller over
the object.

原因

Config Sync 和 Config Connector 可能會爭奪資源。

如果 Config Sync 和 Config Connector 持續將相同欄位更新為不同的值，就會「爭奪」資源。其中一個更新會觸發另一個更新的動作並更新資源，導致另一個更新也採取行動並更新資源，如此不斷重複。

大多數欄位不會有爭議。Config Connector 不會變更 Config Sync 中指定的欄位。同樣地，Config Sync 會忽略 Config Connector 預設但未在 Config Sync 中指定的欄位。因此，對於大多數欄位，Config Sync 和 Config Connector 都不應需要更新相同欄位。

清單欄位是例外狀況。與 Config Connector 可能會預設物件欄位中的子欄位類似，Config Connector 也可能會預設清單內物件中的子欄位。不過，由於 Config Connector 資源中的清單欄位是不可分割的，因此子欄位的預設值會視為完全變更清單的值。

因此，如果 Config Sync 設定清單欄位，而 Config Connector 預設該清單中的任何子欄位，Config Sync 和 Config Connector 就會「爭奪」資源。

解析度

如要解決這個問題，請選擇下列其中一種做法：

1. 更新 Config Sync 存放區中的資源資訊清單，使其與 Config Connector 嘗試設定的資源相符。

   方法之一是暫時停止同步設定，等待 Config Connector 完成資源的調解作業，然後更新資源資訊清單，使其與 Kubernetes API 伺服器上的資源相符。

2. 將註解 client.lifecycle.config.k8s.io/mutation 設為 ignore，即可停止 Config Sync 對 Kubernetes API 伺服器上資源更新的反應。進一步瞭解如何讓 Config Sync 忽略物件變動。

3. 如要停止讓 Config Connector 完全更新資源規格，請在資源上將 cnrm.cloud.google.com/state-into-spec 註解設為 absent。並非所有資源都支援這項註解。如要查看資源是否支援註解，請參閱對應的資源參考頁面。進一步瞭解註解。

Config Connector 刪除的資源

問題

叢集中的資源遭到刪除，您懷疑是 Config Connector 所為。

原因

Config Connector 絕不會無故刪除資源。舉例來說，執行 kubectl delete、使用 Argo CD 等設定管理工具，或使用自訂 API 用戶端，都可能導致資源遭到刪除。

一般常見的誤解是，Config Connector 已啟動並刪除叢集中的部分資源。舉例來說，如果您使用 Config Connector，可能會在容器記錄訊息或 Kubernetes 叢集稽核記錄中，發現 Config Connector 控制器管理員對特定資源發出的刪除要求。這些刪除要求是由外部觸發，Config Connector 正在嘗試協調刪除要求。

解析度

如要判斷資源遭刪除的原因，請查看傳送至相應資源的第一個刪除要求。如要深入瞭解這項問題，最好的方法是檢查 Kubernetes 叢集稽核記錄。

舉例來說，如果您使用 GKE，可以使用 Cloud Logging 查詢 GKE 叢集稽核記錄。舉例來說，如要尋找命名空間 bar 中名為 foo 的 BigQueryDataset 資源的初始刪除要求，請執行類似下列的查詢：

resource.type="k8s_cluster"
resource.labels.project_id="my-project-id"
resource.labels.cluster_name="my-cluster-name"
protoPayload.methodName="com.google.cloud.cnrm.bigquery.v1beta1.bigquerydatasets.delete"
protoPayload.resourceName="bigquery.cnrm.cloud.google.com/v1beta1/namespaces/bar/bigquerydatasets/foo"

使用這項查詢時，您會尋找第一個刪除要求，然後檢查該刪除記錄訊息的 authenticationInfo.principalEmail，判斷刪除原因。

控制器 Pod 因記憶體不足而終止

問題

Config Connector 控制器 Pod 顯示 OOMKilled 錯誤。Pod 的狀態可能會顯示為 OOMKilled 或 Terminating。

原因

容器或整個 Pod 使用的記憶體超過允許量，因此遭到終止。 您可以執行 kubectl describe 指令來確認：

kubectl describe pod POD_NAME -n cnrm-system

將 POD_NAME 替換為要排解問題的 Pod。

此外，仔細檢查 Pod 的事件記錄，可以找出任何與 OOM 相關的事件。

解析度

如要解決這個問題，可以使用 ControllerResource 自訂資源，增加 Pod 的記憶體要求和記憶體限制。

刪除

以下列出與使用者啟動的刪除作業相關的常見問題，這些問題可能會導致 Config Connector 發生衝突。

命名空間刪除作業停滯在「終止」狀態

問題

刪除命名空間作業停滯在 Terminating 階段。

原因

如果您在命名空間模式下安裝 Config Connector，且在刪除該命名空間中的所有 Config Connector 資源之前，就刪除了命名空間的 ConfigConnectorContext，就可能發生這個問題。刪除命名空間的 ConfigConnectorContext 時，系統會停用該命名空間的 Config Connector，防止刪除該命名空間中任何剩餘的 Config Connector 資源。

解析度

如要修正這個問題，請先強制清除，然後手動刪除基礎 Google Cloud 資源。

為避免日後發生這個問題，請先從 Kubernetes 刪除命名空間中的所有 Config Connector 資源，再刪除 ConfigConnectorContext。請勿在刪除命名空間中的所有 Config Connector 資源前，刪除整個命名空間，因為 ConfigConnectorContext 可能會先遭到刪除。

專案刪除後，資源刪除作業停滯在「DeleteFailed」狀態

問題

刪除 Config Connector 資源失敗，狀態為 DeleteFailed。

原因

如果 Google Cloud 專案在資源之前遭到刪除，就可能發生這個問題。

解析度

如要修正這個問題，請在Google Cloud上還原專案，讓 Config Connector 從 Kubernetes 刪除其餘子項資源。或者，您也可以強制清除。

為避免日後發生這個問題，請務必先從 Kubernetes 刪除所有子項 Config Connector 資源，再刪除 Google Cloud 專案。請避免刪除可能同時包含 Project 資源及其子項 Config Connector 資源的整個命名空間，因為系統可能會先刪除 Project 資源。

權限和驗證

下一節列出與權限和驗證相關的常見問題。

未定義 Compute Engine 中繼資料

問題

您的 Config Connector 資源具有 UpdateFailed 狀態，且訊息指出未定義 Compute Engine 中繼資料，類似於下列錯誤：

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": Get
"https://spanner.googleapis.com/v1/projects/my-project/instances/my-spanner-instance?alt=json":
metadata: Compute Engine metadata "instance/service-accounts/default/token?
scopes=https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)compute%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSIN
G)auth%!F(MISSING)cloud-platform%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)cloud-identity%!C(MISSING)https%!A(MISSING)%!F(MISS
ING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)ndev.clouddns.readwrite%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSIN
G)devstorage.full_control%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)userinfo.email%!C(MISSING)https%!A(MISSING)%!F(MISSING)%!F
(MISSING)www.googleapis.com%!F(MISSING)auth%!F(MISSING)drive.readonly" not
defined, detail:

原因

Config Connector 使用的 IAM 服務帳戶可能不存在。

解析度

如要修正這個問題，請確認 Config Connector 使用的 IAM 服務帳戶存在。

為避免日後發生這個問題，請務必按照設定連接器安裝操作說明操作。

錯誤 403：要求的驗證範圍不足

問題

您的 Config Connector 資源具有 UpdateFailed 狀態，且訊息指出因驗證範圍不足而發生 403 錯誤，類似於下列錯誤：

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner-instance": googleapi: Error 403: Request had
insufficient authentication scopes.

原因

您的 GKE 叢集可能未啟用 Workload Identity Federation for GKE。

如要確認 Workload Identity Federation for GKE 未啟用，請完成下列步驟：

1. 將下列 Pod 設定儲存為 wi-test.yaml：

   apiVersion: v1
   kind: Pod
   metadata:
     name: workload-identity-test
     namespace: cnrm-system
   spec:
     containers:
     - image: google/cloud-sdk:slim
       name: workload-identity-test
       command: ["sleep","infinity"]
     serviceAccountName: cnrm-controller-manager
   

   如果您使用命名空間模式安裝 Config Connector，serviceAccountName 應為 cnrm-controller-manager-NAMESPACE。將 NAMESPACE 替換為安裝期間使用的命名空間。

2. 在 GKE 叢集中建立 Pod：

   kubectl apply -f wi-test.yaml
   

3. 在 Pod 中開啟互動工作階段：

   kubectl exec -it workload-identity-test \
       --namespace cnrm-system \
       -- /bin/bash
   

4. 列出您的身分：

   gcloud auth list
   

5. 確認列出的身分與繫結至資源的 Google 服務帳戶相符。

   如果看到Compute Engine 預設服務帳戶，表示 GKE 叢集和/或節點集區未啟用 Workload Identity Federation for GKE。

6. 結束互動式工作階段，然後從 GKE 叢集刪除 Pod：

   kubectl delete pod workload-identity-test \
       --namespace cnrm-system
   

解析度

如要修正這個問題，請確保叢集已啟用 Workload Identity Federation for GKE。

如果仍看到相同錯誤，請確認您也為叢集的節點集區啟用 GKE 適用的工作負載身分聯盟。

403 Forbidden：呼叫者沒有權限

問題

您的 Config Connector 資源具有 UpdateFailed 狀態，且訊息指出因 Workload Identity Federation for GKE 而發生 403 錯誤，類似於下列錯誤：

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": Get
"https://spanner.googleapis.com/v1/projects/my-project/instances/my-spanner-instance?alt=json":
compute: Received 403 `Unable to generate access token; IAM returned 403
Forbidden: The caller does not have permission
This error could be caused by a missing IAM policy binding on the target IAM
service account.
For more information, refer to the Workload Identity documentation:
  https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#creating_a_relationship_between_ksas_and_gsas

原因

Config Connector 的 Kubernetes 服務帳戶缺少適當的 IAM 權限，無法以 Workload Identity Federation for GKE 使用者的身分模擬 IAM 服務帳戶。

解析度

如要修正問題並避免日後再次發生，請參閱 Config Connector 安裝說明。

錯誤 403：呼叫端缺少 IAM 權限

問題

您的 Config Connector 資源具有 UpdateFailed 狀態，且訊息指出呼叫端缺少 IAM 權限，類似於下列錯誤：

Update call failed: error fetching live state: error reading underlying
resource: summary: Error when reading or editing SpannerInstance
"my-project/my-spanner- instance": googleapi: Error 403: Caller is missing IAM
permission spanner.instances.get on resource
projects/my-project/instances/my-spanner-instance., detail:

原因

Config Connector 使用的 IAM 服務帳戶缺少管理 Google Cloud 資源所需的 IAM 權限，訊息中會說明缺少哪些權限。

解析度

如果授予 IAM 服務帳戶適當的 IAM 權限後，您仍看到相同的錯誤，請確認資源是在正確的專案中建立。檢查 Config Connector 資源的 spec.projectRef 欄位 (或資源不支援 spec.projectRef 欄位時的 cnrm.cloud.google.com/project-id 註解)，並確認資源參照的專案是否正確。請注意，如果資源和命名空間都未指定目標專案，Config Connector 會將命名空間的名稱做為專案 ID。進一步瞭解如何為專案範圍資源設定目標專案。

如果仍看到相同錯誤，請檢查是否已在 GKE 叢集上啟用 Workload Identity Federation for GKE。

為避免日後發生這個問題，請務必按照設定連接器安裝操作說明操作。

更新 IAMPolicy、IAMPartialPolicy 和 IAMPolicyMember 時發生錯誤

問題

您會看到 UpdateFailed 狀態，以及指出服務帳戶不存在的 400 錯誤訊息：

Update call failed: error setting policy member: error applying changes: summary: Request `Create IAM Members roles/[MYROLE] serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com for project \"projects/[PROJECT_ID]\"` returned error: Error applying IAM policy for project \"projects/[PROJECT_ID]\": Error setting IAM policy for project \"projects/[PROJECT_ID]\": googleapi: Error 400: Service account [NAME]@[PROJECT_ID].iam.gserviceaccount.com does not exist., badRequest

原因

如果您在清除依附於該服務帳戶的 IAMPolicy、IAMPartialPolicy 和 IAMPolicyMember 資源前刪除 IAMServiceAccount Config Connector 資源，Config Connector 就無法在調解期間找到這些 IAM 資源參照的服務帳戶。

解析度

如要解決這個問題，請檢查服務帳戶，確認是否刪除了這些 IAM 資源所需的服務帳戶。如果刪除服務帳戶，請一併清除相關的 IAM Config Connector 資源。如果是 IAMPolicyMember，請刪除整個資源。如果是 IAMPolicy 和 IAMParitialPolicy，請只移除涉及已刪除服務帳戶的繫結。不過，這類清理作業不會立即移除Google Cloud 角色繫結。由於已刪除的服務帳戶會保留 60 天，因此角色繫結也會保留 60 天。 Google Cloud 詳情請參閱 Google Cloud IAM 說明文件中的「 刪除服務帳戶」一節。

注意： 如果在刪除期間遇到任何問題，可能需要強制清除。如要立即刪除 IAM 繫結，您需要使用 gcloud 手動刪除基礎 Google Cloud 資源。

Google Cloud

為避免發生這個問題，您應一律在刪除參照的 IAMServiceAccount 之前，清除 IAMPolicy、IAMPartialPolicy、IAMPolicyMember Config Connector 資源。

ServiceIdentity 資源失敗，錯誤訊息為 IAM_SERVICE_NOT_CONFIGURED_FOR_IDENTITIES

問題

您的 ServiceIdentity 資源狀態為 UpdateFailed，並顯示類似下列的錯誤訊息：

Update call failed: error applying desired state: summary: Error creating Service Identity: googleapi: Error 400: com.google.api.tenant.error.TenantManagerException: IAM_SERVICE_NOT_CONFIGURED_FOR_IDENTITIES: ...

原因

這項錯誤表示指定資源不支援隨選服務身分建立作業。

解析度

ServiceIdentity 資源只能為支援的服務產生服務身分。如要驗證服務是否支援隨選服務身分識別建立作業，請先執行下列指令，再套用設定：

gcloud beta services identity create --service SERVICE_NAME.googleapis.com

將 SERVICE_NAME 改為服務名稱，例如 spanner。

如果指令成功，Config Connector 就能為該服務建立身分。如果指令失敗，表示 Config Connector 無法為該服務建立身分。

安裝與升級

以下列出與安裝或升級 Config Connector 版本相關的常見問題。

Config Connector 外掛程式安裝作業不支援這個版本

問題

如果無法順利啟用 Config Connector 外掛程式，系統會顯示以下錯誤訊息：Node version 1.15.x-gke.x s unsupported。

如果停用 Workload Identity Federation for GKE 或 GKE Monitoring，也會顯示錯誤訊息。

原因

GKE 叢集版本不符合規定，或已停用必要功能。

解析度

如要解決這項錯誤，請確認 GKE 叢集版本符合版本和功能需求。確認已啟用 Workload Identity Federation for GKE 和 GKE Monitoring。

如要取得叢集的所有有效版本，請執行下列指令：

gcloud container get-server-config --format "yaml(validMasterVersions)" \
    --zone ZONE

將 ZONE 替換為 Compute Engine 區域。

從清單中選擇符合需求的版本。

failed calling webhook

問題

您無法解除安裝 Config Connector，並收到類似下列內容的錯誤：

error during reconciliation: error building deployment objects: error finalizing the deletion of Config Connector system components deployed by ConfigConnector controller: error waiting for CRDs to be deleted: error deleting CRD accesscontextmanageraccesslevels.accesscontextmanager.cnrm.cloud.google.com: Internal error occurred: failed calling webhook "abandon-on-uninstall.cnrm.cloud.google.com": failed to call webhook: Post "https://abandon-on-uninstall.cnrm-system.svc:443/abandon-on-uninstall?timeout=3s": service "abandon-on-uninstall" not found

原因

使用 Config Connector 外掛程式並先停用 Config Connector，再移除 Config Connector CRD 時，可能會發生這個問題。

解析度

如要解決這項錯誤，請先手動刪除 Webhook：

kubectl delete validatingwebhookconfiguration abandon-on-uninstall.cnrm.cloud.google.com --ignore-not-found --wait=true
kubectl delete validatingwebhookconfiguration validating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true
kubectl delete mutatingwebhookconfiguration mutating-webhook.cnrm.cloud.google.com --ignore-not-found --wait=true

接著即可解除安裝 Config Connector。

PodSecurityPolicy 阻止升級

問題

從 Config Connector 外掛程式切換為手動安裝，並將 Config Connector 升級至新版本後，cnrm Pod 無法更新。

原因

使用 PodSecurityPolicies 可能會導致 cnrm Pod 無法更新。

如要確認 PodSecurityPolicies 是否會阻礙升級，請檢查 config-connector-operator 的事件，並尋找類似下列內容的錯誤：

create Pod configconnector-operator-0 in StatefulSet configconnector-operator failed error: pods "configconnector-operator-0" is forbidden: PodSecurityPolicy: unable to admit pod: [pod.metadata.annotations[seccomp.security.alpha.kubernetes.io/pod]: Forbidden: seccomp may not be set pod.metadata.annotations[container.seccomp.security.alpha.kubernetes.io/manager]: Forbidden: seccomp may not be set]

解析度

如要解決這個問題，請在 PodSecurityPolicy 中指定註解，對應錯誤訊息中提及的註解。在先前的範例中，註解為 seccomp.security.alpha.kubernetes.io。

設定

下節列出設定資源時的常見問題。

無法變更不可變更的欄位

Config Connector 會在准入時拒絕更新不可變更的欄位。

舉例來說，使用 kubectl apply 更新不可變更的欄位會導致指令立即失敗。

也就是說，如果工具持續重新套用資源 (例如 GitOps)，且未處理許可錯誤，更新資源時可能會卡住。

由於 Config Connector 不允許更新不可變更的欄位，因此執行這類更新的唯一方法是刪除並重新建立資源。

沒有更新時，更新不可變動的欄位時發生錯誤

使用 Config Connector 建立或取得 Google Cloud 資源後不久，您可能會在 Config Connector 資源的狀態中看到下列錯誤：

• Update call failed: error applying desired state: infeasible update: ({true \<nil\>}) would require recreation (範例)

• Update call failed: cannot make changes to immutable field(s) (範例)

這可能不代表您實際更新了資源，而是 Google Cloud API 變更了您在 Config Connector 資源中管理的不可變更欄位。這導致不可變動的欄位出現所需狀態與即時狀態不符的情況。

如要解決這個問題，請更新 Config Connector 資源中不可變更的欄位值，使其與即時狀態相符。如要達成這個目標，請完成下列步驟：

1. 更新 Config Connector 資源的 YAML 設定，並將 cnrm.cloud.google.com/deletion-policy 註解設為 abandon。
2. 套用更新後的 YAML 設定，更新 Config Connector 資源的刪除政策。
3. 捨棄 Config Connector 資源。
4. 使用 gcloud CLI 列印對應 Google Cloud 資源的即時狀態。
5. 找出 gcloud CLI 輸出內容與 Config Connector 資源的 YAML 設定之間的不符之處，並更新 YAML 設定中的這些欄位。
6. 套用更新後的 YAML 設定，取得遭捨棄的資源。

找不到「Foo」類型的相符項目

問題

畫面上顯示「No matches for kind "Foo"」錯誤。

原因

您的 Kubernetes 叢集未安裝 Foo 資源種類的 CRD。

解析度

確認種類是 Config Connector 支援的資源種類。

如果支援該類別，表示您的 Config Connector 安裝版本過舊或無效。

如果您使用 GKE 外掛程式安裝 Config Connector，系統應會自動升級安裝項目。如果您是手動安裝 Config Connector，則必須手動升級。

請查看 GitHub 存放區，瞭解哪些 Config Connector 版本支援哪些資源種類 (例如，這裡列出 Config Connector v1.44.0 支援的種類)。

標籤不會傳播至 Google Cloud 資源

問題

YAML 中的標籤未顯示在 Google Cloud 資源上。

原因

並非所有 Google Cloud 資源都支援標籤。

解析度

Config Connector 會將 metadata.labels 中的標籤傳播至基礎Google Cloud 資源。查看資源的 REST API 說明文件 (例如 PubSubTopic 的 API 說明文件)，確認資源是否支援標籤。

資源名稱含有特殊字元，導致發生錯誤

問題

您看到與 metadata.name 中無效字元相關的錯誤：

a lowercase RFC 1123 subdomain must consist of lower case alphanumeric characters, '-' or '.', and must start and end with an alphanumeric character (e.g. 'example.com', regex used for validation is '[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*')

原因

Kubernetes metadata.name 欄位不得使用特殊字元。

解析度

如果您想為資源命名，但該名稱不是有效的 Kubernetes 名稱，卻是有效的 Google Cloud 資源名稱，可以使用 resourceID 欄位，如下例所示：

apiVersion: sql.cnrm.cloud.google.com/v1beta1
kind: SQLUser
metadata:
  name: 'test'
spec:
  instanceRef:
    name: sqlinstance-sample-postgresql
  host: "%"
  type: CLOUD_IAM_USER
  resourceID: [e-mail]

這項設定會導致 Config Connector 使用 resourceID，而非 metadata.name 做為資源名稱。

無法從資源規格中移除欄位

問題

從 Config Connector 資源的規格中移除欄位，不會從資源中移除該欄位。

原因

從 Config Connector 管理的資源規格中移除欄位，不會使該欄位空白或還原為預設值。而是會導致該欄位成為外部管理。

注意： 有一種例外情況：清單內的欄位。清單是不可分割的，也就是說，Config Connector 會嘗試在基礎 Google Cloud中設定清單，使其等同於規格中指定的清單。

解析度

如要在基礎Google Cloud 資源中將欄位值變更為空白或預設值，您必須在 Config Connector 資源規格中將該欄位歸零：

• 如果是清單類型欄位，請使用 [] 將欄位設為空白清單。

  以下範例顯示要移除的 targetServiceAccounts 欄位：

  spec:
    targetServiceAccounts:
      - external: "[e-mail]"
      - external: "[e-mail]"
  

  如要移除這個欄位，請將值設為空白：

  spec:
    targetServiceAccounts: []
  

• 如果是基本型別欄位，請使用下列任一方法將欄位設為空白：

  類型	空白值
  字串	""
  bool	「false」
  整數	0

  以下範例顯示要移除的 identityNamespace 欄位：

  spec:
    workloadIdentityConfig:
      identityNamespace: "foo-project.svc.id.goog"
  

  如要移除這個欄位，請將值設為空白：

  spec:
    workloadIdentityConfig:
      identityNamespace: ""
  

• 如果是物件類型欄位，您可以嘗試按照上一節的指引，將物件類型的子欄位設為空白或預設值，然後確認是否有效。不過，這不一定能正常運作。

Config Connector 無法在 Arm 架構的節點上啟動

如果叢集包含使用 Arm 架構的節點集區 (例如 C4A、N4A 或 Tau T2A 系列機器)，Config Connector 元件可能無法執行。這是已知限制，因為 Config Connector 不支援以 Arm 為基礎的系統。

問題

如果您的 Config Connector 執行個體受到這個問題影響，可能會出現下列徵狀：

• cnrm-system 命名空間中的 Pod 會維持 Pending 狀態。
• Pod 可能會顯示 CrashLoopBackOff，且記錄檔中會出現類似以下的錯誤訊息： exec user process caused "exec format error"。
• 描述 Pod 會顯示排程失敗或架構不符的情況。

解析度

如要解決這個問題，請確認 Config Connector 元件排定在具有 x86 架構的節點上：

• 新增 x86 節點集區：如果叢集只包含 Arm 節點，請使用 x86 機型 (例如 e2-standard-2) 至少新增一個節點集區，以代管 Config Connector 控制器 Pod。
• 驗證節點汙染：GKE Arm 節點通常會遭到 kubernetes.io/arch=arm64:NoSchedule 汙染，避免僅限 x86 的工作負載排程在這些節點上執行。請確認您未在 Config Connector 部署作業中新增容許度，允許這些部署作業在節點上執行。

強制清除

如果 Config Connector 資源無法刪除，而您只是想從 Kubernetes 叢集移除這些資源，可以刪除資源的終結器，強制刪除資源。

警告： 刪除終結器超出 Config Connector 的正常使用範圍，可能會造成非預期的後果，因此請務必謹慎操作。具體來說，我們無法保證基礎 Google Cloud 資源會發生什麼情況。

如要刪除資源的終結器，請使用 kubectl edit 編輯資源，刪除 metadata.finalizers 欄位，然後儲存檔案，將變更保留在 Kubernetes API 伺服器中。

由於刪除資源的終結器後，資源會立即從 Kubernetes 叢集刪除，因此 Config Connector 可能 (但不一定) 無法完成基礎Google Cloud 資源的刪除作業。這表示您可能需要手動刪除 Google Cloud 資源。

監控

監控 Config Connector 並查看記錄，有助於判斷問題來源，並進一步瞭解非預期行為。

指標

您可以使用 Prometheus 收集及顯示 Config Connector 的指標。

記錄

所有 Config Connector Pod 都會以 JSON 格式輸出結構化記錄。

控制器的 Pod 記錄特別適合用於偵錯資源協調問題。

您可以篩選記錄訊息中的下列欄位，查詢特定資源的記錄：

• logger：包含小寫的資源類型。舉例來說，PubSubTopic 資源的 logger 為 pubsubtopic-controller。
• resource.namespace：包含資源的命名空間。
• resource.name：包含資源名稱。

使用 Logging 進行進階記錄查詢

如果您使用 GKE，可以使用 Cloud Logging 查詢特定資源的記錄，查詢方式如下：

注意： 查詢語法不支援註解。下列查詢使用註解慣例「# comment」提供說明文字，但這些註解無法納入查詢。

# Filter to include only logs coming from the controller Pods
resource.type="k8s_container"
resource.labels.container_name="manager"
resource.labels.namespace_name="cnrm-system"
labels.k8s-pod/cnrm_cloud_google_com/component="cnrm-controller-manager"

# Filter to include only logs coming from a particular GKE cluster
resource.labels.cluster_name="GKE_CLUSTER_NAME"
resource.labels.location="GKE_CLUSTER_LOCATION"

# Filter to include only logs for a particular Config Connector resource
jsonPayload.logger="RESOURCE_KIND-controller"
jsonPayload.resource.namespace="RESOURCE_NAMESPACE"
jsonPayload.resource.name="RESOURCE_NAME"

更改下列內容：

• GKE_CLUSTER_NAME，其中包含執行 Config Connector 的 GKE 叢集名稱
• GKE_CLUSTER_LOCATION，其中包含執行 Config Connector 的 GKE 叢集位置。例如：us-central1。
• RESOURCE_KIND，其中資源種類為小寫。例如：pubsubtopic。
• RESOURCE_NAMESPACE，其中包含資源的命名空間。
• RESOURCE_NAME，並提供資源名稱。

其他說明

如需其他協助，請在 GitHub 回報問題，或與Google Cloud 支援團隊聯絡。