Config Connector のトラブルシューティング

このページでは、Config Connector のトラブルシューティングに使用できる解決方法と、プロダクトの使用時に発生する可能性のある一般的な問題ついて説明します。

基本的なトラブルシューティングの手法

Config Connector のバージョンを確認する

インストールされている Config Connector のバージョンを取得するには、次のコマンドを実行します。使用したい機能やリソースが実行中のバージョンでサポートされていることを確認するには、リリースノートを照らし合わせます。

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

リソースのステータスとイベントを確認する

通常、Config Connector リソースの問題は、Kubernetes でのリソースの状態の調査によって特定できます。リソースのステータスとイベントの確認は、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 を namespaced モードにインストールすると、対象の名前空間内の Config Connector リソースの管理を担当する名前空間ごとに 1 つのコントローラ（cnrm-controller-manager）Pod が作成されます。

次のコマンドを実行して、特定の名前空間を担当するコントローラ 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 は Namespace の名前に置き換えます。

コントローラのログを確認する

コントローラ Pod は、Config Connector リソースの調整に関する情報とエラーをログに記録します。

コントローラ Pod のログを確認するには、次のコマンドを実行します。

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

Config Connector が namespaced-mode にインストールされている場合に、先ほどのコマンドによって、すべてのコントローラ 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 は Namespace の名前に置き換えます。

Config Connector のログを検査してクエリを実行する方法を確認する。

リソースを放棄して取得します。

場合によっては、リソース内の変更不可フィールドの更新が必要になることがあります。変更不可のフィールドは編集できないため、リソースを放棄してから取得する必要があります。

Config Connector リソースの YAML 構成を更新して、cnrm.cloud.google.com/deletion-policy アノテーションを abandon に設定します。
更新された YAML 構成を適用して Config Connector リソースの削除ポリシーを更新します。
Config Connector リソースを放棄します。
YAML 構成で変更が必要な不変フィールドを更新します。
更新された YAML 構成を適用して、放棄されたリソースを取得します。

一般的な問題

リソースが 5～15 分ごとに更新される

Config Connector リソースが 5～10 分ごとに UpToDate ステータスから Updating ステータスに切り替わる場合は、Config Connector がリソースの望ましい状態と実際の状態の間に予期しない差分を検出している可能性があります。これが、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 リソースモデルは異なるため、これは完全な方法ではありませんが、意図しない差分のほとんどを特定できます。

問題を解決できない場合は、その他のサポートをご覧ください。

「終了しています」と表示されたまま停止している名前空間の削除

Config Connector を Namespace モードでインストール済みであり、対象の名前空間内のすべての Config Connector リソースが削除される前に名前空間の ConfigConnectorContext が削除された場合に名前空間の削除によって Terminating で動作が停止する可能性があります。名前空間の ConfigConnectorContext が削除されると、その名前空間の Config Connector は無効となり、その名前空間の残りの Config Connector リソースが削除できなくなります。

この問題を解決するには、強制クリーンアップを実行した後で、基盤となる Google Cloud リソースを手動で削除する必要があります。

この問題を将来にわたって軽減するには、その名前空間内のすべての Config Connector リソースが Kubernetes から削除された後でのみ、ConfigConnectorContext を削除します。ConfigConnectorContext が最初に削除される可能性があるため、対象の前空間内のすべての Config Connector リソースを削除する前に、名前空間全体を削除することは回避してください。

また、プロジェクトとその子またはフォルダとその子を含む名前空間を削除すると動作が停止する仕組みについても説明します。

プロジェクトが削除された後に「DeleteFailed」と表示されたまま停止しているリソースの削除

Google Cloud プロジェクトがすでに削除されている場合、Config Connector リソースの削除は DeleteFailed で停止する可能性があります。

この問題を解決するには、Google Cloud でプロジェクトを復元して、Config Connector が Kubernetes から残りの子リソースを削除できるようにします。または、強制クリーンアップを実行することもできます。

