**協助改進此頁面** 

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

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

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

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

**注意**  
EKS 功能是完全受管的，並在叢集外部執行。您無法存取控制器日誌或控制器命名空間。故障診斷著重於功能運作狀態、應用程式狀態和組態。

## 功能為 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="_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) - 一般功能故障診斷指引