**このページの改善にご協力ください** このユーザーガイドに貢献するには、すべてのページの右側のペインにある「**GitHub でこのページを編集する**」リンクを選択してください。 # Argo CD 機能に関する問題をトラブルシューティングする **注記** EKS の機能は完全に管理され、クラスターの外部で実行されます。コントローラーの名前空間に直接アクセスすることはできません。コントローラーの動作の可視化のためにコントローラーのログ配信を設定できます。「[EKS 機能コントローラーログにアクセスする](capabilities-controller-logs.md)」を参照してください。トラブルシューティングでは、機能のヘルス、アプリケーションのステータス、および設定に焦点を当てています。 ## 機能が ACTIVE であるのにアプリケーションが同期しない Argo CD 機能のステータスが `ACTIVE` であるのにアプリケーションが同期しない場合は、機能のヘルスとアプリケーションのステータスを確認してください。 **機能のヘルスを確認する**: 機能のヘルスとステータスの問題は、EKS コンソールまたは AWS CLI を使用して表示できます。 **コンソール:** 1. https://console.aws.amazon.com/eks/home\#/clusters で Amazon EKS コンソールを開きます。 1. クラスター名を選択します。 1. **[オブザーバビリティ]** タブを選択します。 1. **[クラスターを監視する]** を選択します。 1. **[機能]** タブを選択すると、すべての機能のヘルスとステータスが表示されます。 **AWS CLI**: ``` # View capability status and health aws eks describe-capability \ --region {{region-code}} \ --cluster-name {{my-cluster}} \ --capability-name {{my-argocd}} # Look for issues in the health section ``` **一般的な原因:** + **リポジトリが設定されていない**: Git リポジトリが Argo CD に追加されていません。 + **認証に失敗した**: SSH キー、トークン、または CodeCommit 認証情報が無効です。 + **Application が作成されていない**: クラスターに Application リソースが存在しません。 + **同期ポリシー**: 手動同期が必要です (自動同期は有効になっていません)。 + **IAM アクセス許可**: CodeCommit または Secrets Manager に対するアクセス許可がありません。 **アプリケーションのステータスを確認する**: ``` # List applications kubectl get application -n argocd # View sync status kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.sync.status}' # View application health kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.health}' ``` **アプリケーションの条件を確認する**: ``` # Describe application to see detailed status kubectl describe application {{my-app}} -n argocd # View application health kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.health}' ``` ## アプリケーションが「進行中」のまま変化しない アプリケーションが `Progressing` であるのに `Healthy` に達しない場合は、アプリケーションのリソースステータスとイベントを確認してください。 **リソースのヘルスを確認する**: ``` # View application resources kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.resources}' # Check for unhealthy resources kubectl describe application {{my-app}} -n argocd | grep -A 10 "Health Status" ``` **一般的な原因:** + **デプロイの準備が完了していない**: ポッドの起動に失敗したか、準備状況プローブが失敗しています。 + **リソースの依存関係**: リソースが他のリソースの準備を待っています。 + **イメージプルエラー**: コンテナイメージにアクセスできません。 + **リソースが不十分**: クラスターでポッドの CPU やメモリが不足しています。 **ターゲットクラスターの設定を検証する** (マルチクラスター設定の場合): ``` # List registered clusters kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster # View cluster secret details kubectl get secret {{cluster-secret-name}} -n argocd -o yaml ``` ## リポジトリの認証に失敗する Argo CD が Git リポジトリにアクセスできない場合は、認証設定を確認してください。 **CodeCommit リポジトリの場合**: IAM 機能ロールに CodeCommit へのアクセス許可があることを確認します。 ``` # View IAM policies aws iam list-attached-role-policies --role-name {{my-argocd-capability-role}} aws iam list-role-policies --role-name {{my-argocd-capability-role}} # Get specific policy details aws iam get-role-policy --role-name {{my-argocd-capability-role}} --policy-name {{policy-name}} ``` ロールにはリポジトリに対する `codecommit:GitPull` アクセス許可が必要です。 **プライベート Git リポジトリの場合**: リポジトリの認証情報が正しく設定されていることを確認します。 ``` # Check repository secret exists kubectl get secret -n argocd {{repo-secret-name}} -o yaml ``` シークレットに適切な認証情報 (SSH キー、トークン、またはユーザー名/パスワード) が含まれていることを確認します。 **Secrets Manager を使用するリポジトリの場合**: ``` # Verify IAM Capability Role has Secrets Manager permissions aws iam list-attached-role-policies --role-name {{my-argocd-capability-role}} # Test secret retrieval aws secretsmanager get-secret-value --secret-id {{arn:aws:secretsmanager:region-code:111122223333:secret:my-secret}} ``` ## マルチクラスターデプロイに関する問題 アプリケーションがリモートクラスターにデプロイされていない場合は、クラスターの登録とアクセスの設定を確認してください。 **クラスターの登録を確認する**: ``` # List registered clusters kubectl get secret -n argocd -l argocd.argoproj.io/secret-type=cluster # Verify cluster secret format kubectl get secret {{CLUSTER_SECRET_NAME}} -n argocd -o yaml ``` `server` フィールドに、Kubernetes API URL ではなく EKS クラスター ARN が含まれていることを確認します。 **ターゲットクラスターのアクセスエントリを確認する**: ターゲットクラスターで、Argo CD 機能ロールにアクセスエントリがあることを確認します。 ``` # List access entries (run on target cluster or use AWS CLI) aws eks list-access-entries --cluster-name {{target-cluster}} # Describe specific access entry aws eks describe-access-entry \ --cluster-name {{target-cluster}} \ --principal-arn {{arn:aws:iam::111122223333:role/my-argocd-capability-role}} ``` **クロスアカウントの IAM アクセス許可を確認する**: クロスアカウントデプロイの場合、ターゲットクラスターで Argo CD 機能ロールにアクセスエントリがあることを確認します。マネージド機能は、IAM ロールの引き受けではなく、クロスアカウントアクセスの EKS アクセスエントリを使用します。 マルチクラスター設定の詳細については、「[ターゲットクラスターを登録する](argocd-register-clusters.md)」を参照してください。 ## アプリケーションの同期時間の増加 アプリケーションが同期しているが、予想以上に時間がかかる場合は、次の診断ステップを使用して原因を特定します。 ### 最後の同期時間を確認する アプリケーションが最後に同期されたタイミングをレビューして、遅延を確認します: ``` # View last sync time for all applications kubectl get application -n argocd -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.operationState.finishedAt}{"\n"}{end}' # View last sync time for a specific application kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.operationState.finishedAt}' ``` ### アプリケーションの条件を確認する 調整キューの遅延に関するアプリケーション条件をレビューします: ``` # Check conditions on an application kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.conditions}' ``` ### targetRevision 設定を確認する `targetRevision: HEAD` を使用するアプリケーションは、リポジトリへのコミットごとにマニフェストキャッシュを無効化するため、同期時間が遅くなります。 ``` # List applications using HEAD as targetRevision kubectl get application -n argocd -o jsonpath='{range .items[?(@.spec.source.targetRevision=="HEAD")]}{.metadata.name}{"\n"}{end}' ``` ### 一般的な原因 + **ウェブフック設定なし**: ウェブフックがない場合、Argo CD はデフォルトの 6 分間隔でリポジトリをポーリングします。これにより、新しいコミットの検出が遅れます。 + **HEAD に設定された targetRevision**: リポジトリへのコミットごとにマニフェストキャッシュが無効化されます。次に、Argo CD は各調整でマニフェストを再生成します。 + **大規模または複雑な Git リポジトリ**: モノレポまたは複雑な Helm チャートでは、処理するファイルやテンプレートの量が多いため、マニフェストの生成が遅くなります。 + **単一のアプリケーションでの多数の Kubernetes リソース**: 多くのリソースを管理するアプリケーションでは、Argo CD が各リソースの状態を追跡する必要があるため、クラスターキャッシュの同期が遅くなります。 ### 緩和策 + **Git ウェブフックを設定する**: ウェブフックは、変更がプッシュされるとすぐに Argo CD に通知し、デフォルトのポーリング間隔をバイパスします。設定手順については、「[Argo CD に関する考慮事項](argocd-considerations.md)」を参照してください。 + **特定のブランチ名またはコミット SHA を使用する**: 同期の間にマニフェストキャッシュを保持するには、`HEAD` の代わりに `targetRevision` を ブランチ名またはコミット SHA に設定します。 + **大きなモノレポジトリを分割する**: 大きなリポジトリをより小さく、焦点を絞ったリポジトリに分割して、マニフェストの生成時間を短縮します。 + **アプリケーションあたりのリソースを削減する**: Kubernetes リソースが多いアプリケーションを複数の小さなアプリケーションに分割して、クラスターキャッシュの同期時間を短縮します。 + **コントローラーログ配信を有効にする**: コントローラーログは、調整動作とキュー処理を可視化します。設定手順については、「[EKS 機能コントローラーログにアクセスする](capabilities-controller-logs.md)」を参照してください。 ## アプリケーションが繰り返し同期するか、同期がスタックする アプリケーションが同期されてすぐに `OutOfSync` になる場合、または同期ループでスタックしたままの場合、通常、Git が定義するものとクラスター内に存在するものの間のドリフトが原因です。ベースライン診断から始めます。 ### 診断情報を収集する ``` # View current sync and health status argocd app get {{my-app}} # Show exact fields that differ between Git and live state argocd app diff {{my-app}} # Check whether the app has ever reached a stable state argocd app history {{my-app}} ``` `argocd app diff` コマンドは最も便利な開始点です。アプリケーションが同期しない原因となるフィールドが正確に表示されます。 ### セルフマネージド証明書によってドリフトが発生する cert-manager、OPA Gatekeeper、KEDA などのコントローラーは、ランタイム時に証明書を生成します。これらのランタイム値は Git にないため、Argo CD はすべての調整でドリフトを検出します。 症状は次のとおりです: + アプリケーションの同期後、すぐに `OutOfSync` が表示される + ドリフトが、ウェブフック `caBundle` フィールドまたは TLS シークレット `data`フ ィールドでの変更を示す これを解決するには、影響を受けるフィールドで `ignoreDifferences` を追加し、同期オプションで `RespectIgnoreDifferences` を有効にします。 ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: ignoreDifferences: - group: admissionregistration.k8s.io kind: ValidatingWebhookConfiguration jsonPointers: - /webhooks/0/clientConfig/caBundle - group: "" kind: Secret jsonPointers: - /data/tls.crt - /data/tls.key syncPolicy: syncOptions: - RespectIgnoreDifferences=true ``` ### 自己修復によって起動の遅いワークロードが中断される `selfHeal` を有効にすると、Argo CD はドリフトを検出したときにアプリケーションを再同期します。ワークロードの起動に 30～60 秒かかると、ワークロードが `Healthy` になる前に自己修復がトリガーされます。`prune` を有効にすると、部分的に起動されたリソースが破損する可能性があります。 これを解決するには、まず基盤となるドリフトを修正します (証明書シナリオを参照)。ドリフトが原因でない場合は、Git を通じてのみ管理するワークロードの自己修復を無効にすることを検討してください。 ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: syncPolicy: automated: selfHeal: false prune: false ``` **注記** 自己修復バックオフタイミングは、インスタンスレベルのコントローラー設定です。無効にするのではなく自己修復タイミングを調整する必要がある場合は、AWS サポートケースを開きます。 ### ApplicationSet またはリソース所有権が衝突する 2 つの Applications または ApplicationSets が同じ Kubernetes リソースを管理している場合、Argo CD には `SharedResourceWarning` が表示されます。リソースが安定状態に到達することはありません。これは通常、共有リソース名が環境またはクラスターごとにスコープされていない場合に発生します。 これを解決するには: + 競合しているリソースを所有者ごとに一意にします。リソース名に環境またはクラスターサフィックスを追加します。 + ApplicationSet の名前を変更するときは、既存のリソースが破壊的に破損されないように、最初に `preserveResourcesOnDeletion: true` を設定します。 ``` apiVersion: argoproj.io/v1alpha1 kind: ApplicationSet metadata: name: my-appset spec: syncPolicy: preserveResourcesOnDeletion: true ``` ### リソースファイナライザーによる削除のスタック アプリケーションが `Terminating` 状態でスタックする場合、または「削除のために N 個のオブジェクトが残っている」と表示される場合、`resources-finalizer.argocd.argoproj.io` ファイナライザーはすべてのマネージドリソースが削除されるまで削除をブロックします。独自の未処理のファイナライザーを持つマネージドリソースは、削除を無期限にブロックします。 確認するには、削除タイムスタンプがあるが、削除されていないリソースを一覧表示します。 ``` kubectl get all -n {{my-namespace}} -o json | \ jq '.items[] | select(.metadata.deletionTimestamp != null) | {name: .metadata.name, kind: .kind, finalizers: .metadata.finalizers}' ``` これを解決するには: + ブロッキングファイナライザーを所有するコントローラーが正常で実行中であることを確認します。 + 所有コントローラーが正常であるが、ファイナライザーが処理されていない場合は、スタックしたリソースからブロッキングファイナライザーを削除します。 ``` kubectl patch {{resource-kind}} {{resource-name}} -n {{my-namespace}} \ --type json -p '[{"op": "remove", "path": "/metadata/finalizers/0"}]' ``` ### 同期が失敗しても同じリビジョンに自動的に再試行されない 特定のリビジョンへの同期が失敗すると、Argo CD は同じリビジョンを自動再試行しません。これは通常、重複する環境変数キーからの `ComparisonError` などのマニフェストの欠陥が原因で発生します。 アプリケーションのステータスをチェックして確認します: ``` argocd app get {{my-app}} # Look for: Operation: Sync Phase: Failed Revision: ``` これを解決するには、Git リポジトリのマニフェストの不具合を修正し、新しいコミットをプッシュします。または、手動同期をトリガーします: ``` argocd app sync {{my-app}} ``` ### モノレポのコミットチャーンが広範な再生成をトリガーする 多くのアプリケーションが同じリポジトリで `HEAD` を追跡している場合、そのリポジトリへのコミットはすべてのアプリケーションの `HEAD` を変更します。これにより、それらのファイルが変更されなかった場合でも、すべてのアプリケーションに対してマニフェストの再生成がトリガーされます。`targetRevision` とキャッシュの詳細については、このページの「アプリケーション同期時間の増加」セクションを参照してください。 各アプリケーションが使用するファイルのみに再生成をスコープするには、`manifest-generate-paths` 注釈を追加します。 ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app annotations: argocd.argoproj.io/manifest-generate-paths: /apps/my-app spec: source: repoURL: https://github.com/my-org/my-monorepo.git targetRevision: HEAD path: apps/my-app ``` この注釈を使用すると、Argo CD は指定されたパスの下にあるファイルが変更された場合にのみマニフェストを再生成します。アプリケーション間で使用されている共有ライブラリでは、複数のパスをセミコロン (`;`) で区切って指定できます。 可能な場合は、`HEAD` の代わりにブランチ名またはタグに `targetRevision` をピン留めします。 ### Kubernetes のデフォルトおよび変異ウェブフックによりファントム差分が発生する 同期の直後にアプリケーションが `OutOfSync` を表示する場合は、設定していないフィールド (`terminationGracePeriodSeconds`、`dnsPolicy`、`/spec/replicas` など) の差分をチェックします。Kubernetes API サーバーまたは変異ウェブフックが、適用時にこれらのフィールドを追加しました。 別のコントローラーによって管理されているフィールド (HPA がスケーリングを管理する場合の `/spec/replicas` など) でこれを解決するには、`ignoreDifferences` を追加します。 ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app spec: ignoreDifferences: - group: apps kind: Deployment jsonPointers: - /spec/replicas syncPolicy: syncOptions: - RespectIgnoreDifferences=true ``` Kubernetes のデフォルトまたは変異ウェブフックによって追加されたフィールドでは、アプリケーションでサーバー側の差分を有効にできます。 ``` apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: my-app annotations: argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true ``` サーバー側の差分は、リソースごとにドライラン適用を実行するため、Kubernetes API サーバーの負荷が増加します。これを広範に有効にする前に、少数のアプリケーションでテストしてください。 ### 高チャーンのコントローラー所有リソース 一部のコントローラーは、有効期間の短い、または頻繁に更新される多数のリソースを生成します。例としては、Karpenter ノードオブジェクト、Cilium ID とエンドポイントオブジェクト、Kyverno ポリシーレポートなどがあります。これらのリソースが大量のウォッチイベントを生成し、同期チャーンを引き起こす場合、それらのリソースタイプを除外するか、ウォッチイベントをフィルタリングすることで、負荷を軽減できます。これらの変更には、インスタンスレベルのコントローラー設定が必要です。 マネージド機能で、AWS サポートケースを開いて、これらのリソースタイプのリソース除外またはウォッチイベントフィルタリングをリクエストします。 ### ベストプラクティス + **最初にアプリケーション差分を使用する**: 同期が繰り返される問題の最初の診断ステップとして `argocd app diff` を実行します。ドリフトの正確な原因が示されます。 + **ignoreDifferences を絞り込む**: 特定のリソースタイプで特定のフィールドをターゲットにします。実際の設定ドリフトをマスクできる広範な無視ルールは避けてください。 + **ignoreDifferences と RespectIgnoreDifferences を組み合わせる**: 常に `RespectIgnoreDifferences=true` 同期オプションを追加します。これがない場合、同期は無視されたフィールドを上書きします。 + **リソース名を一意に保つ**: Applications または ApplicationSets の間の所有権の衝突を避けるため、環境とクラスターごとにリソース名をスコープします。 + **prune と selfHeal に注意する**: 起動に時間がかかるワークロードでは、両方を有効にしないでください。自己修復は、リソースが正常になる前にリソースを破損する可能性があります。 + **targetRevision をピン留めしてマニフェストパスをスコープする**: 大規模な共有リポジトリ内のアプリケーションでは、`HEAD` の代わりにブランチまたはタグを使用して、`manifest-generate-paths` 注釈を追加します。 ### AWS サポートに連絡すべきケース 以下の状況では AWS サポートケースを開いてください: + インスタンスレベルのコントローラー調整が必要と思われる (プロセッサ数、自己修復タイミング、またはリソースの除外)。 + リポジトリサーバーまたはコントローラーの容量がアプリケーション数には不十分であると思われる。 + ワークロード設定、ドリフト、所有権、またはファイナライザーでは動作を説明できない。 サポートケースには、影響を受けるアプリケーションの `argocd app get` および `argocd app diff` の出力を含めてください。 ## 次のステップ + [Argo CD に関する考慮事項](argocd-considerations.md) - Argo CD の考慮事項とベストプラクティス + [Argo CD の使用](working-with-argocd.md) - Argo CD Application を作成して管理する + [ターゲットクラスターを登録する](argocd-register-clusters.md) - マルチクラスターデプロイを設定する + [EKS 機能をトラブルシューティングする](capabilities-troubleshooting.md) - 一般的な機能をトラブルシューティングする際のガイダンス