このページの改善にご協力ください

このユーザーガイドに貢献するには、すべてのページの右側のペインにある「GitHub でこのページを編集する」リンクを選択してください。

Argo CD 機能に関する問題をトラブルシューティングする

機能が ACTIVE であるのにアプリケーションが同期しない

Argo CD 機能のステータスが ACTIVE であるのにアプリケーションが同期しない場合は、機能のヘルスとアプリケーションのステータスを確認してください。

機能のヘルスを確認する:

機能のヘルスとステータスの問題は、EKS コンソールまたは AWS CLI を使用して表示できます。

コンソール:

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

一般的な原因:

アプリケーションのステータスを確認する:

# 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"

一般的な原因:

ターゲットクラスターの設定を検証する (マルチクラスター設定の場合):

# 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 アクセスエントリを使用します。

マルチクラスター設定の詳細については、「ターゲットクラスターを登録する」を参照してください。

アプリケーションの同期時間の増加

アプリケーションが同期しているが、予想以上に時間がかかる場合は、次の診断ステップを使用して原因を特定します。

最後の同期時間を確認する

アプリケーションが最後に同期されたタイミングをレビューして、遅延を確認します:

# 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}'

一般的な原因

緩和策

アプリケーションが繰り返し同期するか、同期がスタックする

アプリケーションが同期されてすぐに 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 はすべての調整でドリフトを検出します。

症状は次のとおりです:

これを解決するには、影響を受けるフィールドで 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

ApplicationSet またはリソース所有権が衝突する

2 つの Applications または ApplicationSets が同じ Kubernetes リソースを管理している場合、Argo CD には SharedResourceWarning が表示されます。リソースが安定状態に到達することはありません。これは通常、共有リソース名が環境またはクラスターごとにスコープされていない場合に発生します。

これを解決するには:

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: <sha>

これを解決するには、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 サポートケースを開いて、これらのリソースタイプのリソース除外またはウォッチイベントフィルタリングをリクエストします。

ベストプラクティス

AWS サポートに連絡すべきケース

以下の状況では AWS サポートケースを開いてください:

サポートケースには、影響を受けるアプリケーションの argocd app get および argocd app diff の出力を含めてください。

次のステップ