排解 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 設定，取得遭捨棄的資源。

依問題類型排解

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

問題類型 常見問題
對帳
刪除
權限
安裝和升級
設定

協調

下節列出 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 (例如 ContainerCluster) 或 Google Cloud CLI 取得 Google Cloud 資源的狀態。然後，將該狀態與 Config Connector 資源進行比較。找出值不相符的欄位，然後更新 Config Connector 資源，使其相符。請特別留意 Google Cloud重新格式化的值。舉例來說，請參閱 GitHub 問題 #578 和 #294。

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

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

由於系統自動更新欄位，導致對帳失敗或進入迴圈

如果 Google Cloud 自動更新使用 cnrm.cloud.google.com/state-into-spec: merge 註解的資源欄位，就會發生這個問題。

問題

Google Cloud 自動更新您未在 YAML 資訊清單中指定的欄位後，Config Connector 資源會進入 UpdateFailed 狀態，或重複切換至 Updating 狀態。

舉例來說，在 Cloud SQL 對 SQLInstance 資源執行自動維護更新後，和解作業可能會失敗，並顯示類似下列的錯誤：

Update call failed: error updating: patching SQLInstance ... maintenanceVersion failed: googleapi: Error 400: Invalid request: The requested maintenance version is not an available maintenance version to upgrade. Please refer to the availableMaintenanceVersions on the instance resource to see the available maintenance versions.., invalid

原因

資源含有 cnrm.cloud.google.com/state-into-spec: merge 註解。對於在 Config Connector 1.123.1 版之前建立的資源，這個註解是預設值，適用於 1.113.0 版及更早版本中新增的 CustomResourceDefinitions (CRD)。如果 ConfigConnector 或 ConfigConnectorContext 自訂資源 (CR) 中的 spec.stateIntoSpec 欄位設為 Merge，資源也可能會有這項註解。

如果將 cnrm.cloud.google.com/state-into-spec 註解設為 merge，Config Connector 會在初始協調期間，將未指定的欄位 (例如 spec.maintenanceVersion 欄位) 填入 Kubernetes 資源 spec 欄位。當 Google Cloud 稍後自動更新基礎資源上的該欄位時，Config Connector 會將儲存在 spec 欄位中的舊值視為目標狀態，並嘗試還原變更。如果 Google Cloud API 拒絕降級 (例如 Cloud SQL 對 spec.maintenanceVersion 欄位執行的操作)，協調就會失敗。

解析度

如要解決這個問題，請將資源從 Merge 行為遷移至 Absent 行為，讓 Config Connector 停止將未指定的欄位填入 spec 欄位：

  1. 在資源 YAML 資訊清單中，省略自動更新的欄位 (例如 spec.maintenanceVersion 欄位)，並將 cnrm.cloud.google.com/state-into-spec 註解設為 absent。
  2. 請按照「將資源從 Merge 遷移至 Absent」中的步驟，捨棄 Kubernetes 資源，並使用更新後的 YAML 資訊清單重新取得資源。

資源沒有狀態

問題

您的資源沒有 status 欄位。

原因

Config Connector 可能未正常運作。

解析度

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

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 叢集稽核記錄。舉例來說，如要尋找 my-namespace 命名空間中名為 my-dataset 的 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/my-namespace/bigquerydatasets/my-dataset"

使用這項查詢，您可以尋找第一個刪除要求，然後檢查該刪除記錄訊息的 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 使用的身分與存取權管理服務帳戶存在。

為避免日後發生這個問題，請務必按照 Config Connector 安裝操作說明操作。

錯誤 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

解析度

如要修正這個問題，請確保叢集已啟用 GKE 適用的工作負載身分聯盟。

如果仍看到相同錯誤，請確認您也已在叢集的節點集區中啟用 GKE 的 Workload Identity Federation。

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 服務帳戶缺少訊息中指出的 IAM 權限，無法管理 Google Cloud 資源。

解析度

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

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

