**帮助改进此页面** 

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

# Argo CD 注意事项
<a name="argocd-considerations"></a>

本主题将介绍使用适用于 Argo CD 的 EKS 功能的重要注意事项，包括规划、权限、身份验证和多集群部署模式。

## 规划
<a name="_planning"></a>

在部署 Argo CD 之前，请考虑以下事项：

 **存储库策略**：确定应用程序清单的存储位置（CodeCommit、GitHub、GitLab、Bitbucket）。为不同的环境规划存储库结构和分支策略。

 **RBAC 策略**：规划哪些团队或用户应具有管理员、编辑者或查看者访问权限。将其映射到 Amazon Identity Center 组或 Argo CD 角色。

 **多集群架构**：确定是否要通过单个 Argo CD 实例管理多个集群。考虑为 Argo CD 使用专用的管理集群。

 **应用程序组织**：规划如何构建 Applications 和 ApplicationSets。考虑使用项目按团队或环境组织应用程序。

 **同步策略**：决定应用程序应自动同步还是需要手动批准。开发环境通常采用自动同步，生产环境则采用手动同步。

## 权限
<a name="_permissions"></a>

有关 IAM 功能角色、信任策略和安全最佳实践的详细信息，请参阅 [Amazon EKS 功能 IAM 角色](capability-role.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。

### IAM 功能角色概述
<a name="_iam_capability_role_overview"></a>

创建 Argo CD 功能资源时，您需要提供 IAM 功能角色。与 ACK 不同，Argo CD 主要管理 Kubernetes 资源，而不是直接管理 Amazon 资源。但是，IAM 功能角色在以下场景是必需的：
+ 访问 CodeCommit 中的私有 Git 存储库
+ 与 Amazon Identity Center 集成以进行身份验证
+ 访问 Amazon Secrets Manager 中的密钥（如果已配置）
+ 跨集群部署到其他 EKS 集群

### CodeCommit 集成
<a name="_codecommit_integration"></a>

如果使用的是 CodeCommit 存储库，请附加具有读取权限的策略：

```
{
  "Version": "2012-10-17",		 	 	 
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "codecommit:GitPull"
      ],
      "Resource": "*"
    }
  ]
}
```

**重要**  
对于生产用途，请将 `Resource` 字段限制为特定的存储库 ARN，而不是使用 `"*"`。  
示例：  

```
"Resource": "arn:aws:codecommit:us-west-2:111122223333:my-app-repo"
```
这限制了 Argo CD 功能对存储库的访问权限，仅允许其访问需要管理的存储库。

### Secrets Manager 集成
<a name="_secrets_manager_integration"></a>

如果要将存储库凭证存储在 Secrets Manager 中，请附加托管策略以获得读取访问权限：

```
arn:aws:iam::aws:policy/AWSSecretsManagerClientReadOnlyAccess
```

此策略包括必要的权限：`secretsmanager:GetSecretValue`、`secretsmanager:DescribeSecret` 和 KMS 解密权限。

### 基本设置
<a name="_basic_setup"></a>

对于使用公有 Git 存储库的基本 Argo CD 功能，除了信任策略外，不需要其他的 IAM 策略。

## 身份验证
<a name="_authentication"></a>

### Amazon Identity Center 集成
<a name="shared_aws_identity_center_integration"></a>

Argo CD 托管功能直接与 Amazon Identity Center（原 Amazon SSO）集成，您能够使用现有的身份提供者进行身份验证。

配置 Amazon Identity Center 集成时：

1. 用户通过 EKS 控制台访问 Argo CD 用户界面

1. 他们使用 Amazon Identity Center（可以与企业身份提供者联合）进行身份验证

1.  Amazon Identity Center 向 Argo CD 提供用户和组信息

1. Argo CD 会根据配置将用户和组映射到 RBAC 角色

1. 用户只能看到他们有权访问的应用程序和资源

### 使用 IAM Center 权限集简化访问管理
<a name="_simplifying_access_with_identity_center_permission_sets"></a>

 使用 Argo CD 时，Amazon Identity Center 提供两种不同的身份验证路径：

 **Argo CD API 身份验证**：Identity Center 向 Argo CD 用户界面和 API 提供 SSO 身份验证。这通过 Argo CD 功能的 RBAC 角色映射进行配置。

 **EKS 集群访问权限**：Argo CD 功能使用客户提供的 IAM 角色，通过访问条目向 EKS 集群进行身份验证。可以手动配置这些访问条目以添加或移除权限。

您可以使用 [Identity Center 权限集](https://docs.amazonaws.cn/singlesignon/latest/userguide/howtocreatepermissionset.html)来简化身份管理，允许单个身份同时访问 Argo CD 和 EKS 集群。这样一来，您只需在两个系统中管理一个身份，而无需为 Argo CD 访问和集群访问保留单独的凭证，从而减少了开销。

### RBAC 角色映射
<a name="_rbac_role_mappings"></a>

Argo CD 具有内置角色，您可以将其映射到 Amazon Identity Center 用户和组：

 **ADMIN**：可以完全访问所有应用程序和设置。可以创建、更新和删除应用程序。可以管理 Argo CD 配置。

 **EDITOR**：可以创建和修改应用程序。无法更改 Argo CD 设置或删除应用程序。

 **VIEWER**：可以对应用程序进行只读访问。可以查看应用程序状态和历史记录。无法进行更改。

**注意**  
角色名称区分大小写，必须为大写（ADMIN、EDITOR、VIEWER）。

**重要**  
EKS 功能与 Amazon Identity Center 集成后，每个 Argo CD 功能可支持最多 1000 个身份。身份可以是用户或组。

## 多集群部署
<a name="_multi_cluster_deployments"></a>

Argo CD 托管功能支持多集群部署，便于您通过单个 Argo CD 实例在开发、暂存和生产集群之间管理应用程序。

### 多集群工作原理
<a name="_how_multi_cluster_works"></a>

当您向 Argo CD 注册其他集群时：

1. 您需要创建集群密钥，并通过 ARN 来引用目标 EKS 集群

1. 您需要创建针对不同集群的 Applications 或 ApplicationSets

1. Argo CD 会连接到每个集群以部署和监视资源

1. 您可以通过单个 Argo CD 用户界面查看和管理所有集群

### 多集群的先决条件
<a name="_prerequisites_for_multi_cluster"></a>

在注册其他集群之前：
+ 在目标集群上，为 Argo CD 功能角色创建访问条目
+ 确保 Argo CD 功能与目标集群之间建立网络连接
+ 验证访问目标集群所需的 IAM 权限

### 注册集群
<a name="_register_a_cluster"></a>

使用 `argocd` 命名空间中的 Kubernetes Secret 注册集群。

获取目标集群 ARN。将 *region-code* 替换为目标集群所在的 Amazon 区域，并将 *target-cluster* 替换为目标集群的名称。

```
aws eks describe-cluster \
  --region region-code \
  --name target-cluster \
  --query 'cluster.arn' \
  --output text
```

使用集群 ARN 创建集群密钥：

```
apiVersion: v1
kind: Secret
metadata:
  name: target-cluster
  namespace: argocd
  labels:
    argocd.argoproj.io/secret-type: cluster
type: Opaque
stringData:
  name: target-cluster
  server: arn:aws:eks:us-west-2:111122223333:cluster/target-cluster
  project: default
```

**重要**  
在 `server` 字段中使用 EKS 集群 ARN，而不是 Kubernetes API 服务器 URL。托管功能需要使用 ARN 来识别目标集群。

应用该密钥：

```
kubectl apply -f cluster-secret.yaml
```

### 在目标集群上配置访问条目
<a name="_configure_access_entry_on_target_cluster"></a>

目标集群必须具有访问条目，以授予 Argo CD 功能角色部署应用程序的权限。将 *region-code* 替换为目标集群所在的 Amazon 区域，将 *target-cluster* 替换为目标集群的名称，然后将 ARN 替换为 Argo CD 功能角色 ARN。

```
aws eks create-access-entry \
  --region region-code \
  --cluster-name target-cluster \
  --principal-arn arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole \
  --type STANDARD \
  --kubernetes-groups system:masters
```

**注意**  
对于生产用途，可以考虑使用限制性更强的 Kubernetes 组，而不使用 `system:masters`。

### 私有集群访问
<a name="_private_cluster_access"></a>

Argo CD 托管功能可以部署到完全私有的 EKS 集群，无需进行 VPC 对等连接或专门的网络配置。Amazon 会自动管理 Argo CD 功能与私有远程集群之间的连接。确保您的存储库访问控制和 Argo CD RBAC 策略已正确配置。

### 跨账户部署
<a name="_cross_account_deployments"></a>

对于跨账户部署，请将源账户中的 Argo CD IAM 功能角色添加到目标集群的 EKS 访问条目中：

1. 在目标账户中的目标 EKS 集群上创建访问条目

1. 将源账户中的 Argo CD IAM 功能角色 ARN 用作主体

1. 为访问条目配置相应的 Kubernetes RBAC 权限

1. 使用其 EKS 集群 ARN 在 Argo CD 中注册目标集群

无需创建额外的 IAM 角色或配置信任策略，EKS 访问条目会处理跨账户访问。

## 最佳实践
<a name="_best_practices"></a>

 **使用声明式源作为事实来源**：将所有应用程序清单存储在声明式源（Git 存储库、Helm 注册表或 OCI 映像）中，从而实现版本控制、审计跟踪记录和协作。

 **实施适当的 RBAC**：使用 Amazon Identity Center 集成来控制哪些人可以访问和管理 Argo CD 中的应用程序。Argo CD 支持对应用程序内的资源（Deployment、Pod、ConfigMap、Secret）进行精细访问控制。

 **使用 ApplicationSets 进行多环境部署**：使用 ApplicationSets 在不同集群或命名空间中以不同配置部署应用程序。

## 生命周期管理
<a name="_lifecycle_management"></a>

### 应用程序同步策略
<a name="_application_sync_policies"></a>

控制 Argo CD 如何同步应用程序：

 **手动同步**：应用程序需要手动批准才能同步更改。建议将其用于**生产**环境。

 **自动同步**：检测到 Git 更改时，应用程序会自动同步。通常用于开发和暂存环境。

 **自我修复**：自动还原对集群所作的手动更改。确保集群状态与 Git 一致。

 **修剪**：自动删除从 Git 中移除的资源。请谨慎使用，因为此操作可能会删除资源。

### 应用程序运行状况
<a name="_application_health"></a>

Argo CD 会持续监控应用程序运行状况：
+  **良好**：所有资源均按预期运行
+  **正在处理**：正在创建或更新资源
+  **已降级**：部分资源运行状况不佳
+  **已暂停**：应用程序暂停
+  **缺失**：集群中缺少资源

### 同步时段
<a name="_sync_windows"></a>

配置同步时段以控制何时可以同步应用程序：
+ 仅允许在维护时段进行同步
+ 在工作时间阻止同步
+ 为特定时间安排自动同步
+ 在需要进行更改且需要停止所有同步操作（紧急情景）的情况下，请使用同步窗口

## 配置 Webhook 以实现更快同步
<a name="_webhook_configuration_for_faster_sync"></a>

默认情况下，Argo CD 每 6 分钟轮询一次 Git 存储库以检测更改。要实现响应速度更快的部署，请配置 Git Webhook 以在推送更改时立即触发同步。

Webhook 具有以下优势：
+ 推送代码时立即同步响应（秒级而非分钟级）
+ 减少轮询开销并提高系统性能
+ 更有效地使用 API 速率限制
+ 用户体验更好，反馈更快

### Webhook 端点
<a name="_webhook_endpoint"></a>

webhook URL 遵循模式 `${serverUrl}/api/webhook`，其中 `serverUrl` 是您的 Argo CD 服务器 URL。

例如，如果您的 Argo CD 服务器 URL 是 `https://abc123.eks-capabilities.us-west-2.amazonaws.com`，则 webhook URL 是：

```
https://abc123.eks-capabilities.us-west-2.amazonaws.com/api/webhook
```

### 按 Git 提供者配置 Webhook
<a name="_configure_webhooks_by_git_provider"></a>

 **GitHub**：在存储库设置中，添加指向 Argo CD Webhook URL 的 Webhook。将内容类型设置为 `application/json`，然后选择“仅推送事件”。

 **GitLab**：在项目设置中，添加指向 Argo CD Webhook URL 的 Webhook。启用“推送事件”和“标签推送事件”（可选）。

 **Bitbucket**：在存储库设置中，添加指向 Argo CD Webhook URL 的 Webhook。选择“存储库推送”作为触发器。

 **CodeCommit**：创建 Amazon EventBridge 规则，该规则会在 CodeCommit 存储库状态更改时触发，并将通知发送到 Argo CD Webhook 端点。

有关详细的 Webhook 配置说明，请参阅 [Argo CD Webhook Configuration](https://argo-cd.readthedocs.io/en/stable/operator-manual/webhook/)。

**注意**  
Webhooks 是对轮询的补充，并不能取而代之。Argo CD 会继续轮询存储库，作为错过 Webhook 通知时的回退机制。

## 后续步骤
<a name="_next_steps"></a>
+  [使用 Argo CD](working-with-argocd.md)：了解如何创建和管理 Argo CD 应用程序
+  [排查 Argo CD 功能的问题](argocd-troubleshooting.md)：排查 Argo CD 问题
+  [使用功能资源](working-with-capabilities.md)：管理 Argo CD 功能资源