Config Sync の既知の問題

削除されたパッケージについて報告された指標

RootSync オブジェクトまたは RepoSync オブジェクトを削除したものの同じ名前の ResourceGroup オブジェクトを削除しない場合、Config Sync はその ResourceGroup オブジェクトの次の指標を引き続き報告します。

• rg_reconcile_duration_seconds
• resource_group_total
• resource_count
• ready_resource_count
• resource_ns_count
• cluster_scoped_resource_count
• crd_count
• kcc_resource_count
• pipeline_error_observed

回避策:

ResourceGroup オブジェクトを削除します。

kubectl delete resourcegroup RESOURCE_GROUP_NAME -n config-management-system

RESOURCE_GROUP_NAME は、削除する必要がある ResourceGroup オブジェクトの名前に置き換えます。ResourceGroup の命名の詳細については、ResourceGroup コントローラと ResourceGroup オブジェクトをご覧ください。

Reconciler のスケジュールが設定できない

Config Sync Reconciler には、RootSync または RepoSync の構成に応じて、さまざまな量のリソースが必要です。特定の構成では、他の構成よりも多くのリソースが必要になります。

Reconciler がスケジューリングできない場合は、ノードで使用可能な量を超えるリソースをリクエストしている可能性があります。

Standard モードの GKE クラスタを使用している場合、Reconciler リソース リクエストは非常に低く設定されます。この設定は、スロットリングやパフォーマンス低下につながる場合でもあっても、スケジューリングを可能にすることを目的として選択されています。これにより、Config Sync は小規模なクラスタや小規模なノードでも機能します。ただし、GKE Autopilot クラスタでは、同期中の使用状況をより現実的に表すように、Reconciler リクエストが高い値に設定されます。

回避策:

GKE Autopilot または GKE Standard でノード自動プロビジョニングを有効にすると、リソースのリクエスト数を確認して適切なサイズのノードを作成し、スケジューリングを行うことができます。ただし、ノードまたはノード インスタンス サイズを手動で構成する場合は、Reconciler Pod のリソース要件に合わせて、それらの設定の調整が必要になる可能性があります。

修正済み: エクスポート失敗: 認識できない指標ラベル

バージョン 1.15.0 では、Config Sync によって多くの指標に type ラベルと commit ラベルが追加されました。これらのラベルによって指標のカーディナリティが増加し、エクスポートされる指標の数が増加しました。Cloud Monarch にエクスポートする際にこれらのラベルを除外する属性処理も追加されましたが、このフィルタリングが誤って構成されたため、otel-collector ログに変換エラーが発生していました。

エクスポートに失敗しました。権限が却下されました

デフォルトでは、Reconciler マネージャーがアプリケーションのデフォルト認証情報を検出すると、Otel コレクタは Prometheus、Cloud Monitoring、Monarch に指標をエクスポートするように構成されます。

回避策:

Cloud Monitoring を構成していないか、Cloud Monitoring と Cloud Monarch を無効にしていない場合は、otel-collector がエラーをログに記録します。

カスタム構成で otel-collector がクラッシュする

デフォルトの ConfigMap のいずれか（otel-collector または otel-collector-google-cloud）を変更または削除しようとすると、otel-collector でエラーやクラッシュが発生し、必要な ConfigMap を読み込めない場合があります。

回避策:

指標のエクスポート構成をカスタマイズするには、config-management-monitoring Namespace に otel-collector-custom という名前の ConfigMap を作成します。

修正済み: nomos status と nomos bugreport が Pod で機能しない

バージョン 1.17.2 より前の nomos では、nomos bugreport と nomos status は Kubernetes Pod 内で実行している場合にのみローカル クラスタに接続できました。nomos バージョン 1.17.2 では、承認方法が kubectl のような動作に変更されました。この変更により、デフォルトのターゲットがローカル クラスタになりました。KUBECONFIG 環境変数を指定することで、この構成をオーバーライドできます。

Config Sync が自身と競合している

Config Sync が自身とコントローラの競合状態になっているように見えることがあります。この問題は、Git リポジトリ内のリソースのオプション フィールドにデフォルト値を設定した場合に発生します。たとえば、RoleBinding のサブジェクトに対して apiGroup: "" を設定すると、apiGroup フィールドがオプションになり、空の文字列がデフォルト値になるため、これがトリガーされます。文字列、ブール値、整数のフィールドのデフォルト値は、それぞれ ""、false、0 です。

回避策:

リソース宣言からフィールドを削除します。

Config Sync が Config Connector リソースと競合している

Config Sync と Config Connector が StorageBucket などのリソースに対して競合状態になっているように見える場合があります。この問題は、信頼できる情報源のリソース spec.lifecycleRule.condition.withState のオプション フィールドの値を設定していない場合に発生します。

