**協助改進此頁面** 

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

若要為本使用者指南貢獻內容，請點選每個頁面右側面板中的**在 GitHub 上編輯此頁面**連結。

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

# 對 Argo CD 功能的問題進行故障診斷
<a name="argocd-troubleshooting"></a>

**注意**  
EKS 功能是完全受管的，並在叢集外部執行。您無法直接存取控制器命名空間。您可以設定控制器日誌交付，以掌握控制器行為。請參閱 [存取 EKS 功能控制器日誌](capabilities-controller-logs.md)。故障診斷著重於功能運作狀態、應用程式狀態和組態。

## 功能為 ACTIVE，但應用程式未同步
<a name="_capability_is_active_but_applications_are_not_syncing"></a>

如果您的 Argo CD 功能顯示`ACTIVE`狀態，但應用程式未同步，請檢查功能運作狀態和應用程式狀態。

 **檢查功能運作狀態**：

您可以在 EKS 主控台或使用 AWS CLI 檢視功能運作狀態和狀態問題。

 **主控台**：

1. 在以下網址開啟 Amazon EKS 主控台：https://console.aws.amazon.com/eks/home\#/clusters。

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 登入資料無效
+  **未建立應用程式**：叢集中不存在應用程式資源
+  **同步政策**：需要手動同步 （未啟用自動同步）
+  **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}'
```

## 應用程式停滯在「進行中」狀態
<a name="_applications_stuck_in_progressing_state"></a>

如果應用程式顯示 `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"
```

 **常見原因**：
+  **部署未就緒**：Pod 無法啟動或整備探查失敗
+  **資源相依性**：等待其他資源準備就緒的資源
+  **映像提取錯誤**：無法存取容器映像
+  **資源不足**：叢集缺乏 Pod 的 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
```

## 儲存庫身分驗證失敗
<a name="_repository_authentication_failures"></a>

如果 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}}
```

## 多叢集部署問題
<a name="_multi_cluster_deployment_issues"></a>

如果應用程式未部署到遠端叢集，請驗證叢集註冊和存取組態。

 **檢查叢集註冊**：

```
# 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 角色假設。

如需多叢集組態的詳細資訊，請參閱[註冊目標叢集](argocd-register-clusters.md)。

## 增加應用程式同步時間
<a name="_increased_application_sync_time"></a>

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

### 檢查上次同步時間
<a name="_check_last_sync_time"></a>

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

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

### 檢查應用程式條件
<a name="_check_application_conditions"></a>

檢閱應用程式條件是否有調校佇列延遲：

```
# Check conditions on an application
kubectl get application {{my-app}} -n argocd -o jsonpath='{.status.conditions}'
```

### 檢查 targetRevision 組態
<a name="_check_targetrevision_configuration"></a>

使用 的應用程式會在每次遞交至儲存庫時使資訊清單快取`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}'
```

### 常見原因
<a name="_common_causes"></a>
+  **無 Webhook 組態**：如果沒有 Webhook，Argo CD 會以預設間隔 6 分鐘輪詢儲存庫。這會延遲新遞交的偵測。
+  **targetRevision 設定為 HEAD**：對儲存庫的每筆遞交都會使資訊清單快取失效。Argo CD 接著會在每次對帳時重新產生資訊清單。
+  **大型或複雜的 Git 儲存庫**：由於要處理的檔案和範本數量， Monorepos 或複雜的 Helm Chart 會導致資訊清單產生緩慢。
+  **單一應用程式中大量的 Kubernetes 資源**：管理許多資源的應用程式會導致叢集快取同步緩慢，因為 Argo CD 必須追蹤每個資源的狀態。

### 緩解措施
<a name="_mitigations"></a>
+  **設定 Git Webhook**：Webhooks 會在推送變更時立即通知 Argo CD，繞過預設輪詢間隔。如需組態步驟，請參閱 [Argo CD 考量事項](argocd-considerations.md)。
+  **使用特定分支名稱或遞交 SHAs**：`targetRevision`設定為分支名稱或遞交 SHA，而不是`HEAD`在同步之間保留資訊清單快取。
+  **分割大型單一儲存庫**：將大型儲存庫分割成較小的聚焦儲存庫，以減少資訊清單產生時間。
+  **減少每個應用程式的資源**：將具有許多 Kubernetes 資源的應用程式分割成多個較小的應用程式，以減少叢集快取同步時間。
+  **啟用控制器日誌交付**：控制器日誌提供對調校行為和佇列處理的可見性。如需組態步驟，請參閱 [存取 EKS 功能控制器日誌](capabilities-controller-logs.md)。

## 應用程式重複同步或無法同步
<a name="_applications_repeatedly_syncing_or_stuck_out_of_sync"></a>

如果您的應用程式同步，然後立即變成 `OutOfSync`，或者它卡在同步迴圈中，原因通常會在 Git 定義和叢集中存在的內容之間偏離。從基準診斷開始。