今後におけるこの問題を軽減するには、すべての子 Config Connector リソースが Kubernetes から削除された後にのみ、Google Cloud プロジェクトを削除します。Project リソースと子の Config Connector リソースの両方を含む可能性がある名前空間全体を削除することは回避してください。Project リソースが最初に削除される可能性があります。

Compute Engine メタデータが定義されていない

Compute Engine メタデータが定義されていないことを示すメッセージが表示されて Config Connector リソースが UpdateFailed ステータスになっている場合は、Config Connector が使用している IAM サービスアカウントが存在しない可能性があります。

UpdateFailed メッセージの例:

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 のインストール手順に沿って操作してください。

エラー 403: リクエストに十分な認証スコープがありません

認証スコープが不十分であることが原因で 403 エラーを示すメッセージが表示されて、Config Connector リソースのステータスが UpdateFailed になっている場合は、Workload Identity が GKE クラスタで有効になっていない可能性があります。

UpdateFailed メッセージの例:

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.

調べるには、次の手順を行います。

次の 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 は、インストール時に使用した名前空間に置き換えます。
GKE クラスタに Pod を作成します。
```
kubectl apply -f wi-test.yaml
```

Pod でインタラクティブセッションを開きます。

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

ID を一覧表示します。
```
gcloud auth list
```
表示された ID が、リソースにバインドされた Google サービスアカウントと一致していることを確認します。

Compute Engine のデフォルトのサービスアカウントが表示されている場合は、GKE クラスタまたはノードプール（あるいは、それらの両方）で Workload Identity Federation for GKE が有効になっていません。
インタラクティブセッションを終了し、GKE クラスタから Pod を削除します。
```
kubectl delete pod workload-identity-test \
    --namespace cnrm-system
```

この問題を解決するには、Workload Identity Federation for GKE が有効になっている GKE クラスタを使用します。

Workload Identity Federation for GKE が有効になっている GKE クラスタで引き続き同じエラーが表示される場合は、クラスタのノードプールでも忘れずに Workload Identity Federation for GKE を有効にしていることを確認してください。既存のノードプールで Workload Identity Federation for GKE を有効にする方法を確認する。Config Connector は任意のクラスタで実行できるため、クラスタのすべてのノードプールで Workload Identity Federation for GKE を有効にすることをおすすめします。

403 Forbidden: 呼び出し元に権限がありません。Workload Identity Federation for GKE のドキュメントをご覧ください。

Workload Identity Federation for GKE が原因で 403 エラーを示すメッセージが表示されて、Config Connector リソースのステータスが UpdateFailed になっている場合は、Config Connector の Kubernetes サービスアカウントに、Workload Identity Federation for GKE ユーザーとして IAM サービスアカウントの権限を借用するための適切な IAM 権限がない可能性があります。

UpdateFailed メッセージの例:

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 Federation for GKE documentation:
  https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#creating_a_relationship_between_ksas_and_gsas

この問題を修正してその後の問題を軽減するには、Config Connector のインストール手順をご覧ください。

エラー 403: 呼び出し元に IAM 権限がありません

呼び出し元に IAM 権限がないことを示すメッセージが表示され Config Connector リソースのステータスが UpdateFailed になっている場合は、Config Connector が使用している IAM サービスアカウントに IAM 権限がないく、メッセージに Google Cloud リソースの管理にこの権限が必要であることが示されている可能性があります。

UpdateFailed メッセージの例:

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:

IAM サービスアカウントに適切な IAM 権限を付与した後も同じエラーが引き続き表示される場合は、リソースが正しいプロジェクト内に作成されていることを確認してください。Config Connector リソースの spec.projectRef フィールド（または、リソースが spec.projectRef フィールドをサポートしていない場合はリソースの cnrm.cloud.google.com/project-id アノテーション）を確認し、リソースが正しいプロジェクトを参照していることを確認します。リソース、名前空間のいずれによってもターゲットプロジェクトが指定されていない場合、Config Connector は名前空間の名前をプロジェクト ID として使用します。プロジェクトを対象にしたリソースのターゲットプロジェクトを構成する方法について詳細をご確認ください。