回避策:

この問題を回避するには、リソース宣言に withState=ANY フィールドを追加します。または、cnrm.cloud.google.com/state-into-spec: absent アノテーションを使用してリソースを破棄して再取得します。

修正済み: GitHub での Git SSH 認証エラー

git-sync v4.2.1 には、SSH 使用時にリポジトリ URL からユーザー名が削除されるバグがあり、GitHub に接続するときに認証が失敗します。この場合、ユーザーは git である必要があります。

git のエラー メッセージは次のとおりです。git-sync@github.com: Permission denied (publickey).\r\nfatal: Could not read from remote repository.

回避策:

別の認証方法を使用してください。

修正済み: Cloud Source Repositories の認証情報が定期的に無効になる

Cloud Source Repositories の認証トークンが期限切れになると、Config Sync が定期的にエラーになることがあります。この問題は、トークンの更新が期限切れになるまで待ってからトークンを更新すると発生します。

バージョン 1.18.0 以降では、トークンの有効期限が切れてから 5 分以内に最初のリクエストが行われると、トークンが更新されます。これにより、認証情報が実際に無効でない限り、無効な認証情報エラーを防ぐことができます。

修正済み: リポジトリ同期エラー: コンテキストの期限超過

1.17.0 より前のバージョンでは、Config Sync はデフォルトで Git リポジトリのすべての履歴をチェックアウトしています。このため、commit が多い大規模なリポジトリでは、取得リクエストのタイミングがずれる可能性があります。

バージョン 1.17.0 以降では、Git の取得は --depth=1 で実行され、最新の commit のみが取得されます。これにより、ソースの取得が高速化され、ほとんどのタイムアウトが回避されます。また、Git サーバーの負荷も軽減されます。

アップグレード後もこの問題が発生する場合は、信頼できる情報源にファイルが多い、Git サーバーのレスポンスが遅い、または他のネットワークに関する問題が原因になっている可能性があります。

修正済み: OCI ソースのアクセス トークンを生成できない

Config Sync が信頼できる情報源として OCI を使用し、Workload Identity Federation for GKE で認証するよう構成されている場合、Config Sync がコンテナ レジストリで認証を試みた際に一時的な KNV2004 エラーが発生することがあります。

この問題は、oauth2 ライブラリがトークンの有効期限が切れた後にのみ認証トークンを更新することにより発生します。

エラー メッセージに、"oauth2/google: unable to generate access token" または "ID Token issued at (xxx) is stale to sign-in." というテキストが含まれる場合があります。

回避策:

Config Sync が信頼できる情報源からのフェッチを次に試行する際に、エラーは自動的に解決します。

Config Sync で複数回エラーが発生すると、再試行の頻度が低下します。Config Sync を強制的に再試行するには、Reconciler Pod を削除します。このアクションにより、Config Sync は Reconciler Pod を再作成し、信頼できる情報源からすぐにフェッチします。

    kubectl delete pod -n config-management-system RECONCILER_NAME
    

修正済み: Git ロックファイルが残っている

git-sync コンテナから次のようなエラーが返された場合は、前の git 呼び出しが失敗し、コンテナにロックファイルが残っている可能性があります。

    KNV2004: error in the git-sync container: ... fatal: Unable to create '/repo/source/.git/shallow.lock': File exists. ...
    

回避策:

この問題を回避するには、影響を受ける Reconciler Pod を再起動して、新しいエフェメラル ボリュームを Pod に割り当てます。

    kubectl delete pod -n config-management-system RECONCILER_NAME
    

ミューテーションを無視するアノテーションが適用されない

Config Sync 適用ツールのバグにより、client.lifecycle.config.k8s.io/mutation アノテーションが存在する場合でも、宣言された構成の変更が適用されます。これにより、クラスタ内のオブジェクトの状態が上書きされる可能性があります。

回避策:

configmanagement.gke.io/managed: disabled アノテーションを追加すれば、管理対象オブジェクトの管理を停止できます。ただし、管理を無効にすると、オブジェクトがクラスタから削除された場合に Config Sync がオブジェクトを再作成できなくなります。また、今後は信頼できる情報源で更新が適用されなくなります。

修正: API 検出エラーにより、マネージド オブジェクトが Not Found と誤ってマークされる

API Service バックエンドが正常でない場合、API 検出でエラーが発生する可能性があります。ResourceGroup コントローラの起動中、更新後、またはスケジュール変更後にこの問題が発生すると、リソース キャッシュの初期化に失敗し、すべてのマネージド オブジェクトが ResourceGroup ステータスで Not Found として報告されます。

この問題は、metrics-server の状態が正常ではない場合によく発生します。

