協助改進此頁面

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的在 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 欄位包含 EKS 叢集 ARN，而不是 Kubernetes API URL。

驗證目標叢集存取項目：

在目標叢集上，檢查 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 功能角色在目標叢集上有存取項目。受管功能使用 EKS 存取項目進行跨帳戶存取，而非 IAM 角色假設。

如需多叢集組態的詳細資訊，請參閱註冊目標叢集。

增加應用程式同步時間

如果您的應用程式正在同步，但花費的時間超過預期，請使用下列診斷步驟來識別原因。

檢查上次同步時間

透過檢閱應用程式上次同步的時間來確認延遲：

# 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 或資源擁有權衝突

如果兩個應用程式或 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
         

Monorepo 遞交流失觸發條件廣泛的再生

如果許多應用程式在相同的儲存庫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 只會在指定路徑下的檔案變更時重新產生資訊清單。對於跨應用程式使用的共用程式庫，您可以指定多個以分號 () 分隔的路徑;。

盡可能將 釘選targetRevision到分支名稱或標籤，而不是 HEAD。

Kubernetes 預設和變動 Webhook 會導致假體差異

如果您的應用程式在同步OutOfSync後立即顯示，請檢查從未設定的欄位差異 （例如 terminationGracePeriodSeconds、 dnsPolicy或 /spec/replicas)。Kubernetes API 伺服器或變動 Webhook 會在套用時新增這些欄位。

若要解決由其他控制器管理的欄位 （例如 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 預設或變動 Webhook 新增的欄位，您可以在應用程式上啟用伺服器端差異：

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  annotations:
    argocd.argoproj.io/compare-options: ServerSideDiff=true,IncludeMutationWebhook=true

伺服器端 diff 會針對每個資源執行試轉套用，這會增加 Kubernetes API 伺服器的負載。在廣泛啟用之前，先在少量應用程式上進行測試。

高流失控制器擁有的資源

有些控制器會產生大量短期或經常更新的資源。範例包括 Karpenter 節點物件、Cilium 身分和端點物件，以及 Kyverno 政策報告。如果這些資源產生大量監看事件並導致同步流失，您可以透過排除這些資源類型或篩選監看事件來減少負載。這些變更需要執行個體層級控制器組態。

在 受管功能上，開啟 AWS 支援案例，請求這些資源類型的資源排除或監看事件篩選。

最佳實務

聯絡 AWS Support 的時機

在下列情況下開啟 AWS 支援案例：

在支援案例中包含受影響應用程式的 argocd app get和 argocd app diff 輸出。

後續步驟