為避免日後發生這個問題，請務必按照 Config Connector 安裝操作說明操作。

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 天，因此 Google Cloud 角色繫結也會保留 60 天。詳情請參閱 Google Cloud IAM 說明文件中的「刪除服務帳戶」一節。

為避免發生這個問題，請務必「先」清除 IAMPolicy、IAMPartialPolicy、IAMPolicyMember Config Connector 資源，再刪除參照的 IAMServiceAccount。

ServiceIdentity 資源失敗，錯誤代碼為 Invalid service producer

問題

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

Update call failed: error applying desired state: summary: Error creating Service Identity: Invalid service producer: ...

原因

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

解析度

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 CRD「之前」停用 Config Connector，就可能發生這個問題。

解析度

如要解決這項錯誤，請先手動刪除 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 設定，取得已捨棄的資源。

沒有與「RESOURCE_KIND」相符的種類

問題

您會看到錯誤 No matches for kind "RESOURCE_KIND"。

原因

您的 Kubernetes 叢集未安裝 RESOURCE_KIND 資源類型的 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: test.example@example-project.iam

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

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

問題

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

原因

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

解析度

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

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

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

    spec:
  targetServiceAccounts:
    - external: "example-sa-1@example-project.iam.gserviceaccount.com"
    - external: "example-sa-2@example-project.iam.gserviceaccount.com"

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

    spec:
  targetServiceAccounts: []

  • 如要將原始類型欄位設為空白，請使用下列其中一種方法：

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

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

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

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

    spec:
  workloadIdentityConfig:
    identityNamespace: ""

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

state-into-spec 註解的值「merge」無效

如果資源使用 cnrm.cloud.google.com/state-into-spec: merge 註解，但資源種類或 Config Connector 版本拒絕 merge 值，就會發生這個問題。

問題

您的 Config Connector 資源無法完成調解，並顯示類似下列內容的錯誤訊息：

Update call failed: error applying desired state: invalid value "merge" for "cnrm.cloud.google.com/state-into-spec" annotation

原因

發生這項錯誤的原因如下：

  • 資源種類不支援 Merge 行為，但資源具有 cnrm.cloud.google.com/state-into-spec: merge 註解。這項註解可能直接在資源上設定，或從 ConfigConnector 或 ConfigConnectorContext CR 中的 spec.stateIntoSpec: Merge 設定繼承。Config Connector 1.114.0 以上版本新增的 CRD 僅支援 Absent 行為。
  • 您已升級至 Config Connector 1.134.0 或 1.134.1 版，且現有 SQLInstance 資源預設具有舊版中的 cnrm.cloud.google.com/state-into-spec: merge 註解。1.134.0 和 1.134.1 版有已知問題，會拒絕 SQLInstance 資源上的 merge 值。

解析度

如要解決這個問題，請完成適用於您情況的步驟：

  • 資源種類不支援 Merge 行為：在資源 YAML 資訊清單中設定 cnrm.cloud.google.com/state-into-spec: absent 註解，並在 ConfigConnector 或 ConfigConnectorContext CR 中將 spec.stateIntoSpec 欄位設為 Absent。如要確認資源種類是否支援 Merge 行為，請參閱「支援 Merge 的種類」。如果叢集中的現有資源已包含註解，請按照「將資源從 Merge 遷移至 Absent」一文中的步驟操作。
  • 您在 Config Connector 1.134.0 或 1.134.1 版中使用現有的 SQLInstance 資源：請將 Config Connector 升級至 1.134.2 以上版本。或者，按照「將資源從 Merge 遷移至 Absent」一文中的步驟，將 SQLInstance 資源遷移至 cnrm.cloud.google.com/state-into-spec: absent 註解。

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 叢集中移除這些資源，可以刪除資源的終結器，強制刪除資源。

如要刪除資源的終結器，請使用 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 查詢特定資源的記錄，查詢方式如下：

# 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 支援團隊聯絡。