**帮助改进此页面** 

要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。

# 排查 Argo CD 功能的问题
<a name="argocd-troubleshooting"></a>

本主题提供了适用于 Argo CD 的 EKS 功能的问题排查指南，包括功能运行状况检查、应用程序同步问题、存储库身份验证和多集群部署。

**注意**  
EKS 功能完全托管，可在您的集群之外运行。您无权访问 Argo CD 服务器日志或 `argocd` 命名空间。问题排查侧重于功能运行状况、应用程序状态和配置。

## 功能已激活，但应用程序未同步
<a name="_capability_is_active_but_applications_arent_syncing"></a>

如果 Argo CD 功能显示 `ACTIVE` 状态但应用程序未同步，请检查功能运行状况和应用程序状态。

 **检查功能运行状况**：

您可以在 EKS 控制台或使用 Amazon CLI 查看功能运行状况和状态问题。

 **控制台**：

1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。

1. 选择集群名称。

1. 选择**可观测性**选项卡。

1. 选择**监控集群**。

1. 选择**功能**选项卡，查看所有功能的运行状况和状态。

 **Amazon 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 资源
+  **同步策略**：需要手动同步（未启用自动同步）
+  **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”状态
<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::[.replaceable]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)：一般功能问题排查指导