引き続き同じエラーが表示される場合は、Workload Identity Federation for GKE が GKE クラスタで有効になっているかどうかを確認します。

この問題を将来にわたって軽減するには、Config Connector のインストール手順に沿って操作してください。

バージョンがConfig Connector アドオンのインストールでサポートされていない

Config Connector アドオンを正常に有効にできない場合は、Node version 1.15.x-gke.x s unsupported というエラーメッセージが表示されます。このエラーを解決するには、GKE クラスタのバージョンが、バージョンと機能の要件を満たしていることを確認します。

クラスタのすべての有効なバージョンを取得するには、次のコマンドを実行します。

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

ZONE を Compute Engine ゾーンに置き換えます。

要件を満たすリストからバージョンを選択します。

エラーメッセージは、Workload Identity Federation for GKE または GKE Monitoring が無効になっている場合にも表示されます。エラーを解決するには、これらの機能を有効になっていることを確認してください。

変更不可のフィールドを変更できない

Config Connector は、アドミッション時に変更不可のフィールドの更新を拒否します。

たとえば、kubectl apply で変更不可のフィールドを更新すると、コマンドが直後に失敗します。

つまり、継続的にリソースを再適用するツール（GitOps など）は、アドミッションエラーを処理しないとリソースの更新中にツール自身が動作を停止していることを検出する可能性があります。

Config Connector は変更不可のフィールドの更新を許可していないため、このような更新を実行する唯一の方法は、リソースを削除して再作成することです。

更新がないときに、変更不可のフィールドの更新中にエラーが発生する

Google 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 リソース内の変更不可のフィールドの値を更新します。そのためには、次の手順を完了する必要があります。

Config Connector リソースの YAML 構成を更新して、cnrm.cloud.google.com/deletion-policy アノテーションを abandon に設定します。
更新された YAML 構成を適用して Config Connector リソースの削除ポリシーを更新します。
Config Connector リソースを放棄します。
gcloud CLI を使用して、対応する Google Cloud リソースのライブ状態を印刷します。
gcloud CLI の出力と Config Connector リソースの YAML 構成の不一致を見つけ、YAML 構成のそれらのフィールドを更新します。
更新された YAML 構成を適用して、放棄されたリソースを取得します。

リソースにステータスがない

リソースに status フィールドがない場合、Config Connector が正しく実行されていない可能性があります。Config Connector が動作していることを確認してください。

「Foo」という種類に一致する結果が見つからない

このエラーが発生した場合は、Kubernetes クラスタに Foo リソースタイプ用の CRD がインストールされていないことを示しています。

その種類が Config Connector でサポートされているリソースの種類であることを確認します。

その種類がサポートされている場合は、Config Connector のインストールが期限切れまたは無効のいずれかです。

GKE アドオンを使用して Config Connector をインストールした場合、インストールは自動的にアップグレードされます。Config Connector を手動でインストールした場合、手動アップグレードを実行する必要があります。

GitHub リポジトリを確認して、Config Connector のバージョンごとにサポートされているリソースの種類を確認してください（たとえば、Config Connector v1.44.0 でサポートされる種類はこちらです）。

ラベルが Google Cloud リソースに伝播されない

Config Connector は、metadata.labels にあるラベルを、基盤となる Google Cloud API にプロパゲートします。ただし、すべての Google Cloud リソースがラベルをサポートしているわけではない点に留意してください。リソースの REST API ドキュメント（PubSubTopic の API ドキュメントなど）を確認して、ラベルがサポートされているかどうかを確認します。

Webhook x509 の呼び出しに失敗: 証明書が以前の共通名フィールドに依存している

次の例のようなエラーが表示される場合は、証明書に関する問題が発生している可能性があります。

Error from server (InternalError): error when creating "/mnt/set-weaver-dns-record.yml": Internal error occurred: failed calling webhook "annotation-defaulter.cnrm.cloud.google.com": Post "https://cnrm-validating-webhook.cnrm-system.svc:443/annotation-defaulter?timeout=30s": x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0

この問題を回避するには、関連する証明書と Pod を削除します。