回避策:

metrics-server が正常な状態に戻ったら、resource-group-controller Pod を再起動します。

    kubectl delete pod -n resource-group-system RESOURCE_GROUP_CONTROLLER_NAME
    

監査ログ内の多数の無効な PATCH リクエスト

Config Sync 修復ツールは、ドライランを使用してドリフトを検出します。これにより、PATCH が永続化されていない場合でも、監査ログでドライランと通常のリクエストを区別しないため、監査ログに PATCH リクエストが表示される場合があります。

回避策:

修正済み: Config Sync がブランチから最新の commit を pull できない

Config Sync バージョン 1.17.0、1.17.1、1.17.2 では、同じブランチが複数のリモートで参照されていて、それらが同期されていない場合、Config Sync が特定のブランチの HEAD から最新の commit を pull できないという問題が発生する可能性があります。たとえば、リモート リポジトリ origin の main ブランチは、リモート リポジトリ upstream の同じブランチの前に存在する場合がありますが、Config Sync は最後のラインの commit SHA のみを取得します。このため、それが最新の commit ではない場合があります。

たとえば、次のような問題が発生します。

git ls-remote -q [GIT_REPOSITORY_URL] main  main^{}
244999b795d4a7890f237ef3c8035d68ad56515d    refs/heads/main               # the latest commit
be2c0aec052e300028d9c6d919787624290505b6    refs/remotes/upstream/main    # the commit Config Sync pulls from

バージョン 1.17.3 以降では、git-sync の依存関係が別の取得メカニズムで更新されました。

アップグレードできない場合は、Git ブランチ（spec.git.branch）に設定された値に関係なく、Git リビジョン（spec.git.revision）を最新の commit SHA に設定できます。Git 構成の詳細については、Git リポジトリの構成をご覧ください。

Config Sync が reconciler Deployment に非公開レジストリを使用しない場合

非公開レジストリが構成されている場合、Config Sync はすべての Deployment のイメージを置き換える必要があります。ただし、Config Sync は、Reconciler Deployment のイメージのイメージ レジストリに代わるものではありません。

回避策:

この問題を回避するには、containerd でイメージ レジストリ ミラーを構成します。

修正済み: Config Sync Reconciler がクラッシュループする

Config Sync バージョン 1.17.0 以降では、一部の Kubernetes プロバイダで、Reconciler が REST 構成を作成できないという問題が発生することがあります。

この問題は Reconciler ログに次の例のように表示されます。

Error creating rest config: failed to build rest config: reading local kubeconfig: loading REST config from "/.kube/config": stat /.kube/config: no such file or directory

更新されたインベントリをクラスタに書き込めませんでした

Config Sync が ResourceGroup オブジェクトのステータスの更新に失敗すると、Reconciler ログに次のようなエラーが断続的に書き込まれる場合があります。

    KNV2009: task failed (action: "Inventory", name: "inventory-set-0"): failed to write updated inventory to cluster: Operation cannot be fulfilled on resourcegroups.kpt.dev "root-sync": the object has been modified; please apply your changes to the latest version and try again
    

このエラーは、Reconciler と ResourceGroup Controller 間の競合状態が原因で発生します。Reconciler が ResourceGroup 仕様を更新する前に ResourceGroup Controller が ResourceGroup のステータスを更新すると、KNV2009 エラーが発生することがあります。

回避策:

この問題の回避策はありません。エラーは自然に解決されます。

Terraform を使用して Config Sync をインストールまたはアップグレードできない

Terraform バージョン 5.41.0 では、google_gke_hub_feature_membership に新しいフィールド config_sync.enabled が導入されました。このフィールドのデフォルト値は false であるため、Terraform がバージョン 5.41.0 にアップグレードされると、Config Sync のインストールが失敗します。

回避策:

• google_gke_hub_feature_membership リソースを使用する場合は、config_sync.enabled を手動で true に設定します。
• acm サブモジュールを使用している場合は、別の方法に切り替えて Config Sync をインストールすることをおすすめします。切り替えられない場合は、v33.0.0 にアップグレードしてください。

Google Cloud コンソールの Config Sync ダッシュボードにデータがない旨のエラーが表示される

Google Cloud コンソールのダッシュボードに、Config Sync クラスタに関する「データがない」や「クラスタ認証情報が無効」といった内容のエラーが表示されることがあります。この問題は、GDC（VMware）クラスタまたは GDC（ベアメタル）クラスタにログインしていない場合に発生することがあります。

回避策:

Google Cloud GDC（VMware）または GDC（Bare Metal）クラスタのコンソールにこういったエラーが表示された場合は、GKE Identity Service または Connect Gateway を使用してクラスタにログインしていることを確認します。