### 收集診斷資訊
<a name="_gather_diagnostic_information"></a>

```
# 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` 命令是最有用的起點。它確切顯示應用程式出現不同步的欄位。

### 自我管理憑證造成偏離
<a name="_self_managed_certificates_cause_drift"></a>

cert-manager、OPA Gatekeeper 和 KEDA 等控制器會在執行時間產生憑證。這些執行時間值不在 Git 中，因此 Argo CD 會在每次對帳時偵測偏離。

這些症狀包括：
+ 應用程式同步，然後立即顯示 `OutOfSync` 
+ 差異顯示 Webhook `caBundle` 欄位或 TLS Secret `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
```

### 自我修復會中斷啟動緩慢的工作負載
<a name="_self_heal_interrupts_slow_starting_workloads"></a>

啟用 `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 或資源擁有權衝突
<a name="_applicationset_or_resource_ownership_collisions"></a>

如果兩個應用程式或 ApplicationSets 管理相同的 Kubernetes 資源，Argo CD 會顯示 `SharedResourceWarning`。資源永遠不會達到穩定狀態。當共用資源名稱未依環境或叢集設定範圍時，通常會發生這種情況。

若要解決此問題：
+ 讓每個擁有者的預期資源是唯一的。將環境或叢集尾碼新增至資源名稱。
+ 重新命名 ApplicationSet 時，`preserveResourcesOnDeletion: true`請先設定 以避免現有資源的破壞性縮減：

```
apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: my-appset
spec:
  syncPolicy:
    preserveResourcesOnDeletion: true
```

### 從資源定稿器卡住刪除
<a name="_stuck_deletion_from_resource_finalizers"></a>

如果應用程式停滯在 `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"}]'
```

### 失敗的同步不會自動重試相同的修訂
<a name="_failed_sync_does_not_auto_retry_to_the_same_revision"></a>

同步至特定修訂失敗後，Argo CD 不會自動重試相同的修訂。這通常是因為資訊清單瑕疵，例如`ComparisonError`來自重複環境變數索引鍵的 。

檢查應用程式狀態以確認：

```
argocd app get {{my-app}}
# Look for: Operation: Sync  Phase: Failed  Revision: <sha>
```

若要解決此問題，請修正 Git 儲存庫中的資訊清單瑕疵，並推送新的遞交。或者，觸發手動同步：

```
argocd app sync {{my-app}}
```

### Monorepo 遞交流失觸發條件廣泛的再生
<a name="_monorepo_commit_churn_triggers_broad_regeneration"></a>

如果許多應用程式在相同的儲存庫`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 會導致假體差異
<a name="_kubernetes_defaulting_and_mutating_webhooks_cause_phantom_diffs"></a>

如果您的應用程式在同步`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 伺服器的負載。在廣泛啟用之前，先在少量應用程式上進行測試。

### 高流失控制器擁有的資源
<a name="_high_churn_controller_owned_resources"></a>

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

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

### 最佳實務
<a name="_best_practices"></a>
+  **先使用應用程式差異**：執行 `argocd app diff`做為任何重複同步問題的第一個診斷步驟。它會顯示偏離的確切原因。
+  **偏好窄型 ignoreDifferences**：以特定資源類型的特定欄位為目標。避免可遮罩實際組態偏離的廣泛忽略規則。
+  **配對 ignoreDifferences with RespectIgnoreDifferences**：一律新增`RespectIgnoreDifferences=true`同步選項。如果沒有它，同步仍會覆寫忽略的欄位。
+  **保持資源名稱是唯一**的：範圍每個環境和叢集的資源名稱，以避免應用程式或 ApplicationSets 之間的所有權衝突。
+  **請謹慎使用 prune 和 selfHeal**：請勿在需要很長時間才能啟動的工作負載上啟用兩者。自我修復可以在資源正常運作之前將其銷毀。
+  **Pin targetRevision 和範圍資訊清單路徑**：對於大型共用儲存庫中的應用程式，請使用分支或標籤，而不是 `HEAD`並新增`manifest-generate-paths`註釋。

### 聯絡 AWS Support 的時機
<a name="when_to_contact_shared_aws_support"></a>

在下列情況下開啟 AWS 支援案例：
+ 執行個體層級控制器調校似乎是必要的 （處理器計數、自我修復時間或資源排除）。
+ 儲存庫伺服器或控制器容量似乎不足以滿足您的應用程式計數。
+ 工作負載組態、偏離、擁有權或定案者不會解釋行為。

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

## 後續步驟
<a name="_next_steps"></a>
+  [Argo CD 考量事項](argocd-considerations.md) - Argo CD 考量事項和最佳實務
+  [使用 Argo CD](working-with-argocd.md) - 建立和管理 Argo CD 應用程式
+  [註冊目標叢集](argocd-register-clusters.md) - 設定多叢集部署
+  [對 EKS 功能進行故障診斷](capabilities-troubleshooting.md) - 一般功能故障診斷指引