kubectl delete -n cnrm-system secrets cnrm-webhook-cert-abandon-on-uninstall
kubectl delete -n cnrm-system secrets cnrm-webhook-cert-cnrm-validating-webhook
kubectl delete -n cnrm-system pods -l "cnrm.cloud.google.com/component=cnrm-webhook-manager"

これらのリソースを削除すると、正しい証明書が再作成されます。

このエラーについて詳しくは、GitHub の問題をご覧ください。

リソース名で特殊文字を使用したことによるエラー

Kubernetes の metadata.name フィールドでは、特殊文字を使用できません。次の例のようなエラーが表示される場合、リソースの 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])?)*')

たとえば、次の SQLUser リソースでは、metadata.name に無効な文字が含まれています。

apiVersion: sql.cnrm.cloud.google.com/v1beta1
kind: SQLUser
metadata:
  name: test.example@example-project.iam
spec:
  instanceRef:
    name: test-cloudsql-db
  type: "CLOUD_IAM_USER"

このリソースを作成しようとすると、次のエラーが発生します。

Error from server (Invalid): error when creating "sqlusercrd.yaml": SQLUser.sql.cnrm.cloud.google.com "test.example@example-project.iam" is invalid: metadata.name: Invalid value: "test.example@example-project.iam": 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 名ではなく、有効な 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 は、リソースの名前として metadata.name の代わりに resourceID を使用します。

リソース仕様からフィールドを削除できない

（リソースの .yaml ファイルを更新して再適用するか、kubectl edit を使用してリソース仕様を編集して）Config Connector リソースの仕様からフィールドを削除しても、実際にはそのフィールドは Config Connector リソースの仕様または基盤となる Google Cloud リソースから削除されることはありません。代わりに、仕様からフィールドを削除すると、そのフィールドは externally-managed になるだけです。

基盤となる Google Cloud リソースのフィールドの値を空またはデフォルトに変更するには、Config Connector リソース仕様のフィールドを完全に取り除く必要があります。

リスト型フィールドの場合は、[] を使用してフィールドを空のリストに設定します。

次の例は、削除する targetServiceAccounts フィールドを示しています。
```
spec:
  targetServiceAccounts:
    - external: "foo-bar@foo-project.iam.gserviceaccount.com"
    - external: "bar@foo-project.iam.gserviceaccount.com"
```
このフィールドを削除するには、値を空に設定します。
```
spec:
  targetServiceAccounts: []
```
プリミティブ型フィールドの場合は、次のいずれかを使用してフィールドを空に設定します。

タイプ空の値

文字列 ""

bool "false"

整数 0

次の例は、削除する identityNamespace フィールドを示しています。
```
spec:
  workloadIdentityConfig:
    identityNamespace: "foo-project.svc.id.goog"
```
このフィールドを削除するには、値を空に設定します。
```
spec:
  workloadIdentityConfig:
    identityNamespace: ""
```
オブジェクト型のフィールドの場合、現時点では、オブジェクト型のフィールド全体を「NULL」に設定する簡単な方法は Config Connector にはありません。先ほどのガイダンスに従って、オブジェクトタイプのサブフィールドを空またはデフォルトに設定して、動作するかどうかを確認できます。

タイプ	空の値
文字列	""
bool	"false"
整数	0

KNV2005: syncer がリソースを過剰に更新する

Config Sync を使用していて、Config Connector リソースに KNV2005 エラーが表示される場合は、Config Sync と Config Connector のリソースが競合している可能性があります。

ログメッセージの例:

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 Sync で指定されず、Config Connector によってデフォルトで設定されるフィールドは、Config Sync で無視されます。したがって、ほとんどのフィールドでは、Config Sync と Config Connector が同じフィールドを異なる値に更新することはありません。

ただし、リストフィールドは例外です。Config Connector がオブジェクトフィールドのサブフィールドをデフォルトに設定する場合と同様に、Config Connector は、リスト内のオブジェクトのサブフィールドもデフォルトに設定できます。ただし、Config Connector リソースのリストフィールドはアトミックであるため、サブフィールドのデフォルトはリストの値全体を変更するとみなされます。

したがって、Config Sync によってリストフィールドが設定され、Config Connector がそのリスト内のサブフィールドはデフォルトで設定されると、Config Sync と Config Connector に競合が発生します。

この問題を回避するには、次のオプションがあります。

Config Connector がリソースを設定しようとするものと一致するように、Config Sync リポジトリのリソースマニフェストを更新します。

これを行う方法の一つは、構成の同期を一時的に停止し、Config Connector がリソースの調整を完了するのを待ってから、Kubernetes API サーバー上のリソースと一致するようにリソースマニフェストを更新することです。
アノテーションを client.lifecycle.config.k8s.io/mutation を ignore に設定して、Kubernetes API サーバーでのリソースの更新に Config Sync が反応しないようにします。Config Sync でオブジェクトのミューテーションを無視させる方法をご覧ください。
リソースのアノテーション cnrm.cloud.google.com/state-into-spec を absent に設定して、Config Connector がリソースの仕様を完全に更新しないようにします。このアノテーションは、すべてのリソースでサポートされているわけではありません。ご自身のリソースがアノテーションをサポートしているかどうかを確認するには、対応するリソースのリファレンスページをご覧ください。アノテーションの詳細を確認する。

`failed calling webhook`

Config Connector がアンインストールできない状態になる場合があります。これは、通常、Config Connector アドオンを使用して、Config Connector CRD を削除する前に 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

このエラーを解決するには、まず 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 のアンインストールを続行できます。

IAMPolicy、IAMPartialPolicy、IAMPolicyMember による更新エラー

そのサービスアカウントに依存する IAMPolicy、IAMPartialPolicy、IAMPolicyMember リソースをクリーンアップする前に IAMServiceAccount Config Connector リソースを削除すると、Config Connector は調整中にそれらの IAM リソースで参照されるサービスアカウントを見つけることができなくなります。その結果、UpdateFailed ステータスで次のようなエラーメッセージが表示されます。

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

この問題を解決するには、サービスアカウントを確認し、その IAM リソースに必要なサービスアカウントが削除されているかどうかを確認します。サービスアカウントが削除された場合は、関連する IAM Config Connector リソースもクリーンアップします。IAMPolicyMember については、リソース全体を削除します。IAMPolicy と IAMParitialPolicy については、削除されたサービスアカウントを含むバインディングのみを削除します。ただし、このようなクリーンアップを行っても、Google Cloud のロールバインディングがすぐに削除されるわけではありません。削除されたサービスアカウントが保持されるため、Google Cloud ロールバインディングは 60 日間保持されます。詳細については、Google Cloud IAM のドキュメントのサービスアカウントの削除をご覧ください。

この問題を回避するには、参照先の IAMServiceAccount を削除する前に、必ず IAMPolicy、IAMPartialPolicy、IAMPolicyMember の Config Connector リソースをクリーンアップする必要があります。

Config Connector によってリソースが削除される

Config Connector は、外部の原因がなければリソースを削除することはありません。たとえば、Argo CD などの構成管理ツールや、カスタマイズされた API クライアントを使用して kubectl delete を実行すると、リソースが削除される可能性があります。

よくある誤解は、Config Connector が主導してクラスタ内の一部のリソースを削除するというものです。たとえば、Config Connector を使用している場合、Config Connector コントローラマネージャーからコンテナログメッセージまたは Kubernetes クラスタ監査ログのいずれかに、特定のリソースに対する削除リクエストが届いていることに気づきます。これらの削除リクエストは、外部トリガーの結果であり、Config Connector は削除リクエストを調整しようとしているのです。

リソースが削除された理由を特定するには、対応するリソースに送信された最初の削除リクエストを確認する必要があります。詳しく調べるには、Kubernetes クラスタの監査ログを確認することをおすすめします。

たとえば、GKE を使用している場合は、GKE クラスタ監査ログに関して、Cloud Logging を使用してクエリを実行できます。たとえば、名前空間 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 の OOMKilled

Config Connector コントローラ Pod に OOMKilled エラーが発生した場合は、許容範囲を超えるメモリを使用したためコンテナまたは Pod 全体が停止したことを示しています。これは、kubectl describe コマンドを実行して確認できます。Pod のステータスは OOMKilled または Terminating と表示される場合があります。さらに、Pod のイベントログを調査すると、OOM 関連のイベントが発生したことが判明する場合があります。

kubectl describe pod POD_NAME -n cnrm-system

POD_NAME は、トラブルシューティング対象の Pod に置き換えます。

この問題に対処するには、ControllerResource カスタムリソースを使用して、Pod のメモリリクエストとメモリ上限を増やします。

`PodSecurityPolicy` が原因でアップグレードできない

Config Connector アドオンから手動インストールに切り替え、Config Connector を新しいバージョンにアップグレードした後、PodSecurityPolicy を使用すると cnrm Pod の更新が妨げられる可能性があります。

PodSecurityPolicy がアップグレードを妨げていることを確認するには、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 リソースが削除時に停止しており、単純に Kubernetes クラスタから対象のリソースを削除する処理を行う必要がある場合は、finalizer を削除することで強制的に削除できます。

リソースのファイナライザを削除するには、kubectl edit を使用してリソースを編集し、metadata.finalizers フィールドを削除してからファイルを保存して、Kubernetes API Server に対して行った変更の内容を保持します。

リソースのファイナライザを削除することによって、Kubernetes クラスタから直ちにリソースを削除できるため、Config Connector は基盤となる Google Cloud リソースの削除を完了できない可能性があります（ただし、そうでない場合も考えられます）。つまり、後で Google Cloud リソースを手動で削除することもできます。

モニタリング

指標

Prometheus を使用して、Config Connector から指標を収集して表示できます。

ロギング

すべての Config Connector Pod は、構造化ログを JSON 形式で出力します。

コントローラ Pod のログは、リソース調整に関する問題のデバッグに特に有用です。

ログメッセージで以下のフィールドをフィルタすることで、特定のリソースのログをクエリできます。

logger: 小文字のリソースの種類が含まれます。たとえば、PubSubTopic リソースには pubsubtopic-controller の logger が存在します。
resource.namespace: リソースの名前空間が含まれます。
resource.name: リソースの名前が含まれます。

Cloud 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 サポートにお問い合わせください。

Config Connector のトラブルシューティング

基本的なトラブルシューティングの手法

Config Connector のバージョンを確認する

リソースのステータスとイベントを確認する

Config Connector が動作していることを確認する

コントローラのログを確認する

リソースを放棄して取得します。

一般的な問題

リソースが 5～15 分ごとに更新される

「終了しています」と表示されたまま停止している名前空間の削除

プロジェクトが削除された後に「DeleteFailed」と表示されたまま停止しているリソースの削除

Compute Engine メタデータが定義されていない

エラー 403: リクエストに十分な認証スコープがありません

403 Forbidden: 呼び出し元に権限がありません。Workload Identity Federation for GKE のドキュメントをご覧ください。

エラー 403: 呼び出し元に IAM 権限がありません

バージョンがConfig Connector アドオンのインストールでサポートされていない

変更不可のフィールドを変更できない

更新がないときに、変更不可のフィールドの更新中にエラーが発生する

リソースにステータスがない

「Foo」という種類に一致する結果が見つからない

ラベルが Google Cloud リソースに伝播されない

Webhook x509 の呼び出しに失敗: 証明書が以前の共通名フィールドに依存している

リソース名で特殊文字を使用したことによるエラー

リソース仕様からフィールドを削除できない

KNV2005: syncer がリソースを過剰に更新する

failed calling webhook

IAMPolicy、IAMPartialPolicy、IAMPolicyMember による更新エラー

Config Connector によってリソースが削除される

コントローラ Pod の OOMKilled

PodSecurityPolicy が原因でアップグレードできない

強制クリーンアップ

モニタリング

指標

ロギング

Cloud Logging を使用した高度なログクエリ

その他の参考情報

`failed calling webhook`

`PodSecurityPolicy` が原因でアップグレードできない