**帮助改进此页面**
要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。
# EKS 功能
**提示**
入门：[创建 ACK 功能](create-ack-capability.md) \$1 [创建 Argo CD 功能](create-argocd-capability.md) \$1 [创建 kro 功能](create-kro-capability.md)
Amazon EKS 功能是一组分层的完全托管式集群功能，可帮助加快开发人员的速度并减轻使用 Kubernetes 构建和扩展的复杂性。EKS 功能是 Kubernetes 原生功能，用于声明式持续部署、AWS 资源管理以及 Kubernetes 资源编写和编排，所有这些功能都由 AWS 完全托管。借助 EKS 功能，您可以更加专注于构建和扩展工作负载，从而将这些基础平台服务的运营负担转移至 AWS。这些功能在 EKS 中运行，而不是在您的集群中运行，因此无需在 Worker 节点上安装、维护和扩展关键平台组件。
首先，您可以在新的或现有的 EKS 集群上创建一个或多个 EKS 功能。为此，您可以使用 AWS CLI、AWS 管理控制台、EKS API、eksctl 或您偏好的基础设施即代码工具。虽然 EKS 功能旨在协同工作，但它们是独立的云资源，您可以根据自己的使用案例和要求进行选择。
EKS 支持的所有 Kubernetes 版本都支持 EKS 功能。
**注意**
所有提供 Amazon EKS 的 AWS 商业区域均提供 EKS 功能。有关支持的区域列表，请参阅《AWS 一般参考》中的 [Amazon EKS 端点和配额](https://docs.aws.amazon.com/general/latest/gr/eks.html)。
## 可用的功能
### AWS Controllers for Kubernetes（ACK）
ACK 支持使用 Kubernetes API 管理 AWS 资源，允许您使用 Kubernetes 自定义资源创建和管理 S3 存储桶、RDS 数据库、IAM 角色和其他 AWS 资源。ACK 会持续调整您的所需状态与 AWS 中的实际状态，纠正随时间推移而出现的任何漂移，以保持系统运行状况良好并按照指定配置资源。您能够使用统一的工具与工作流程，将 AWS 资源和 Kubernetes 工作负载纳入同一管理体系，该工具支持包括 S3、RDS、DynamoDB 及 Lambda 在内的 50 余项 AWS 服务。ACK 支持跨账户和跨区域资源管理，支持复杂的多账户、多集群系统管理架构。ACK 支持只读资源和只读采用，便于从其他基础设施即代码工具迁移到基于 Kubernetes 的系统。
[了解有关 ACK 的更多信息 →](ack.md)
### Argo CD
Argo CD 将 Git 存储库作为工作负载和系统状态的事实来源，为您的应用程序实施基于 GitOps 的持续部署。Argo CD 会自动将应用程序资源从 Git 存储库同步到您的集群，从而检测和修复漂移，确保您部署的应用程序与预期状态保持一致。您可以通过单个 Argo CD 实例跨多个集群部署和管理应用程序，当 Git 存储库中提交变更时，该工具会自动触发部署流程。同时使用 Argo CD 和 ACK 可以提供基础的 GitOps 系统，简化工作负载依赖关系管理，并支持包括大规模管理集群和基础设施在内的整个系统设计。Argo CD 与 AWS Identity Center 集成，可进行身份验证和授权，并提供托管 Argo 用户界面，用于可视化应用程序运行状况和部署状态。
[了解有关 Argo CD 的更多信息 →](argocd.md)
### kro（Kube Resource Orchestrator）
kro 支持您创建自定义 Kubernetes API，可将多种资源组合为更上层的抽象资源，方便平台团队针对常见的资源组合云基础设施组件，定义可复用的模式。使用 kro，您可以将 Kubernetes 和 AWS 资源组合成统一的抽象资源，使用简单的语法实现动态配置和条件逻辑。kro 使平台团队能够提供带有适当护栏的自助服务功能，允许开发人员在维护组织标准和最佳实践的同时，使用简单、专门构建的 API 预置复杂的基础设施。kro 资源只是 Kubernetes 资源，在可以存储在 Git 中的 Kubernetes 清单中指定，或者推送到 Amazon ECR 等兼容 OCI 的注册表，用于在组织范围广泛分布。
[了解有关 kro 的更多信息 →](kro.md)
## EKS 功能的优势
EKS 功能完全由 AWS 管理，无需安装、维护和扩展基础集群服务。AWS 可处理安全修补、更新和运营管理，让您的团队腾出时间专注于使用 AWS 进行构建，而无需顾虑集群操作。与消耗集群资源的传统 Kubernetes 附加组件不同，这些功能在 EKS 中运行，而不是在 Worker 节点上运行。这可以为工作负载释放集群容量和资源，同时最大限度地减少管理集群内控制器和其他平台组件的运营负担。
借助 EKS 功能，您可以使用原生 Kubernetes API 和诸如 `kubectl` 等工具管理部署、AWS 资源、自定义 Kubernetes 资源和组合。所有功能都在集群环境中运行，可自动检测和纠正应用程序和云基础设施资源中的配置漂移。您可以从一个控制点跨多个集群、AWS 账户和区域部署和管理资源，从而简化复杂的分布式环境中的操作。
EKS 功能专为 GitOps 工作流程而设计，提供声明式、版本控制的基础设施和应用程序管理。这些变更通过 Git 在系统中传递，从而提供审计跟踪记录、回滚功能以及与您现有开发流程相整合的协作工作流程。这种 Kubernetes 原生方法意味着您无需使用多种工具或管理集群外部的基础设施即代码系统，并且只有一个事实来源供参考。在版本控制的 Kubernetes 声明式配置中定义的预期状态将在环境中持续强制执行。
## 定价
使用 EKS 功能无需预付费用承诺，也没有最低费用。您需要为每项功能资源在 Amazon EKS 集群上处于活动状态的每小时支付费用。由 EKS 功能管理的特定 Kubernetes 资源也按小时费率计费。
有关当前定价信息，请参阅 [Amazon EKS 定价页面](https://aws.amazon.com/eks/pricing/)。
**提示**
您可以使用 AWS Cost Explorer 成本管理服务以及成本和使用情况报告，分别追踪容量成本与其他 EKS 费用。您可以使用集群名称、功能类型和其他详细信息来标记您的功能，用于成本分配。
## EKS 功能的工作原理
每项功能都是您在 EKS 集群上创建的 AWS 资源。创建后，该功能将在 EKS 中运行并完全由 AWS 管理。
**注意**
您可以针对给定集群创建每种类型（Argo CD、ACK 和 kro）的功能资源。您不能在同一个集群上创建相同类型的多个功能资源。
您可以使用标准 Kubernetes API 和工具与集群中的功能进行交互：
+ 使用 `kubectl` 应用 Kubernetes 自定义资源
+ 使用 Git 存储库作为 GitOps 工作流程的事实来源
某些功能还支持其他工具。例如：
+ 使用 Argo CD CLI 在 Argo CD 功能中配置和管理存储库和集群
+ 使用 Argo CD 用户界面，对由 Argo CD 功能管理的应用程序进行可视化和管理
各功能旨在协同工作，但它们是独立的，且完全可由您自行选择加入。您可以根据需要启用一项、两项或全部三项功能，并随着需求的变化更新配置。
所有 EKS 计算类型均支持与 EKS 功能配合使用。有关更多信息，请参阅 [使用节点来管理计算资源](eks-compute.md)。
有关安全配置和 IAM 角色的详细信息，请参阅 [EKS 功能的安全注意事项](capabilities-security.md)。有关多集群架构模式的信息，请参阅 [EKS 功能和注意事项](capabilities-considerations.md)。
## 常见使用案例
**适用于应用程序和基础设施的 GitOps**
使用 Argo CD 部署应用程序和操作组件，使用 ACK 管理集群配置和预置基础设施，两者均从 Git 存储库中获得。整个堆栈（应用程序、数据库、存储和网络）都会被定义为代码并自动部署。
示例：开发团队将更改推送到 Git。Argo CD 会部署更新的应用程序，ACK 会使用正确的配置预置新的 RDS 数据库。所有更改均可审计、可逆且可在不同环境中保持一致。
**具有自助服务能力的平台工程**
使用 kro 创建用于构建 ACK 和 Kubernetes 资源的自定义 API。平台团队使用护栏定义经批准的模式。应用程序团队使用简单的高级别 API 预置完整的堆栈。
示例：平台团队创建了“WebApplication”API，用于配置部署、服务、入口和 S3 存储桶。开发人员无需了解底层复杂性或 AWS 权限即可使用此 API。
**多集群应用程序管理**
使用 Argo CD，在不同地区或账户的多个 EKS 集群中部署应用程序。使用一致的策略和工作流程，使用单个 Argo CD 实例管理所有部署。
示例：将同一个应用程序部署到多个区域中的开发、暂存和生产集群。Argo CD 可确保每个环境与其相应的 Git 分支保持同步。
**多集群管理**
使用 ACK 定义和预置 EKS 集群，使用 kro 根据组织标准自定义集群配置，使用 Argo CD 管理集群生命周期和配置。这能实现从创建到持续运营的端到端集群管理。
示例：使用 ACK 和 kro 定义 EKS 集群，以预置和管理集群基础设施，同时定义网络、安全策略、附加组件和其他配置的组织标准。使用 Argo CD，利用一致标准和自动化生命周期管理，跨实例集创建并持续管理集群、配置和 Kubernetes 版本更新。
**迁移与现代化**
借助原生云资源预置和 GitOps 工作流程，简化向 EKS 的迁移。在不重新创建现有 AWS 资源的情况下通过 ACK 采用这些资源，并使用 Argo CD 从 Git 实施工作负载部署。
示例：从 EC2 迁移到 EKS 的团队使用 ACK 采用其现有的 RDS 数据库和 S3 存储桶，然后使用 Argo CD 从 Git 部署容器化应用程序。迁移路径很明确，操作从第一天起就实现标准化。
**账户和区域引导**
同时使用 Argo CD 和 ACK，实现跨账户和地区自动化基础设施部署。在 Git 中将基础设施定义为代码，让各类功能处理部署和管理事务。
示例：平台团队维护负责定义标准账户配置（VPC、IAM 角色、RDS 实例和监控堆栈）的 Git 存储库。Argo CD 会自动将这些配置部署到新账户和区域，从而确保一致性，并将手动设置时间从几天缩短到几分钟。
# 使用功能资源
本主题介绍管理所有功能类型的功能资源的常见操作。
## EKS 功能资源
EKS 功能是在 Amazon EKS 集群上启用托管功能的 AWS 资源。各项功能在 EKS 中运行，无需在 Worker 节点上安装和维护控制器和其他操作组件。这些功能是为特定的 EKS 集群创建，并且在整个生命周期内都与该集群保持关联。
每种能力资源都有：
+ 集群中的唯一名称
+ 功能类型（ACK、ARGOCD 或 KRO）
+ Amazon 资源名称（ARN），同时指定名称和类型
+ 功能 IAM 角色
+ 表示当前状态的状态
+ 配置，包括通用配置和特定于功能类型的配置
## 了解功能状态
功能资源的状态表示其当前状态。您可以在 EKS 控制台或使用 AWS CLI 查看功能状态和运行状况。
**控制台**：
1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。
1. 选择集群名称。
1. 选择**功能**选项卡，查看所有功能的状态。
1. 有关详细的运行状况信息，请选择**可观测性**选项卡，然后依次选择**监控集群**、**功能**选项卡。
** AWSCLI**：
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-capability-name
```
### 功能状态
**CREATING**：正在设置功能。您可以离开控制台，功能将继续在后台创建。
**ACTIVE**：功能正在运行中并可供使用。如果资源未按预期运行，请检查资源状态和 IAM 权限。请参阅 [EKS 功能问题排查](capabilities-troubleshooting.md) 查看相关指南。
**UPDATING**：正在应用配置更改。等待状态恢复为 `ACTIVE`。
**删除**：正在从集群中删除功能。
**CREATE\$1FAILED**：设置时遇到了错误。常见原因包括：
+ IAM 角色信任策略不正确或缺失
+ IAM 角色不存在或无法访问
+ 集群访问权限问题
+ 无效的配置参数
有关具体错误的详细信息，请查看功能运行状况部分。
**UPDATE\$1FAILED**：配置更新失败。有关详细信息，请查看功能运行状况部分并验证 IAM 权限。
**提示**
有关详细的问题排查指导，请参阅：
[EKS 功能问题排查](capabilities-troubleshooting.md)：一般功能问题排查
[排查 ACK 功能问题](ack-troubleshooting.md)：ACK 特有的问题
[排查 Argo CD 功能的问题](argocd-troubleshooting.md)：Argo CD 特有的问题
[排查 kro 功能问题](kro-troubleshooting.md)：kro 特有的问题
## 创建功能
要在集群上创建功能，请参阅以下主题：
+ [创建 ACK 功能](create-ack-capability.md)：创建 ACK 功能以使用 Kubernetes API 管理 AWS 资源
+ [创建 Argo CD 功能](create-argocd-capability.md)：创建用于 GitOps 持续交付的 Argo CD 功能
+ [创建 kro 功能](create-kro-capability.md)：创建用于资源组合与编排的 kro 功能
## 列出功能
您可以列出集群上的所有功能资源。
### 控制台
1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。
1. 选择集群名称，打开集群详细信息页面。
1. 选择**功能**选项卡。
1. 在**托管功能**下查看功能资源。
### AWS CLI
使用 `list-capabilities` 命令查看集群上的所有功能。将 *region-code* 替换为您的集群所在的 AWS 区域，并将 *my-cluster* 替换为您的集群的名称。
```
aws eks list-capabilities \
--region region-code \
--cluster-name my-cluster
```
```
{
"capabilities": [
{
"capabilityName": "my-ack",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack/abc123",
"type": "ACK",
"status": "ACTIVE",
"createdAt": "2025-11-02T10:30:00.000000-07:00",
"modifiedAt": "2025-11-02T10:32:15.000000-07:00",
},
{
"capabilityName": "my-kro",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/kro/my-kro/abc123",
"type": "KRO",
"status": "ACTIVE",
"version": "v0.6.3",
"createdAt": "2025-11-02T10:30:00.000000-07:00",
"modifiedAt": "2025-11-02T10:32:15.000000-07:00",
},
{
"capabilityName": "my-argocd",
"arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/argocd/my-argocd/abc123",
"type": "ARGOCD",
"status": "ACTIVE",
"version": "3.1.8-eks-1",
"createdAt": "2025-11-21T08:22:28.486000-05:00",
"modifiedAt": "2025-11-21T08:22:28.486000-05:00"
}
]
}
```
## 描述功能
获取有关特定功能的详细信息，包括其配置和状态。
### 控制台
1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。
1. 选择集群名称，打开集群详细信息页面。
1. 选择**功能**选项卡。
1. 从**托管功能**中选择要查看的功能。
1. 查看功能详细信息，包括状态、配置和创建时间。
### AWS CLI
使用 `describe-capability` 命令查看详细信息。将 *region-code* 替换为集群所在的 AWS 区域，将 *my-cluster* 替换为集群的名称，将 *capability-name* 替换为功能名称（ack、argocd 或 kro）。
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name
```
**输出示例：**
```
{
"capability": {
"capabilityName": "my-ack",
"capabilityArn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack/abc123",
"clusterName": "my-cluster",
"type": "ACK",
"roleArn": "arn:aws:iam::111122223333:role/AmazonEKSCapabilityACKRole",
"status": "ACTIVE",
"configuration": {},
"tags": {},
"health": {
"issues": []
},
"createdAt": "2025-11-19T17:11:30.242000-05:00",
"modifiedAt": "2025-11-19T17:11:30.242000-05:00",
"deletePropagationPolicy": "RETAIN"
}
}
```
## 更新功能的配置
创建后，您可以更新功能配置的某些方面。具体的配置选项因功能类型而异。
**注意**
EKS 功能资源为完全托管，包括修补和版本更新。更新某项功能将更新资源配置，并且不会导致托管功能组件的版本更新。
### AWS CLI
使用 `update-capability` 命令修改功能：
```
aws eks update-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name \
--role-arn arn:aws:iam::[.replaceable]111122223333:role/NewCapabilityRole
```
**注意**
并非所有功能属性在创建后都可以更新。有关可以修改的内容的详细信息，请参阅特定于功能的文档。
## 删除功能
如果不再需要集群上的某项功能，可以删除该功能资源。
**重要**
**在删除功能之前，请先删除集群资源。**
删除功能资源不会自动删除通过该功能创建的资源：
所有 Kubernetes 自定义资源定义（CRD）仍安装在您的集群中。
ACK 资源保留在您的集群中，相应的 AWS 资源则保留在您的账户中
Argo CD 应用程序及其 Kubernetes 资源保留在您的集群中
kro ResourceGraphDefinitions 和实例保留在您的集群中
在删除功能之前，应删除这些资源，以避免存在孤立的资源。
您可以选择保留与 ACK Kubernetes 资源关联的 AWS 资源。请参阅 [ACK 注意事项](ack-considerations.md)
### 控制台
1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。
1. 选择集群名称，打开集群详细信息页面。
1. 选择**功能**选项卡。
1. 从**托管功能**列表中选择要删除的功能。
1. 选择**删除功能**。
1. 在确认对话框中，输入功能名称以确认删除。
1. 选择**删除**。
### AWS CLI
使用 `delete-capability` 命令删除功能资源：
将 *region-code* 替换为集群所在的 AWS 区域，将 *my-cluster* 替换为集群的名称，并将 *capability-name* 替换为要删除的功能名称。
```
aws eks delete-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name capability-name
```
## 后续步骤
+ [功能 Kubernetes 资源](capability-kubernetes-resources.md)：了解每种功能类型提供的 Kubernetes 资源
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念和资源生命周期
+ [使用 Argo CD](working-with-argocd.md)：在 GitOps 工作流程中使用 Argo CD 功能
+ [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源组合编排
# 功能 Kubernetes 资源
在集群上启用某项功能后，通常需要通过在集群中创建和管理 Kubernetes 自定义资源来与该功能进行交互。每种功能都提供自己的一组自定义资源定义（CRD），这些定义通过功能特定的功能扩展 Kubernetes API。
## Argo CD 资源
启用 Argo CD 功能后，您可以创建和管理以下 Kubernetes 资源：
**应用程序**
定义从 Git 存储库到目标集群的部署。`Application` 资源指定源存储库、目标命名空间和同步策略。您可以针对每个 Argo CD 功能实例创建 1000 个 `Application` 资源。
**ApplicationSet**
通过模板生成多个 `Application` 资源，从而实现多集群和多环境部署。`ApplicationSet` 资源使用生成器根据集群列表、Git 目录或其他来源动态创建 `Application` 资源。
**AppProject**
为 `Application` 资源提供逻辑分组和访问控制。`AppProject` 资源定义了 `Application` 资源可以使用的存储库、集群和命名空间，从而实现了多租户和安全边界。
示例 `Application` 资源：
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: my-app
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/org/repo
targetRevision: main
path: manifests
destination:
server: https://kubernetes.default.svc
namespace: production
```
有关 Argo CD 资源和概念的更多信息，请参阅 [Argo CD 概念](argocd-concepts.md)。
## kro 资源
启用 kro 功能后，您可以创建和管理以下 Kubernetes 资源：
**ResourceGraphDefinition（RGD）**
定义一个自定义 API，该 API 将多个 Kubernetes 和 AWS 资源组合成更高级别的抽象。平台团队可创建 `ResourceGraphDefinition` 资源，以提供带有护栏的可重用模式。
**自定义资源实例**
创建 `ResourceGraphDefinition` 资源后，您可以创建由 `ResourceGraphDefinition` 定义的自定义 API 的实例。kro 会自动创建和管理 `ResourceGraphDefinition` 中指定的资源。
示例 `ResourceGraphDefinition` 资源：
```
apiVersion: kro.run/v1alpha1
kind: ResourceGraphDefinition
metadata:
name: web-application
spec:
schema:
apiVersion: v1alpha1
kind: WebApplication
spec:
name: string
replicas: integer
resources:
- id: deployment
template:
apiVersion: apps/v1
kind: Deployment
# ... deployment spec
- id: service
template:
apiVersion: v1
kind: Service
# ... service spec
```
示例 `WebApplication` 实例：
```
apiVersion: v1alpha1
kind: WebApplication
metadata:
name: my-web-app
namespace: default
spec:
name: my-web-app
replicas: 3
```
当您应用此实例时，kro 会自动创建 `ResourceGraphDefinition` 中定义的 `Deployment` 和 `Service` 资源。
有关 kro 资源和概念的更多信息，请参阅 [kro 概念](kro-concepts.md)。
## ACK 资源
启用 ACK 功能后，您可以使用 Kubernetes 自定义资源创建和管理 AWS 资源。ACK 为 50 多项 AWS 服务提供超过 200 个 CRD，允许您在使用 Kubernetes 工作负载的同时定义 AWS 资源，并使用 Kubernetes 管理专用的 AWS 基础设施资源。
ACK 资源示例：
**S3Bucket**
`Bucket` 资源使用版本控制、加密和生命周期策略创建和管理 Amazon S3 存储桶。
**RDS DBInstance**
`DBInstance` 资源通过自动备份和维护时段预置和管理 Amazon RDS 数据库实例。
**DynamoDB 表**
`Table` 资源使用已预置或按需容量创建和管理 DynamoDB 表。
**IAM 角色**
`Role` 资源通过信任策略和权限策略来定义 IAM 角色，以实现 AWS 服务访问。
**Lambda 函数**
`Function` 资源使用代码、运行时和执行角色配置创建和管理 Lambda 函数。
`Bucket` 资源规范示例：
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-app-bucket
spec:
name: my-unique-bucket-name-12345
versioning:
status: Enabled
encryption:
rules:
- applyServerSideEncryptionByDefault:
sseAlgorithm: AES256
```
有关 ACK 资源和概念的更多信息，请参阅 [ACK 概念](ack-concepts.md)。
## 资源限制
EKS 功能具有以下资源限制：
**Argo CD 使用量限制**：
+ 每个 Argo CD 功能实例最多 1000 个 `Application` 资源
+ 每个 Argo CD 功能实例最多配置 100 个远程集群
**资源配置限制**：
+ Argo CD 中每个 `Application` 资源最多 150 个 Kubernetes 资源
+ kro 中每个 `ResourceGraphDefinition` 最多 64 个 Kubernetes 资源
**注意**
这些上限适用于每个功能实例管理的资源数量。如果您需要更高上限，可以跨多个集群部署功能。
## 后续步骤
有关功能特定的任务和高级配置，请参阅以下主题：
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念和资源生命周期
+ [使用 Argo CD](working-with-argocd.md)：在 GitOps 工作流程中使用 Argo CD 功能
+ [kro 概念](kro-concepts.md)：了解 kro 的基本概念及资源组合编排
# EKS 功能和注意事项
本主题涵盖了使用 EKS 功能的重要注意事项，包括访问控制设计、在 EKS 功能和自主管理型解决方案之间进行选择、多集群部署的架构模式以及最佳操作实践。
## 功能 IAM 角色和 Kubernetes RBAC
每个 EKS 功能资源都有一个已配置的功能 IAM 角色。功能角色用于授予 EKS 功能代表您执行操作的 AWS 服务权限。例如，要使用适用于 ACK 的 EKS 功能来管理 Amazon S3 存储桶，您需要向该功能授予 S3 存储桶管理权限，使其能够创建和管理存储桶。
配置该功能后，即可使用集群中的 Kubernetes 自定义资源创建和管理 AWS 中的 S3 资源。Kubernetes RBAC 是一种集群内访问控制机制，用于确定哪些用户和组可以创建和管理这些自定义资源。例如，向特定的 Kubernetes RBAC 用户和组授予在您选择的命名空间中创建和管理 `Bucket` 资源的权限。
因此，IAM 和 Kubernetes RBAC 共同构成了管理与 EKS 功能和资源相关的权限的端到端访问控制系统。为您的使用案例设计一个 IAM 权限与 RBAC 访问策略的正确组合非常重要。
有关功能 IAM 角色和 Kubernetes 权限的更多信息，请参阅 [EKS 功能的安全注意事项](capabilities-security.md)。
## 多集群架构模式
在跨多个集群部署功能时，请考虑以下常见的架构模式：
**采用集中管理的中心和分支**
在集中管理的集群中运行所有三项功能，以编排工作负载并管理多个工作负载集群中的云基础设施。
+ 管理集群上的 Argo CD 可将应用程序部署到不同区域或账户中的工作负载集群
+ 管理集群上的 ACK 会为所有集群预置 AWS 资源（RDS、S3、IAM）
+ 管理集群上的 kro 创建了适用于所有集群的可移植平台抽象
这种模式可以集中管理工作负载和云基础设施，并且可以简化管理许多集群的组织的操作。
**分散式 GitOps**
工作负载和云基础设施由运行工作负载的同一集群上的功能进行管理。
+ Argo CD 管理本地集群上的应用程序资源。
+ ACK 资源用于满足集群和工作负载需求。
+ 已安装 kro 平台抽象并编排本地资源。
这种模式可以分散操作，团队在一个或多个集群中管理自己的专用平台服务。
**采用混合 ACK 部署的中心和分支**
将集中式和分散式模型与基于范围和所有权的集中式应用程序部署和资源管理相结合。
+ 中心集群：
+ Argo CD 管理本地集群和所有远程工作负载集群的 GitOps 部署
+ ACK 在管理集群上用于管理员范围资源（生产数据库、IAM 角色、VPC）
+ kro 在管理集群上用于可重用的平台抽象
+ 分支集群：
+ 工作负载通过集中式中心集群上的 Argo CD 进行管理
+ ACK 在本地用于工作负载范围资源（S3 存储桶、ElastiCache 实例、SQS 队列）
+ kro 在本地用于资源组合和构建块模式
这种模式将关注点进行分离：平台团队在管理集群上集中管理关键基础设施，可以选择包括工作负载集群，而应用程序团队则指定和管理云资源以及工作负载。
**选择模式**
选择架构时要考虑以下因素：
+ **组织结构**：集中式平台团队偏向于选择中心模式；去中心化团队可能更偏好每个集群的功能
+ **资源范围**：管理员范围的资源（数据库、IAM）通常受益于中心管理；而工作负载资源（存储桶、队列）可以在本地管理
+ **自助服务**：集中式平台团队可以编写和分发规范性的自定义资源，以便实现常见工作负载需求的云资源安全自助服务
+ **集群实例集管理**：集中式管理集群为 EKS 集群实例集管理提供了客户拥有的控制面板以及其他管理员范围资源
+ **合规性要求**：一些组织需要对审计和治理采用集中式的控制
+ **操作复杂性**：较少的功能实例可以简化操作，但可能会造成瓶颈
**注意**
您可以从一种模式开始，然后随着平台的成熟发展到另一种模式。功能是独立的，您可以根据需要跨集群以不同的方式进行部署。
## 将 EKS 功能与自主管理型解决方案进行比较
EKS 功能为在 EKS 中运行的常用 Kubernetes 工具和控制器提供完全托管的体验。这与自主管理型解决方案不同，后者是在集群中安装和运行的。
### 主要区别
**部署和管理**
AWS 完全管理 EKS 功能，无需安装、配置或维护组件软件。AWS 在集群中自动安装和管理所有必需的 Kubernetes 自定义资源定义（CRD）。
使用自主管理型解决方案，您可以使用 Helm 图表、kubectl 或其他运算符来安装和配置集群软件。您可以完全控制自主管理型解决方案的软件生命周期和运行时配置，并在解决方案的任何层面提供自定义设置。
**操作与维护**
AWS 通过自动更新和安全补丁管理 EKS 功能的补丁和其他软件生命周期操作。EKS 功能与 AWS 功能集成，实现配置简化，提供内置的高可用性和容错能力，并且无需对控制器工作负载进行集群内问题排查。
自主管理型的解决方案要求您监控组件运行状况和日志，应用安全补丁和版本更新，配置包含多个副本和容器组（pod）中断预算的高可用性，对控制器工作负载问题进行问题排查和修复，以及管理发行版和版本。您可以完全控制自己的部署，但这通常需要为私有集群访问权限和其他集成提供定制解决方案，这些解决方案必须符合组织标准和安全合规性要求。
**资源消耗**
EKS 功能在 EKS 和集群之外运行，从而释放节点资源和集群资源。EKS 功能不使用集群工作负载资源，不消耗 Worker 节点上的 CPU 或内存，可自动扩展，也可尽量减少对集群容量规划的影响。
自主管理型的解决方案在您的 Worker 节点上运行控制器和其他组件，直接消耗 Worker 节点资源、集群 IP 和其他集群资源。管理集群服务需要对其工作负载进行容量规划，并且需要规划和配置资源请求和限制，以管理扩展和高可用性需求。
**功能支持**
作为完全托管的服务功能，与自主管理型的解决方案相比，EKS 功能本质上是较为固定的。虽然 EKS 功能支持大多数功能和使用案例，但与自主管理型的解决方案相比，覆盖范围会有所不同。
使用自主管理型的解决方案，您可以完全控制软件的配置、可选功能和其他方面的功能。您可以选择运行自己的自定义映像，自定义配置的各个方面，并完全控制自主管理型的解决方案功能。
**与成本相关的注意事项**
每个 EKS 功能资源都有相关的每小时成本，该费用因功能类型而异。由该功能管理的集群资源还会产生关联的每小时成本，此部分成本具有独立定价。有关更多信息，请参阅 [Amazon EKS 定价](https://aws.amazon.com/eks/pricing/)。
自主管理型的解决方案没有与 AWS 费用相关的直接成本，但您需要为控制器和相关工作负载使用的集群计算资源付费。除了节点和集群的资源消耗外，自主管理型解决方案的全部拥有成本还包括运营开销以及维护、问题排查和支持费用。
### 在 EKS 功能和自主管理型解决方案之间进行选择
**EKS 功能**当您想要减少运营开销，将注意力集中在软件和系统的差异化价值上，而不是为了基本要求而进行集群平台运营，请考虑这种选择。如果您希望最大限度地减少安全补丁和软件生命周期管理的运营负担，为应用程序工作负载腾出节点和集群资源，简化配置和安全管理，并从 AWS 支持范围中受益，请使用 EKS 功能。EKS 功能非常适合大多数生产使用案例，也是新部署的推荐方法。
**自主管理型解决方案**当您需要特定的 Kubernetes 资源 API 版本、自定义控制器构建，拥有围绕自主管理型部署构建的现有自动化和工具，或者需要对控制器运行时配置进行深度自定义时，可以考虑这种选择。自主管理型的解决方案为特殊使用案例提供了灵活性，并且您可以完全控制自己的部署和运行时配置。
**注意**
EKS 功能可以通过自主管理型解决方案在您的集群中共存，并且可以实现分步迁移。
### 特定功能的比较
有关详细比较，包括功能特定的功能、上游差异和迁移路径，请参阅：
+ [适用于 ACK 的 EKS 功能与自主管理型 ACK 功能的比较](ack-comparison.md)
+ [适用于 Argo CD 的 EKS 功能与自主管理型 Argo CD 的比较](argocd-comparison.md)
+ [EKS 托管型 kro 与自主管理型 kro 的对比](kro-comparison.md)
# 通过 AWS Controllers for Kubernetes（ACK）部署来自 Kubernetes 的 AWS 资源
借助 AWS Controllers for Kubernetes（ACK），您可以直接在 Kubernetes 定义和管理 AWS 服务资源。借助 AWS Controllers for Kubernetes（ACK），您还可以利用熟悉的 Kubernetes API 和工具，将 Kubernetes 自定义资源与应用程序工作负载配合使用，来管理工作负载资源和云基础设施。
得益于 EKS 功能，ACK 完全由 AWS 托管，无需您在集群上安装、维护和扩展 ACK 控制器。
## ACK 的工作原理
ACK 会将 Kubernetes 自定义资源规范转换为 AWS API 调用。创建、更新或删除代表 AWS 服务资源的 Kubernetes 自定义资源时，ACK 会进行必要的 AWS API 调用来创建、更新或删除相应的 AWS 资源。
ACK 支持的每个 AWS 资源都有自己的自定义资源定义（CRD），其作用是定义用以指定其配置的 Kubernetes API 架构。例如，ACK 为 S3 提供 CRD，包括存储桶、存储桶策略及其他 S3 资源。
ACK 会持续协调 AWS 资源的实际状态，使其与 Kubernetes 自定义资源中定义的预期状态保持一致。如果资源实际状态与预期状态存在偏差，ACK 会检测到这一情况，并采取纠正措施使其恢复一致。对 Kubernetes 资源进行的更改会立即反映在 AWS 资源状态中，而对上游 AWS 资源更改的被动偏差检测和修复可能需要长达 10 个小时（即重新同步周期），但实际速度通常要快得多。
**示例 S3 存储桶资源清单**
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-ack-bucket
spec:
name: my-unique-bucket-name
```
将此自定义资源应用于集群时，如果 Amazon S3 存储桶尚不存在，ACK 会在账户中创建一个存储桶。对该资源的后续更改（例如指定非默认存储层或添加策略）将应用于 AWS 中的 S3 资源。从集群中删除此资源时，默认情况下也将删除 AWS 中的 S3 存储桶。
## ACK 的优势
ACK 有助于您在 Kubernetes 本地管理 AWS 资源，从而让您更方便地使用与管理应用程序相同的 Kubernetes API 和工具来管理 AWS 资源。这种统一的方法简化了基础设施管理工作流程，无需在不同工具之间切换或学习单独的基础设施即代码系统。您可以在 Kubernetes 清单中以声明方式定义 AWS 资源，从而实现 GitOps 工作流程和基础设施即代码实践，并与现有的开发流程无缝集成。
ACK 会根据 AWS 资源的预期状态来持续协调实际状态，从而纠正偏差并确保整个基础设施的一致性。这种持续协调意味着，对 AWS 资源进行的命令式带外更改都将自动恢复，以匹配所声明的配置，从而维护基础设施即代码的完整性。您可以配置 ACK 以管理跨多个 AWS 账户和区域的资源，无需其他工具即可部署复杂的多账户架构。
对于从其他基础设施管理工具迁移的组织，ACK 支持资源接管，从而允许您将现有的 AWS 资源纳入 ACK 管理，无需重新创建资源。此外，ACK 不仅可在不修改访问权限的前提下提供用于观察 AWS 资源的只读资源，还可提供注释，即使从集群中删除 Kubernetes 资源也可选择保留 AWS 资源。
要了解更多信息并开始使用适用于 ACK 的 EKS 功能，请参阅 [ACK 概念](ack-concepts.md)和[针对 EKS 的 ACK 注意事项](ack-considerations.md)。
## 支持的 AWS 服务
ACK 支持众多 AWS 服务，包括但不限于：
+ Amazon EC2
+ Amazon S3
+ Amazon RDS
+ Amazon DynamoDB
+ Amazon ElastiCache
+ Amazon EKS
+ Amazon SQS
+ Amazon SNS
+ AWS Lambda
+ AWS IAM
适用于 ACK 的 EKS 功能支持所有在上游列为“已正式发布”的 AWS 服务。有关详细信息，请参阅[支持的 AWS 服务完整列表](https://aws-controllers-k8s.github.io/community/docs/community/services/)。
## 与其他 EKS 托管功能集成
ACK 可与其他 EKS 托管功能集成。
+ **Argo CD**：使用 Argo CD 跨多个集群管理 ACK 资源的部署，为 AWS 基础设施启用 GitOps 工作流。
+ 当与 ArgoCD 配对时，ACK 能扩大 GitOps 的优势，但 ACK 本身不要求与 git 集成。
+ **kro（Kube Resource Orchestrator）**：使用 kro 从 ACK 资源组合复杂的资源，创建更高级别的抽象以简化资源管理。
+ 您可以使用 kro 创建复合自定义资源，这些资源同时定义了 Kubernetes 资源和 AWS 资源。团队成员可以使用这些自定义资源，快速部署复杂的应用程序。
## 开始使用 ACK
要开始使用适用于 ACK 的 EKS 功能，请执行以下操作：
1. 创建并配置一个 IAM 功能角色，授予 ACK 代表您管理 AWS 资源所需的必要权限。
1. 通过 AWS 管理控制台、AWS CLI 或偏好的基础设施即代码工具，在 EKS 集群上[创建 ACK 功能资源](create-ack-capability.md)。
1. 将 Kubernetes 自定义资源应用于集群，从而开始在 Kubernetes 中管理 AWS 资源。
# 创建 ACK 功能
本章节旨在介绍如何在 Amazon EKS 集群上创建 ACK 功能。
## 先决条件
创建 ACK 功能之前，确保满足以下条件：
+ Amazon EKS 集群
+ 具有允许 ACK 管理 AWS 资源的权限的 IAM 功能角色
+ 可在 EKS 集群上创建功能资源的充足 IAM 权限
+ 已安装和配置相应的 CLI 工具，或可访问 EKS 控制台
有关如何创建 IAM 功能角色的说明，请参阅 [Amazon EKS 功能 IAM 角色](capability-role.md)。
**重要**
ACK 是一种基础设施管理功能，可创建、修改和删除 AWS 资源。这是一项管理员范围的功能，应谨慎控制。任何具有在您的集群中创建 Kubernetes 资源权限的用户，都可以通过 ACK 有效地创建 AWS 资源，但需具有 IAM 功能角色权限。您提供的 IAM 功能角色决定 ACK 可以创建和管理哪些 AWS 资源。有关创建具备最低权限的合适角色的操作指引，请参阅 [Amazon EKS 功能 IAM 角色](capability-role.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。
## 选择工具
您可以使用AWS 管理控制台、AWS CLI 或 eksctl 创建 ACK 功能：
+ [使用控制台创建 ACK 功能](ack-create-console.md)：使用控制台获得引导式体验
+ [使用 AWS CLI 创建 ACK 功能](ack-create-cli.md)：使用 AWS CLI 进行脚本编写和自动化
+ [使用 eksctl 创建 ACK 功能](ack-create-eksctl.md)：使用 eksctl 获得 Kubernetes 原生体验
## 在创建 ACK 功能时会执行的操作
创建 ACK 功能时：
1. EKS 会创建 ACK 功能服务，并配置该服务来监控和管理集群内的资源
1. 自定义资源定义（CRD）将被安装到集群中
1. 系统会自动为您的 IAM 功能角色创建一个访问条目，该条目带有特定于功能的访问条目策略，这些策略会授予基本的 Kubernetes 权限（请参阅 [EKS 功能的安全注意事项](capabilities-security.md)）
1. 该功能会代入您提供的 IAM 功能角色
1. ACK 开始监视集群中的自定义资源
1. 功能状态从 `CREATING` 更改为 `ACTIVE`
激活后，您可以在集群中创建 ACK 自定义资源，来管理 AWS 资源。
**注意**
自动创建的访问条目包括授予 ACK 管理 AWS 资源的权限的 `AmazonEKSACKPolicy`。一些引用 Kubernetes 密钥的 ACK 资源（例如带有密码的 RDS 数据库）需要额外的访问条目策略。要了解有关访问条目以及如何配置其他权限的更多信息，请参阅 [EKS 功能的安全注意事项](capabilities-security.md)。
## 后续步骤
创建 ACK 功能后：
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念并开始使用 AWS 资源
+ [ACK 概念](ack-concepts.md)：了解协调、字段导出和资源采用模式
+ [配置 ACK 权限](ack-permissions.md)：配置 IAM 权限和多账户模式
# 使用控制台创建 ACK 功能
本主题将介绍如何使用 AWS 管理控制台创建 AWS Controllers for Kubernetes（ACK）功能。
## 创建 ACK 功能
1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。
1. 选择集群名称，打开集群详细信息页面。
1. 选择**功能**选项卡。
1. 在左侧导航栏中，选择 **AWS Controllers for Kubernetes（ACK）**。
1. 选择**创建 AWS Controllers for Kubernetes 功能**。
1. 对于 **IAM 功能角色**：
+ 如果已有 IAM 功能角色，请从下拉列表中选择该角色
+ 如果您需要创建一个新角色，请选择**创建管理员角色**
这将在新选项卡中打开 IAM 控制台，其中包含预先填充的信任策略和 `AdministratorAccess` 托管式策略。您可以根据需要取消选择此策略并添加其他权限。
创建角色后，返回 EKS 控制台，系统将自动选择该角色。
**重要**
建议的 `AdministratorAccess` 策略授予了广泛权限，旨在简化入门流程。对于生产用途，请将其替换为自定义策略，该策略仅授予您计划通过 ACK 管理的特定 AWS 服务所需的权限。有关创建最低权限策略的指导，请参阅[配置 ACK 权限](ack-permissions.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。
1. 选择**创建**。
功能创建过程随即开始。
## 验证功能是否处于活动状态
1. 在**功能**选项卡上，查看 ACK 功能状态。
1. 等待状态从 `CREATING` 更改为 `ACTIVE`。
1. 变为活动状态后，该功能即可使用。
有关功能状态和问题排查的信息，请参阅[使用功能资源](working-with-capabilities.md)。
## 验证自定义资源是否可用
功能激活后，验证 ACK 自定义资源是否已在集群中可用。
**使用控制台**
1. 在 Amazon EKS 控制台中导航至集群
1. 选择**资源**选项卡
1. 选择**扩展**
1. 选择 **CustomResourceDefinitions**
您应该会看到列出的多个用于 AWS 资源的 CRD。
**使用 kubectl**
```
kubectl api-resources | grep services.k8s.aws
```
您应该会看到列出的多个用于 AWS 资源的 API。
**注意**
AWS Controllers for Kubernetes 功能将为各种 AWS 资源安装大量 CRD。
## 后续步骤
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念并开始使用
+ [配置 ACK 权限](ack-permissions.md)：为其他 AWS 服务配置 IAM 权限
+ [使用功能资源](working-with-capabilities.md)：管理 ACK 功能资源
# 使用 AWS CLI 创建 ACK 功能
本主题将介绍如何使用 AWS CLI 创建 AWS Controllers for Kubernetes（ACK）功能。
## 先决条件
+ **AWS CLI**：版本 `2.12.3` 或更高版本。要检查版本，请运行 `aws --version`。有关更多信息，请参阅《AWS 命令行界面用户指南》中的[安装](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)。
+ **`kubectl`**：用于与 Kubernetes 集群结合使用的命令行工具。有关更多信息，请参阅 [设置 `kubectl` 和 `eksctl`](install-kubectl.md)。
## 步骤 1：创建 IAM 功能角色
创建信任策略文件：
```
cat > ack-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
创建 IAM 角色：
```
aws iam create-role \
--role-name ACKCapabilityRole \
--assume-role-policy-document file://ack-trust-policy.json
```
将 `AdministratorAccess` 托管式策略附加到角色：
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**重要**
建议的 `AdministratorAccess` 策略授予了广泛权限，旨在简化入门流程。对于生产用途，请将其替换为自定义策略，该策略仅授予您计划通过 ACK 管理的特定 AWS 服务所需的权限。有关创建最低权限策略的指导，请参阅[配置 ACK 权限](ack-permissions.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。
## 步骤 2：创建 ACK 功能
在集群上创建 ACK 功能资源。将 *region-code* 替换为您的集群所在的 AWS 区域，并将 *my-cluster* 替换为您的集群的名称。
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack \
--type ACK \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ACKCapabilityRole \
--delete-propagation-policy RETAIN
```
命令会立即返回，但是由于 EKS 正在创建所需的功能基础设施和组件，该功能需要一些时间才能变为活动状态。在创建集群时，EKS 将在集群中安装与此功能相关的 Kubernetes 自定义资源定义。
**注意**
如果收到集群不存在或您没有权限的错误消息，请验证：
集群名称是否正确
AWS CLI 是否针对正确的区域进行配置
您是否拥有所需的 IAM 权限
## 步骤 3：验证功能是否处于活动状态
等待功能变为活动状态。将 *region-code* 替换为您的集群所在的 AWS 区域，并将 *my-cluster* 替换为您的集群的名称。
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack \
--query 'capability.status' \
--output text
```
当状态显示为 `ACTIVE` 时，表示功能已准备就绪。在该状态变为 `ACTIVE` 之前，请勿继续执行下一步。
您也可以查看完整功能详细信息：
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-ack
```
## 步骤 4：验证自定义资源是否可用
功能激活后，验证 ACK 自定义资源是否已在集群中可用：
```
kubectl api-resources | grep services.k8s.aws
```
您应该会看到列出的多个用于 AWS 资源的 API。
**注意**
AWS Controllers for Kubernetes 功能将为各种 AWS 资源安装大量 CRD。
## 后续步骤
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念并开始使用
+ [配置 ACK 权限](ack-permissions.md)：为其他 AWS 服务配置 IAM 权限
+ [使用功能资源](working-with-capabilities.md)：管理 ACK 功能资源
# 使用 eksctl 创建 ACK 功能
本主题将介绍如何使用 eksctl 创建 AWS Controllers for Kubernetes（ACK）功能。
**注意**
以下步骤需要 eksctl 版本 `0.220.0` 或更高版本。要检查版本，请运行 `eksctl version`。
## 步骤 1：创建 IAM 功能角色
创建信任策略文件：
```
cat > ack-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
创建 IAM 角色：
```
aws iam create-role \
--role-name ACKCapabilityRole \
--assume-role-policy-document file://ack-trust-policy.json
```
将 `AdministratorAccess` 托管式策略附加到角色：
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::aws:policy/AdministratorAccess
```
**重要**
建议的 `AdministratorAccess` 策略授予了广泛权限，旨在简化入门流程。对于生产用途，请将其替换为自定义策略，该策略仅授予您计划通过 ACK 管理的特定 AWS 服务所需的权限。有关创建最低权限策略的指导，请参阅[配置 ACK 权限](ack-permissions.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。
**重要**
此策略通过 `"Resource": "*"` 授予 S3 存储桶管理权限，允许对所有 S3 存储桶进行操作。
用于生产用途：\$1 将 `Resource` 字段限制为特定的存储桶 ARN 或名称模式 \$1 使用 IAM 条件键通过资源标签限制访问权限 \$1 仅授予使用案例所需的最低权限
有关其他 AWS 服务，请参阅[配置 ACK 权限](ack-permissions.md)。
将该策略附加到角色：
```
aws iam attach-role-policy \
--role-name ACKCapabilityRole \
--policy-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/ACKS3Policy
```
## 步骤 2：创建 ACK 功能
使用 eksctl 创建 ACK 功能。将 *region-code* 替换为您的集群所在的 AWS 区域，并将 *my-cluster* 替换为您的集群的名称。
```
eksctl create capability \
--cluster [.replaceable]`my-cluster` \
--region [.replaceable]`region-code` \
--name ack \
--type ACK \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ACKCapabilityRole \
--ack-service-controllers s3
```
**注意**
`--ack-service-controllers` 标记是可选的。如果省略，ACK 将启用所有可用的控制器。为了获得更好的性能和安全性，请考虑仅启用所需的控制器。您可以指定多个控制器，例如：`--ack-service-controllers s3,rds,dynamodb`
命令会立即返回，但该功能需要一些时间才能变为活动状态。
## 步骤 3：验证功能是否处于活动状态
检查功能状态：
```
eksctl get capability \
--cluster [.replaceable]`my-cluster` \
--region [.replaceable]`region-code` \
--name ack
```
当状态显示为 `ACTIVE` 时，表示功能已准备就绪。
## 步骤 4：验证自定义资源是否可用
功能激活后，验证 ACK 自定义资源是否已在集群中可用：
```
kubectl api-resources | grep services.k8s.aws
```
您应该会看到列出的多个用于 AWS 资源的 API。
**注意**
AWS Controllers for Kubernetes 功能将为各种 AWS 资源安装大量 CRD。
## 后续步骤
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念并开始使用
+ [配置 ACK 权限](ack-permissions.md)：为其他 AWS 服务配置 IAM 权限
+ [使用功能资源](working-with-capabilities.md)：管理 ACK 功能资源
# ACK 概念
ACK 通过 Kubernetes API 管理 AWS 资源，方法是根据清单中定义的预期状态，持续协调 AWS 中的实际状态。创建或更新 Kubernetes 自定义资源时，ACK 会进行必要的 AWS API 调用来创建或修改相应的 AWS 资源，随后持续监控其状态是否存在偏差，并更新 Kubernetes 中的资源状态以反映当前实际状态。借助此方法，您可以使用熟悉的 Kubernetes 工具和工作流程来管理基础设施，同时保持集群与 AWS 之间的一致性。
本主题将阐释有关 ACK 如何通过 Kubernetes API 管理 AWS 资源的基本概念。
## 开始使用 ACK
创建 ACK 功能后（请参阅[创建 ACK 功能](create-ack-capability.md)），即可开始在集群中使用 Kubernetes 清单管理 AWS 资源。
例如，将以下 S3 存储桶清单创建为 `bucket.yaml`，并为自己的存储桶选择唯一名称。
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-test-bucket
namespace: default
spec:
name: my-unique-bucket-name-12345
```
应用清单：
```
kubectl apply -f bucket.yaml
```
检查状态：
```
kubectl get bucket my-test-bucket
kubectl describe bucket my-test-bucket
```
验证存储桶是否已在 AWS 中创建：
```
aws s3 ls | grep my-unique-bucket-name-12345
```
删除 Kubernetes 资源：
```
kubectl delete bucket my-test-bucket
```
验证存储桶是否已从 AWS 中删除：
```
aws s3 ls | grep my-unique-bucket-name-12345
```
该存储桶不应再出现在列表中，这表明 ACK 正在管理 AWS 资源的完整生命周期。
有关 ACK 入门的更多信息，请参阅 [ACK 入门](https://aws-controllers-k8s.github.io/community/docs/user-docs/getting-started/)。
## 资源生命周期与协调
ACK 使用持续的协调循环，以确保 AWS 资源与 Kubernetes 清单中定义的预期状态保持一致。
**协调的工作原理**：
1. 您创建或更新 Kubernetes 自定义资源（例如 S3 存储桶）
1. ACK 检测到更改，并将预期状态与 AWS 中的实际状态进行比较
1. 如果两者不一致，ACK 会进行 AWS API 调用来协调差异
1. ACK 会更新 Kubernetes 中的资源状态以反映当前状态
1. 该循环持续重复，通常每隔几个小时运行一次
在以下情况下会触发协调：创建新的 Kubernetes 资源、更新现有资源的 `spec`，或 ACK 检测到在 ACK 外部进行的手动更改导致 AWS 中的状态存在偏差。此外，ACK 还会定期进行协调，其重新同步周期为 10 个小时。对 Kubernetes 资源进行更改会立即触发协调，而对上游 AWS 资源更改的被动偏差检测则会在重新同步周期内发生。
当您完成上述开始使用示例后，ACK 会执行以下步骤：
1. 检查 AWS 中是否存在存储桶
1. 如果不存在，则调用 `s3:CreateBucket`
1. 使用存储桶 ARN 和状态更新 Kubernetes 状态
1. 持续监控状态偏差
要了解有关 ACK 工作原理的更多信息，请参阅 [ACK 协调](https://aws-controllers-k8s.github.io/community/docs/user-docs/reconciliation/)。
## 状态条件
ACK 资源使用状态条件来传达其状态。理解这些条件有助于您排查问题并了解资源运行状况。
+ **Ready**：表示资源已准备就绪，可供使用（标准化的 Kubernetes 条件）。
+ **ACK.ResourceSynced**：表示资源规范与 AWS 资源状态相匹配。
+ **ACK.Terminal**：表示发生了不可恢复的错误。
+ **ACK.Adopted**：表示资源是从现有 AWS 资源接管而来，而非新建的。
+ **ACK.Recoverable**：表示发生了可恢复的错误，可能无需更新规范即可解决。
+ **ACK.Advisory**：提供有关资源的参考信息。
+ **ACK.LateInitialized**：表示是否已完成字段的延迟初始化。
+ **ACK.ReferencesResolved**：表示是否已解析所有 `AWSResourceReference` 字段。
+ **ACK.IAMRoleSelected**：表示是否已选择 IAMRoleSelector 来管理此资源。
检查资源状态：
```
# Check if resource is ready
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
# Check for terminal errors
kubectl get bucket my-bucket -o jsonpath='{.status.conditions[?(@.type=="ACK.Terminal")]}'
```
示例状态：
```
status:
conditions:
- type: Ready
status: "True"
lastTransitionTime: "2024-01-15T10:30:00Z"
- type: ACK.ResourceSynced
status: "True"
lastTransitionTime: "2024-01-15T10:30:00Z"
- type: ACK.Terminal
status: "True"
ackResourceMetadata:
arn: arn:aws:s3:::my-unique-bucket-name
ownerAccountID: "111122223333"
region: us-west-2
```
要了解有关 ACK 状态和条件的更多信息，请参阅 [ACK 条件](https://aws-controllers-k8s.github.io/community/docs/user-docs/conditions/)。
## 删除策略
ACK 的删除策略决定了当您删除 Kubernetes 资源时，相应 AWS 资源的处置方式。
**删除（默认）**
删除 Kubernetes 资源时，相应的 AWS 资源也将删除，这是默认行为。
```
# No annotation needed - this is the default
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: temp-bucket
spec:
name: temporary-bucket
```
删除此资源将同时删除 AWS 中的 S3 存储桶。
**Retain**：
删除 Kubernetes 资源时，相应的 AWS 资源将保留：
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: important-bucket
annotations:
services.k8s.aws/deletion-policy: "retain"
spec:
name: production-data-bucket
```
删除此资源会将其从 Kubernetes 中移除，但会保留 AWS 中的 S3 存储桶。
`retain` 策略适用于以下场景：生产数据库的生命周期超过 Kubernetes 资源，多个应用程序使用共享资源，资源包含不应意外删除的重要数据，或者临时管理 ACK（即先接管一个资源，对其进行配置，然后将其释放回手动管理）。
要了解有关 ACK 删除策略的更多信息，请参阅 [ACK 删除策略](https://aws-controllers-k8s.github.io/community/docs/user-docs/deletion-policy/)。
## 资源接管
通过接管，您可以将现有的 AWS 资源纳入 ACK 管理，而无需重新创建它们。
何时使用接管：
+ 将现有基础设施迁移到 ACK 管理
+ 在 Kubernetes 中意外删除资源的情况下，恢复孤立的 AWS 资源
+ 导入由其他工具（CloudFormation、Terraform）创建的资源
接管的工作原理：
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
当您创建此资源时：
1. ACK 会检查 AWS 中是否存在具有该名称的存储桶
1. 如果找到存储桶，ACK 就会接管它（无需调用 API 创建）
1. ACK 从 AWS 读取当前配置
1. ACK 会更新 Kubernetes 状态以反映实际状态
1. 未来的更新会正常协调该资源
接管后，资源将像任何其他 ACK 资源一样进行管理，并且删除 Kubernetes 资源时将删除相应的 AWS 资源，除非您使用了 `retain` 删除策略。
接管资源时，AWS 资源必须已存在，并且 ACK 需要读取权限才能发现它。如果资源存在，`adopt-or-create` 策略会接管该资源，如果资源不存在，则会创建。当您需要一个无论资源是否存在都能正常工作的声明式工作流程时，这将非常有用。
要了解有关 ACK 资源接管的更多信息，请参阅 [ACK 资源接管](https://aws-controllers-k8s.github.io/community/docs/user-docs/adopted-resource/)。
## 跨账户和跨区域资源
ACK 可以从单个集群管理位于不同 AWS 账户和区域的资源。
**跨区域资源注释**
您可以使用注释指定 AWS 资源的区域：
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: eu-bucket
annotations:
services.k8s.aws/region: eu-west-1
spec:
name: my-eu-bucket
```
您还可以为特定命名空间中创建的所有 AWS 资源指定默认区域：
**命名空间注释**
为命名空间中的所有资源设置默认区域：
```
apiVersion: v1
kind: Namespace
metadata:
name: production
annotations:
services.k8s.aws/default-region: us-west-2
```
除非被资源级注释覆盖，否则在此命名空间中创建的资源将使用此区域。
**跨账户**
使用 IAM 角色选择器将特定的 IAM 角色映射到命名空间：
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: target-account-config
spec:
arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
namespaceSelector:
names:
- production
```
在映射的命名空间中创建的资源会自动使用指定的角色。
要了解有关 IAM 角色选择器的更多信息，请参阅 [ACK 跨账户资源管理](https://aws-controllers-k8s.github.io/docs/guides/cross-account)。有关跨账户配置的详细信息，请参阅[配置 ACK 权限](ack-permissions.md)。
## 错误处理和重试行为
ACK 会自动处理瞬态错误并重试失败的操作。
重试策略：
+ 瞬态错误（速率限制、临时服务问题、权限不足）会触发自动重试
+ 指数回退可防止 API AWS 负载过重
+ 最大重试次数因错误类型而异
+ 永久错误（参数无效、资源名称冲突）不会重试
使用 `kubectl describe` 检查资源状态以了解错误详情：
```
kubectl describe bucket my-bucket
```
查找包含错误消息的状态条件、显示最近协调尝试的事件，以及状态条件中说明失败原因的 `message` 字段。常见错误包括 IAM 权限不足、AWS 中的资源名称冲突、`spec` 中的配置值无效、超出 AWS 服务配额等。
有关如何排查常见错误，请参阅[排查 ACK 功能问题](ack-troubleshooting.md)。
## 使用 kro 进行资源组合
如需将多个 ACK 资源组合并连接在一起，请使用适用于 kro 的 EKS 功能（Kube Resource Orchestrator）。kro 提供了一种声明方式来定义资源组，通过在资源之间传递配置，来简化复杂基础设施模式的管理。
有关使用 ACK 资源创建自定义资源组合的详细示例，请参阅 [kro 概念](kro-concepts.md)
## 后续步骤
+ [针对 EKS 的 ACK 注意事项](ack-considerations.md)：EKS 特定模式与集成策略
# 配置 ACK 权限
ACK 需要 IAM 权限才能代表您创建和管理 AWS 资源。本主题将介绍 IAM 如何与 ACK 结合使用，并提供有关为不同使用案例配置权限的指导。
## IAM 如何与 ACK 结合使用
ACK 使用 IAM 角色向 AWS 进行身份验证并对资源执行操作。向 ACK 提供权限有两种方式：
**功能角色**：您在创建 ACK 功能时提供的 IAM 角色。默认情况下，所有 ACK 操作都使用此角色。
**IAM 角色选择器**：可映射到特定命名空间或资源的其他 IAM 角色。这些角色会覆盖其作用域内资源的功能角色。
当 ACK 需要创建或管理资源时，它会决定使用哪个 IAM 角色：
1. 检查 IAMRoleSelector 是否与资源所在的命名空间相匹配
1. 如果找到匹配项，则代入该 IAM 角色
1. 否则，请使用功能角色
这种方式可以实现灵活的权限管理，从简单的单角色设置到复杂的多账户、多团队配置均适用。
## 入门：简单权限设置
适用于开发、测试或简单使用案例，您可以将所有必要的服务权限直接添加到功能角色。
此方式适用于以下情况：
+ 您刚开始使用 ACK
+ 所有资源都在同一 AWS 账户中
+ 由单个团队管理所有 ACK 资源
+ 您信任所有 ACK 用户拥有相同的权限
## 生产最佳实践：IAM 角色选择器
对于生产环境，请使用 IAM 角色选择器来实现最低权限访问和命名空间级隔离。
使用 IAM 角色选择器时，功能角色只需要 `sts:AssumeRole` 和 `sts:TagSession` 权限即可代入服务特定角色。您无需向功能角色本身添加任何 AWS 服务权限（如 S3 或 RDS），系统会向功能角色所代入的各个 IAM 角色授予这些权限。
**选择权限模式**：
在以下情况下，使用**直接权限**（将服务权限添加到功能角色）：
+ 您刚开始使用并希望最简单的设置
+ 所有资源与集群位于同一账户
+ 您有集群范围的管理权限要求
+ 所有团队都可以共享相同的权限
在以下情况下，使用 **IAM 角色选择器**：
+ 跨多个 AWS 账户管理资源
+ 不同的团队或命名空间需要不同的权限
+ 您需要按命名空间进行精细访问控制
+ 您希望遵循最低权限安全实践
您可以从直接权限开始，随着需求的增长，再迁移到 IAM 角色选择器。
**为什么要在生产环境中使用 IAM 角色选择器：**
+ **最低权限**：每个命名空间仅获得其所需的权限
+ **团队隔离**：团队 A 不会意外使用团队 B 的权限
+ **更易审计**：清晰映射哪个命名空间使用哪个角色
+ **跨账户支持**：在多个账户中管理资源所必需的功能
+ **关注点分离**：不同的服务或环境使用不同的角色
### 基本 IAM 角色选择器设置
**步骤 1：创建服务特定的 IAM 角色**
创建具有特定 AWS 服务权限的 IAM 角色：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": "*"
}
]
}
```
配置信任策略，以允许功能角色代入该策略：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole"
},
"Action": ["sts:AssumeRole", "sts:TagSession"]
}
]
}
```
**步骤 2：向功能角色授予 AssumeRole 权限**
向功能角色添加代入该服务特定角色的权限：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::111122223333:role/ACK-S3-Role"
}
]
}
```
**步骤 3：创建 IAMRoleSelector**
将 IAM 角色映射到命名空间：
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: s3-namespace-config
spec:
arn: arn:aws:iam::111122223333:role/ACK-S3-Role
namespaceSelector:
names:
- s3-resources
```
**步骤 4：在映射的命名空间中创建资源**
`s3-resources` 命名空间中的资源会自动使用指定的角色：
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-bucket
namespace: s3-resources
spec:
name: my-production-bucket
```
## 多账户管理
使用 IAM 角色选择器跨多个 AWS 账户管理资源。
**步骤 1：创建跨账户 IAM 角色**
在目标账户（444455556666）中，创建一个信任源账户功能角色的角色：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/ACKCapabilityRole"
},
"Action": ["sts:AssumeRole", "sts:TagSession"]
}
]
}
```
将服务特定权限附加到此角色。
**步骤 2：授予 AssumeRole 权限**
在源账户（111122223333）中，允许功能角色代入目标账户角色：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::444455556666:role/ACKTargetAccountRole"
}
]
}
```
**步骤 3：创建 IAMRoleSelector**
将跨账户角色映射到命名空间：
```
apiVersion: services.k8s.aws/v1alpha1
kind: IAMRoleSelector
metadata:
name: production-account-config
spec:
arn: arn:aws:iam::444455556666:role/ACKTargetAccountRole
namespaceSelector:
names:
- production
```
**步骤 4：创建资源**
`production` 命名空间中的资源将在目标账户中创建：
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: my-bucket
namespace: production
spec:
name: my-cross-account-bucket
```
## 会话标签
EKS ACK 功能会自动为所有 AWS API 请求设置会话标签。这些标签能够通过识别每个请求的来源来实现精细的访问控制和审计。
### 可用的会话标签
ACK 发出的每个 AWS API 调用都包含以下会话标签：
| 标签密钥 | 说明 |
| --- | --- |
| `eks:eks-capability-arn` | 发出请求的 EKS 功能的 ARN |
| `eks:kubernetes-namespace` | 正在管理的资源的 Kubernetes 命名空间 |
| `eks:kubernetes-api-group` | 资源的 Kubernetes API 组（例如 `s3.services.k8s.aws`） |
### 使用会话标签进行访问控制
您可以在 IAM 策略条件中使用这些会话标签来限制 ACK 可以管理的资源。此操作在基于命名空间的 IAM 角色选择器之外提供了额外的安全层。
**示例：按命名空间进行限制**
仅当请求来自 `production` 命名空间时，才允许 ACK 创建 S3 存储桶：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:CreateBucket",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks:kubernetes-namespace": "production"
}
}
}
]
}
```
**示例：按功能进行限制**
仅允许来自特定 ACK 功能的操作：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:PrincipalTag/eks:eks-capability-arn": "arn:aws:eks:us-west-2:111122223333:capability/my-cluster/ack/my-ack"
}
}
}
]
}
```
**注意**
会话标签与自主管理的 ACK 有所不同，后者默认不设置这些标签。这样便可通过托管功能实现更精细的访问控制。
## 高级 IAM 角色选择器模式
有关高级配置，例如标签选择器、资源特定角色映射及其他示例，请参阅 [ACK IRSA 文档](https://aws-controllers-k8s.github.io/community/docs/user-docs/irsa/)。
## 后续步骤
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念和资源生命周期
+ [ACK 概念](ack-concepts.md)：了解资源接管和删除策略
+ [EKS 功能的安全注意事项](capabilities-security.md)：了解针对功能的安全最佳实践
# 针对 EKS 的 ACK 注意事项
本主题涵盖使用适用于 ACK 的 EKS 功能的重要注意事项，包括 IAM 配置、多账户模式以及与其他 EKS 功能集成。
## IAM 配置模式
ACK 功能使用 IAM 功能角色向 AWS 进行身份验证。根据需求选择合适的 IAM 模式。
### 简易模式：单一功能角色
适用于开发、测试或简单使用案例，直接向功能角色授予所有必要权限。
**何时使用**：
+ 开始使用 ACK
+ 单账户部署
+ 所有资源均由一个团队托管
+ 开发和测试环境
**示例**：向功能角色添加带有资源标记条件的 S3 和 RDS 权限：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:*"],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": ["us-west-2", "us-east-1"]
}
}
},
{
"Effect": "Allow",
"Action": ["rds:*"],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestedRegion": ["us-west-2", "us-east-1"]
},
}
}
]
}
```
此示例将 S3 和 RDS 操作限制在特定区域，并要求 RDS 资源必须带有 `ManagedBy: ACK` 标签。
### 生产模式：IAM 角色选择器
对于生产环境，请使用 IAM 角色选择器来实现最低权限访问和命名空间级隔离。
**何时使用**：
+ 生产环境
+ 多团队集群
+ 多账户资源管理
+ 满足最低权限安全要求
+ 不同的服务需要不同的权限
**优点：**
+ 每个命名空间仅获得其所需的权限
+ 团队隔离：团队 A 无法使用团队 B 的权限
+ 更易于审计和合规
+ 需要进行跨账户资源管理
有关 IAM 角色选择器配置的详细信息，请参阅[配置 ACK 权限](ack-permissions.md)。
## 与其他 EKS 功能集成
### 将 Argo CD 与 GitOps 搭配使用
使用适用于 Argo CD 的 EKS 功能，从 Git 存储库部署 ACK 资源，从而为基础设施管理启用 GitOps 工作流程。
**注意事项：**
+ 将 ACK 资源与应用程序清单存储在一起，实现端到端 GitOps
+ 根据团队结构，按环境、服务或资源类型整理
+ 使用 Argo CD 的自动同步功能实现持续协调
+ 启用修剪来自动移除已删除的资源
+ 考虑采用轴辐模式进行多集群基础设施管理
GitOps 提供审计跟踪记录、回滚功能和声明式基础设施管理。有关 Argo CD 的更多信息，请参阅[使用 Argo CD](working-with-argocd.md)。
### 使用 kro 进行资源组合
使用适用于 kro 的 EKS 功能（Kube Resource Orchestrator），将多个 ACK 资源组合成更高级别的抽象和自定义 API。
**何时将 kro 与 ACK 结合使用**：
+ 为常见的基础设施堆栈创建可重复使用的模式（数据库 \$1 备份 \$1 监控）
+ 为应用团队构建带有简化 API 的自助式平台
+ 管理资源依赖项并在资源之间传递值（例如将 S3 存储桶 ARN 传递给 Lambda 函数）
+ 跨多个团队标准化基础设施配置
+ 通过将实现细节隐藏在自定义资源背后来降低复杂性
**示例模式**：
+ 应用程序堆栈：S3 存储桶 \$1 SQS 队列 \$1 通知配置
+ 数据库设置：RDS 实例 \$1 参数组 \$1 安全组 \$1 密钥
+ 联网：VPC \$1 子网 \$1 路由表 \$1 安全组
kro 负责处理组合资源的依赖项排序、状态传播和生命周期管理。有关 kro 的更多信息，请参阅 [kro 概念](kro-concepts.md)。
## 整理资源
使用 Kubernetes 命名空间和 AWS 资源标签来整理 ACK 资源，以便更轻松地进行管理、访问控制和成本跟踪。
### 整理命名空间
使用 Kubernetes 命名空间按环境（生产、暂存、开发）、团队（平台、数据、ml）或应用程序在逻辑上分隔 ACK 资源。
**优点：**
+ 通过作用域为命名空间的 RBAC 实现访问控制
+ 使用注释为每个命名空间设置默认区域
+ 更轻松地管理和清理资源
+ 逻辑分隔与组织结构一致
### 资源标签
EKS ACK 功能会自动为它创建的所有 AWS 资源应用默认标签。这些标签与自主管理的 ACK 的标签不同，可提供增强的可追溯性。
**该功能应用的默认标签**：
| 标签密钥 | 说明 |
| --- | --- |
| `eks:controller-version` | ACK 控制器的版本 |
| `eks:kubernetes-namespace` | ACK 资源的 Kubernetes 命名空间 |
| `eks:kubernetes-resource-name` | Kubernetes 资源的名称 |
| `eks:kubernetes-api-group` | Kubernetes API 组（例如 `s3.services.k8s.aws`） |
| `eks:eks-capability-arn` | EKS ACK 功能的 ARN |
**注意**
自主管理的 ACK 使用不同的默认标签：`services.k8s.aws/controller-version` 和 `services.k8s.aws/namespace`。功能的标签使用 `eks:` 前缀，以与 EKS 的其他功能保持一致。
**其他推荐标签**：
为成本分配、所有权跟踪和整理目的添加自定义标签：
+ 环境（生产、暂存、开发）
+ 团队或部门所有权
+ 用于账单分配的成本中心
+ 应用程序或服务名称
## 从其他基础设施即代码工具迁移
许多组织发现，将 Kubernetes 标准化扩展到工作负载编排之外具有重要价值。将基础设施和 AWS 资源管理迁移到 ACK，可以让您使用 Kubernetes API 来标准化基础设施管理，并与应用程序工作负载一起管理。
**在 Kubernetes 中标准化基础设施管理的优势**：
+ **单一事实来源**：在 Kubernetes 中同时管理应用程序和基础设施，实现端到端 GitOps 实践
+ **统一工具**：团队使用 Kubernetes 资源和工具，无需学习多种工具和框架
+ **一致协调机制**：ACK 会像 Kubernetes 协调工作负载一样持续协调 AWS 资源，相比命令式工具，ACK 能检测和纠正状态偏差
+ **原生组合**：通过将 kro 与 ACK 结合，直接在应用程序和资源清单中引用 AWS 资源，在资源之间传递连接字符串和 ARN
+ **简化操作**：为整个系统提供统一的控制面板，用于实现部署、回滚和可观测性
ACK 支持在不重新创建的情况下接管现有 AWS 资源，从而实现从 CloudFormation、Terraform 或集群外部资源进行零停机时间迁移。
**接管现有资源**：
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
接管后，资源将由 ACK 管理，并且可以通过 Kubernetes 清单进行更新。您可以增量迁移，根据需要接管资源，同时为其他资源保留现有 IaC 工具。
ACK 也支持只读资源。对于由其他团队或工具管理、您希望引用但不希望修改的资源，可以将接管与 `retain` 删除策略结合使用，并授予 IAM 只读权限。这使得应用程序可以通过 Kubernetes API 发现共享基础设施（VPC、IAM 角色、KMS 密钥），而无需承担修改风险。
有关资源接管的更多信息，请参阅 [ACK 概念](ack-concepts.md)。
## 删除策略
删除策略决定了当您删除 Kubernetes 资源时，相应 AWS 资源的处置方式。根据资源生命周期和运营需求选择合适的策略。
### 删除（默认）
当您删除 Kubernetes 资源时，相应的 AWS 也将删除。这样可以保持集群与 AWS 之间的一致性，确保资源不会累积。
**何时使用删除**：
+ 开发和测试环境中的清理操作至关重要时
+ 临时资源与应用程序生命周期（测试数据库、临时存储桶）相关联时
+ 涉及不应超过应用程序生命周期的资源时（SQS 队列、ElastiCache 集群）
+ 成本优化：自动清理未使用的资源
+ 涉及通过 GitOps 管理的环境时，其中从 Git 中移除资源即应删除基础设施
默认的删除策略与 Kubernetes 的声明式模型一致：集群中存在的内容与 AWS 中存在的内容相匹配。
### 保留
删除 Kubernetes 资源时，相应的 AWS 资源将保留。这样可以保护关键数据，并使资源的存在时间超过其 Kubernetes 表示形式。
**何时使用保留**：
+ 生产数据库包含关键数据且此类数据必须在集群更改后保留时
+ 长期存储桶需符合合规性或审计要求时
+ 多个应用程序或团队使用共享资源时
+ 资源正在迁移到不同管理工具时
+ 希望保留基础设施的灾难恢复场景中
+ 涉及具有复杂依赖项、需要谨慎停用的资源时
```
apiVersion: rds.services.k8s.aws/v1alpha1
kind: DBInstance
metadata:
name: production-db
annotations:
services.k8s.aws/deletion-policy: "retain"
spec:
dbInstanceIdentifier: prod-db
# ... configuration
```
**重要**
被保留的资源将继续产生 AWS 费用，如果您不再需要这些资源，则必须手动将其从 AWS 中删除。使用资源标记来跟踪保留的资源，以便后续清理。
有关删除策略的更多信息，请参阅 [ACK 概念](ack-concepts.md)。
## 上游文档
有关使用 ACK 的详细信息，请参阅下列文档：
+ [ACK 使用指南](https://aws-controllers-k8s.github.io/community/docs/user-docs/usage/)：创建和管理资源
+ [ACK API 参考](https://aws-controllers-k8s.github.io/community/reference/)：所有服务的完整 API 文档
+ [ACK 文档](https://aws-controllers-k8s.github.io/community/docs/)：全面的用户文档
## 后续步骤
+ [配置 ACK 权限](ack-permissions.md)：配置 IAM 权限和多账户模式
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念和资源生命周期
+ [排查 ACK 功能问题](ack-troubleshooting.md)：排查 ACK 问题
+ [使用 Argo CD](working-with-argocd.md)：通过 GitOps 部署 ACK 资源
+ [kro 概念](kro-concepts.md)：将 ACK 资源组合成更高级别的抽象
# 排查 ACK 功能问题
本主题将提供针对适用于 ACK 的 EKS 功能的问题排查指南，包括功能运行状况检查、资源状态验证和 IAM 权限问题。
**注意**
EKS 功能完全托管，可在您的集群之外运行。您无权访问控制器日志或控制器命名空间。问题排查侧重于功能运行状况、资源状态和 IAM 配置。
## 功能处于活动状态，但无法创建资源
如果 ACK 功能显示为 `ACTIVE` 状态但无法在 AWS 中创建资源，请检查功能运行状况、资源状态和 IAM 权限。
**检查功能运行状况**：
您可以在 EKS 控制台或使用 AWS CLI 查看功能运行状况和状态问题。
**控制台**：
1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/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-ack
# Look for issues in the health section
```
**常见原因：**
+ **缺少 IAM 权限**：功能角色缺少 AWS 服务权限
+ **命名空间错误**：在未配置正确 IAMRoleSelector 的命名空间中创建了资源
+ **资源规范无效**：检查资源状态条件是否存在验证错误
+ **API 节流**：达到了 AWS API 速率限制
+ **准入 Webhook**：准入 Webhook 阻止了控制器修补资源状态
**检查资源状态**：
```
# Describe the resource to see conditions and events
kubectl describe bucket my-bucket -n default
# Look for status conditions
kubectl get bucket my-bucket -n default -o jsonpath='{.status.conditions}'
# View resource events
kubectl get events --field-selector involvedObject.name=my-bucket -n default
```
**验证 IAM 权限**：
```
# View the Capability Role's policies
aws iam list-attached-role-policies --role-name my-ack-capability-role
aws iam list-role-policies --role-name my-ack-capability-role
# Get specific policy details
aws iam get-role-policy --role-name my-ack-capability-role --policy-name policy-name
```
## 资源已在 AWS 中创建，但未在 Kubernetes 中显示
ACK 仅跟踪通过 Kubernetes 清单创建的资源。要使用 ACK 管理现有 AWS 资源，请使用接管功能。
```
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
name: existing-bucket
annotations:
services.k8s.aws/adoption-policy: "adopt-or-create"
spec:
name: my-existing-bucket-name
```
有关资源接管的更多信息，请参阅 [ACK 概念](ack-concepts.md)。
## 无法创建跨账户资源
如果使用 IAM 角色选择器时，无法在目标 AWS 账户中创建资源，请验证信任关系和 IAMRoleSelector 配置。
**验证信任关系**：
```
# Check the trust policy in the target account role
aws iam get-role --role-name cross-account-ack-role --query 'Role.AssumeRolePolicyDocument'
```
信任策略必须允许源账户的功能角色代入它。
**确认 IAMRoleSelector 配置**：
```
# List IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector
# Describe specific selector
kubectl describe iamroleselector my-selector
```
**验证命名空间对应关系**：
IAMRoleSelectors 是集群范围内的资源，但针对特定的命名空间。请确保 ACK 资源位于与 IAMRoleSelector 的命名空间选择器匹配的命名空间：
```
# Check resource namespace
kubectl get bucket my-cross-account-bucket -n production
# List all IAMRoleSelectors (cluster-scoped)
kubectl get iamroleselector
# Check which namespace the selector targets
kubectl get iamroleselector my-selector -o jsonpath='{.spec.namespaceSelector}'
```
**检查 IAMRoleSelected 条件**：
通过检查 `ACK.IAMRoleSelected` 条件，验证 IAMRoleSelector 是否已与资源成功匹配：
```
# Check if IAMRoleSelector was matched
kubectl get bucket my-cross-account-bucket -n production -o jsonpath='{.status.conditions[?(@.type=="ACK.IAMRoleSelected")]}'
```
如果条件为 `False` 或缺失，则说明 IAMRoleSelector 的命名空间选择器与资源所在的命名空间不匹配。验证选择器的 `namespaceSelector` 是否与资源的命名空间标签匹配。
**检查功能角色权限**：
功能角色需要目标账户角色的 `sts:AssumeRole` 和 `sts:TagSession` 权限：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["sts:AssumeRole", "sts:TagSession"],
"Resource": "arn:aws:iam::[.replaceable]`444455556666`:role/[.replaceable]`cross-account-ack-role`"
}
]
}
```
有关跨账户配置的详细信息，请参阅[配置 ACK 权限](ack-permissions.md)。
## 后续步骤
+ [针对 EKS 的 ACK 注意事项](ack-considerations.md)：ACK 注意事项和最佳实践
+ [配置 ACK 权限](ack-permissions.md)：配置 IAM 权限和多账户模式
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念和资源生命周期
+ [EKS 功能问题排查](capabilities-troubleshooting.md)：一般功能问题排查指导
# 适用于 ACK 的 EKS 功能与自主管理型 ACK 功能的比较
适用于 ACK 的 EKS 功能提供了与自主管理型 ACK 控制器相同的功能，且具备显著的运营优势。有关 EKS 功能与自主管理型解决方案的总体比较，请参阅 [EKS 功能和注意事项](capabilities-considerations.md)。本主题将重点介绍 ACK 特有的差异。
## 与上游 ACK 的区别
适用于 ACK 的 EKS 功能基于上游 ACK 控制器，但在 IAM 集成方面有所不同。
**IAM 功能角色**：该功能将使用专用 IAM 角色，其信任策略允许 `capabilities.eks.amazonaws.com` 服务主体，而不允许 IRSA（用于服务账户的 IAM 角色）。您可以将 IAM 策略直接附加到功能角色，而无需创建 Kubernetes 服务账户或为其添加注释，也无需配置 OIDC 提供者。对于生产使用案例，最佳实践是使用 `IAMRoleSelector` 来配置服务权限。有关更多信息，请参阅[配置 ACK 权限](ack-permissions.md)。
**会话标签**：托管功能会为所有 AWS API 请求自动设置会话标签，从而实现精细的访问控制和审计。标签包括 `eks:eks-capability-arn`、`eks:kubernetes-namespace` 和 `eks:kubernetes-api-group`。这与自主管理的 ACK 有所不同，后者默认不设置这些标签。有关在 IAM 策略中使用会话标签的详细信息，请参阅 [配置 ACK 权限](ack-permissions.md)。
**资源标签**：该功能为 AWS 资源应用的默认标签与自主管理的 ACK 所应用的标签不同。该功能使用 `eks:` 前缀标签（例如 `eks:kubernetes-namespace`、`eks:eks-capability-arn`），而不是自主管理的 ACK 使用的 `services.k8s.aws/` 标签。有关默认资源标签的完整列表，请参阅 [针对 EKS 的 ACK 注意事项](ack-considerations.md)。
**资源兼容性**：ACK 自定义资源的工作方式与上游 ACK 完全相同，您无需更改 ACK 资源 YAML 文件。该功能使用同一 Kubernetes API 和 CRD，因此 `kubectl` 等工具的使用方式将保持不变。支持上游 ACK 中所有已正式发布的控制器和资源。
有关完整的 ACK 文档及针对具体服务的指南，请参阅 [ACK 文档](https://aws-controllers-k8s.github.io/community/)。
## 迁移路径
您可以从自主管理型 ACK 迁移到托管功能，且停机时间为零：
1. 更新自主管理型 ACK 控制器，使其使用 `kube-system` 实现主节点选举租约，例如：
```
helm upgrade --install ack-s3-controller \
oci://public.ecr.aws/aws-controllers-k8s/s3-chart \
--namespace ack-system \
--set leaderElection.namespace=kube-system
```
这会将控制器的租约移至 `kube-system`，从而允许托管功能与其协调。
1. 在集群上创建 ACK 功能（请参阅[创建 ACK 功能](create-ack-capability.md)）
1. 托管功能可识别出由 ACK 托管的 AWS 现有资源，并接管协调工作
1. 逐步缩减或移除自主管理型控制器部署：
```
helm uninstall ack-s3-controller --namespace ack-system
```
此方法允许两个控制器在迁移期间安全共存。托管功能会自动接管先前由自主管理型控制器托管的资源，确保持续协调且不发生冲突。
## 后续步骤
+ [创建 ACK 功能](create-ack-capability.md)：创建 ACK 功能资源
+ [ACK 概念](ack-concepts.md)：了解 ACK 概念和资源生命周期
+ [配置 ACK 权限](ack-permissions.md)：配置 IAM 和权限
# 使用 Argo CD 持续部署
Argo CD 是一款适用于 Kubernetes 的声明式 GitOps 持续交付工具。借助 Argo CD，您可以跨多个集群和环境自动部署应用程序并管理其生命周期。Argo CD 支持多种来源类型，包括 Git 存储库、Helm 注册表（HTTP 和 OCI）和 OCI 映像，为具有不同安全和合规要求的组织提供了灵活性。
得益于 EKS 功能，Argo CD 完全由 AWS 托管，无需您在集群上安装、维护和扩展 Argo CD 控制器及其依赖项。
## Argo CD 的工作原理
Argo CD 遵循 GitOps 模式，其中您的应用程序源（Git 存储库、Helm 注册表或 OCI 映像）是用于定义所需应用程序状态的事实来源。在创建 Argo CD `Application` 资源时，需要指定包含应用程序清单的源以及目标 Kubernetes 集群和命名空间。Argo CD 持续监控集群中的源状态和实时状态，并且自动同步所有更改以确保集群状态与所需状态保持一致。
**注意**
借助适用于 Argo CD 的 EKS 功能，Argo CD 软件可在 AWS 控制面板上运行，而不是在 Worker 节点上运行。这意味着您的 Worker 节点不需要直接访问 Git 存储库或 Helm 注册表：此功能可处理来自 AWS 账户的源访问。
Argo CD 提供三种主要资源类型：
+ **Application**：定义从 Git 存储库到目标集群的部署
+ **ApplicationSet**：根据用于多集群部署的模板生成多个应用程序
+ **AppProject**：为应用程序提供逻辑分组和访问权限控制
**示例：创建 Argo CD 应用程序**
以下示例说明了如何创建 Argo CD `Application` 资源：
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
name: in-cluster
namespace: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
```
**注意**
将 `destination.name` 用于您注册集群时使用的集群名称（如适用于本地集群的 `in-cluster`）。`destination.server` 字段也适用于 EKS 集群 ARN，但为了提高可读性，建议使用集群名称。
## Argo CD 的优势
Argo CD 实施 GitOps 工作流程，在该工作流程中，您可以在 Git 存储库中定义应用程序配置，然后 Argo CD 会自动同步您的应用程序，以便与预期状态保持一致。这种以 Git 为中心的方法可提供对所有更改的完整审计跟踪记录，实现轻松回滚，并且可以自然地与您现有的代码审查和批准流程集成。Argo CD 会自动检测和协调 Git 中所需状态与集群中实际状态之间的偏差，确保您的部署与声明的配置保持一致。
借助 Argo CD，您可以从单个 Argo CD 实例跨多个集群部署和管理应用程序，从而简化多集群和多区域环境中的操作。Argo CD 用户界面提供可视化和监控功能，允许您查看应用程序的部署状态、运行状况和历史记录。用户界面与 AWS Identity Center（原 AWS SSO）集成，可实现无缝身份验证和授权，使您能够使用现有的身份管理基础设施控制访问权限。
作为 EKS 托管功能的一部分，Argo CD 完全由 AWS 管理，无需安装、配置和维护 Argo CD 基础设施。AWS 负责扩展、修补和操作管理，让您的团队能够专注于应用程序交付而不是工具维护。
## 与 AWS Identity Center 集成
EKS 托管功能提供 Argo CD 与 AWS Identity Center 之间的直接集成，为您的用户提供无缝身份验证和授权。启用 Argo CD 功能后，您可以将 AWS Identity Center 集成配置为将 Identity Center 组和用户映射到 Argo CD RBAC 角色，从而控制谁可以访问和管理 Argo CD 中的应用程序。
## 与其他 EKS 托管功能集成
Argo CD 可与其他 EKS 托管功能集成。
+ **AWS Controllers for Kubernetes（ACK）**：使用 Argo CD 跨多个集群管理 ACK 资源的部署，为 AWS 基础设施启用 GitOps 工作流程。
+ **kro（Kube Resource Orchestrator）**：使用 Argo CD 在多个集群中部署 kro 组合，从而在整个 Kubernetes 资产中实现一致的资源组合。
## 开始使用 Argo CD
要开始使用适用于 Argo CD 的 EKS 功能，请执行以下操作：
1. 创建和配置 IAM 功能角色，该角色具有必要权限，能让 Argo CD 访问您的源和管理应用程序。
1. 通过 AWS 控制台、AWS CLI 或偏好的基础设施即代码工具，在 EKS 集群上[创建 Argo CD 功能资源](create-argocd-capability.md)。
1. 配置存储库访问权限并注册集群，进行应用程序部署。
1. 创建应用程序资源，以从声明式源部署应用程序。
# 创建 Argo CD 功能
本主题旨在介绍如何在 Amazon EKS 集群上创建 Argo CD 功能。
## 先决条件
创建 Argo CD 功能之前，确保满足以下条件：
+ 运行受支持 Kubernetes 版本的现有 Amazon EKS 集群（标准支持与扩展支持范围内的所有版本均适用）
+ **AWS Identity Center 已配置**：此为 Argo CD 身份验证所需（不支持本地用户）
+ 具有 Argo CD 操作权限的 IAM 功能角色
+ 可在 EKS 集群上创建功能资源的充足 IAM 权限
+ 已配置 `kubectl` 以与集群通信
+ （可选）已安装 Argo CD CLI，以便更便捷地进行集群与存储库管理
+ （适用于 CLI/eksctl）已安装并配置相应 CLI 工具
有关如何创建 IAM 功能角色的说明，请参阅 [Amazon EKS 功能 IAM 角色](capability-role.md)。有关设置 Identity Center 的信息，请参阅 [AWS Identity Center 入门](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html)。
**重要**
您提供的 IAM 功能角色，将决定 Argo CD 可以访问的 AWS 资源范围。这包括通过 CodeConnections 访问 Git 存储库，以及访问 Secrets Manager 中的密钥。有关创建具备最低权限的合适角色的操作指引，请参阅 [Amazon EKS 功能 IAM 角色](capability-role.md)和 [EKS 功能的安全注意事项](capabilities-security.md)。
## 选择工具
您可以使用AWS 管理控制台、AWS CLI 或 eksctl 创建 Argo CD 功能：
+ [使用控制台创建 Argo CD 功能](argocd-create-console.md)：使用控制台获得引导式体验
+ [使用 AWS CLI 创建 Argo CD 功能](argocd-create-cli.md)：使用 AWS CLI 进行脚本编写和自动化
+ [使用 eksctl 创建 Argo CD 功能](argocd-create-eksctl.md)：使用 eksctl 获得 Kubernetes 原生体验
## 创建 Argo CD 功能时会执行的操作
创建 Argo CD 功能时：
1. EKS 在 AWS 控制面板中创建 Argo CD 功能服务
1. 自定义资源定义（CRD）将被安装到集群中
1. 系统会自动为您的 IAM 功能角色创建一个访问条目，该条目带有特定于功能的访问条目策略，这些策略会授予基本的 Kubernetes 权限（请参阅 [EKS 功能的安全注意事项](capabilities-security.md)）
1. Argo CD 开始监视其自定义资源（应用程序、ApplicationSets、AppProjects）
1. 功能状态从 `CREATING` 更改为 `ACTIVE`
1. 可通过对应的 URL 访问 Argo CD UI
功能进入运行状态后，即可在集群中创建 Argo CD 应用程序，以通过声明式源完成部署操作。
**注意**
自动创建的访问条目不会授予将应用程序部署到集群的权限。要部署应用程序，您必须为每个目标集群配置额外的 Kubernetes RBAC 权限。有关注册集群和配置访问权限的详细信息，请参阅 [注册目标集群](argocd-register-clusters.md)。
## 后续步骤
创建 Argo CD 功能后：
+ [Argo CD 概念](argocd-concepts.md)：了解 GitOps 原则、同步策略及多集群模式
+ [使用 Argo CD](working-with-argocd.md)：配置存储库访问权限、注册目标集群及创建应用程序
+ [Argo CD 注意事项](argocd-considerations.md)：探索多集群架构模式及高级配置
# 使用控制台创建 Argo CD 功能
本主题将介绍如何使用 AWS 管理控制台创建 Argo CD 功能。
## 先决条件
+ **已配置 AWS Identity Center**：Argo CD 需要使用 AWS Identity Center 进行身份验证。不支持本地用户。如果您尚未设置 AWS Identity Center，请参阅[开始使用 AWS Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) 以创建 Identity Center 实例，并参阅[添加用户](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html)和[添加组](https://docs.aws.amazon.com/singlesignon/latest/userguide/addgroups.html)以创建用于访问 Argo CD 的用户和组。
## 创建 Argo CD 功能
1. 从以下位置打开 Amazon EKS 控制台：https://console.aws.amazon.com/eks/home\$1/clusters。
1. 选择集群名称，打开集群详细信息页面。
1. 选择**功能**选项卡。
1. 在左侧导航栏中，选择 **Argo CD**。
1. 选择**创建 Argo CD 功能**。
1. 对于 **IAM 功能角色**：
+ 如果已有 IAM 功能角色，请从下拉列表中选择该角色
+ 如需创建角色，请选择**创建 Argo CD 角色**
此操作会在新选项卡中打开 IAM 控制台，其中包含预填充的信任策略和 Secrets Manager 的完全读取权限。默认情况下不会添加其他权限，但您可以根据需要自行添加。如果计划使用 CodeCommit 存储库或其他 AWS 服务，请在创建角色之前添加相应的权限。
创建角色后，返回 EKS 控制台，系统将自动选择该角色。
**注意**
如果计划使用与 AWS Secrets Manager 或 AWS CodeConnections 的可选集成，则需要向该角色添加权限。有关 IAM 策略示例和配置指南，请参阅[使用 AWS Secrets Manager 管理应用程序密钥](integration-secrets-manager.md)和[使用 AWS CodeConnections 连接到 Git 存储库](integration-codeconnections.md)。
1. 配置 AWS Identity Center 集成：
1. 选择**启用 AWS Identity Center 集成**。
1. 从下拉列表中选择 Identity Center 实例。
1. 通过将用户或组分配给 Argo CD 角色（ADMIN、EDITOR 或 VIEWER）来配置 RBAC 的角色映射
1. 选择**创建**。
功能创建过程随即开始。
## 验证功能是否处于活动状态
1. 在**功能**选项卡上，查看 Argo CD 功能状态。
1. 等待状态从 `CREATING` 更改为 `ACTIVE`。
1. 变为活动状态后，该功能即可使用。
有关功能状态和问题排查的信息，请参阅[使用功能资源](working-with-capabilities.md)。
## 访问 Argo CD 用户界面
待该功能处于活动状态后，可以访问 Argo CD 用户界面：
1. 在 Argo CD 功能页面上，选择**打开 Argo CD 用户界面**。
1. Argo CD 用户界面将在新的浏览器选项卡中打开。
1. 现在，您可以通过用户界面创建应用程序和管理部署。
## 后续步骤
+ [使用 Argo CD](working-with-argocd.md)：配置存储库、注册集群和创建应用程序
+ [Argo CD 注意事项](argocd-considerations.md)：多集群架构和高级配置
+ [使用功能资源](working-with-capabilities.md)：管理 Argo CD 功能资源
# 使用 AWS CLI 创建 Argo CD 功能
本主题将介绍如何使用 AWS CLI 创建 Argo CD 功能。
## 先决条件
+ **AWS CLI**：版本 `2.12.3` 或更高版本。要检查版本，请运行 `aws --version`。有关更多信息，请参阅《AWS 命令行界面用户指南》中的[安装](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)。
+ **`kubectl`**：用于与 Kubernetes 集群结合使用的命令行工具。有关更多信息，请参阅 [设置 `kubectl` 和 `eksctl`](install-kubectl.md)。
+ **已配置 AWS Identity Center**：Argo CD 需要使用 AWS Identity Center 进行身份验证。不支持本地用户。如果您尚未设置 AWS Identity Center，请参阅[开始使用 AWS Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/getting-started.html) 以创建 Identity Center 实例，并参阅[添加用户](https://docs.aws.amazon.com/singlesignon/latest/userguide/addusers.html)和[添加组](https://docs.aws.amazon.com/singlesignon/latest/userguide/addgroups.html)以创建用于访问 Argo CD 的用户和组。
## 步骤 1：创建 IAM 功能角色
创建信任策略文件：
```
cat > argocd-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
创建 IAM 角色：
```
aws iam create-role \
--role-name ArgoCDCapabilityRole \
--assume-role-policy-document file://argocd-trust-policy.json
```
**注意**
如果计划使用与 AWS Secrets Manager 或 AWS CodeConnections 的可选集成，则需要向该角色添加权限。有关 IAM 策略示例和配置指南，请参阅[使用 AWS Secrets Manager 管理应用程序密钥](integration-secrets-manager.md)和[使用 AWS CodeConnections 连接到 Git 存储库](integration-codeconnections.md)。
## 步骤 2：创建 Argo CD 功能
在集群上创建 Argo CD 功能资源。
首先，为 Identity Center 配置设置环境变量：
```
# Get your Identity Center instance ARN (replace region if your IDC instance is in a different region)
export IDC_INSTANCE_ARN=$(aws sso-admin list-instances --region [.replaceable]`region` --query 'Instances[0].InstanceArn' --output text)
# Get a user ID for RBAC mapping (replace with your username and region if needed)
export IDC_USER_ID=$(aws identitystore list-users \
--region [.replaceable]`region` \
--identity-store-id $(aws sso-admin list-instances --region [.replaceable]`region` --query 'Instances[0].IdentityStoreId' --output text) \
--query 'Users[?UserName==`your-username`].UserId' --output text)
echo "IDC_INSTANCE_ARN=$IDC_INSTANCE_ARN"
echo "IDC_USER_ID=$IDC_USER_ID"
```
创建集成了 Identity Center 的功能。将 *region-code* 替换为您的集群所在的 AWS 区域，将 *my-cluster* 替换为您的集群名称，将 *idc-region-code* 替换为您配置 IAM Identity Center 所在的区域代码：
```
aws eks create-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd \
--type ARGOCD \
--role-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):role/ArgoCDCapabilityRole \
--delete-propagation-policy RETAIN \
--configuration '{
"argoCd": {
"awsIdc": {
"idcInstanceArn": "'$IDC_INSTANCE_ARN'",
"idcRegion": "'[.replaceable]`idc-region-code`'"
},
"rbacRoleMappings": [{
"role": "ADMIN",
"identities": [{
"id": "'$IDC_USER_ID'",
"type": "SSO_USER"
}]
}]
}
}'
```
命令会立即返回，但是由于 EKS 正在创建所需的功能基础设施和组件，该功能需要一些时间才能变为活动状态。在创建集群时，EKS 将在集群中安装与此功能相关的 Kubernetes 自定义资源定义。
**注意**
如果收到集群不存在或您没有权限的错误消息，请验证：
集群名称是否正确
AWS CLI 是否针对正确的区域进行配置
您是否拥有所需的 IAM 权限
## 步骤 3：验证功能是否处于活动状态
等待功能变为活动状态。将 *region-code* 替换为集群所在的 AWS 区域，并将 *my-cluster* 替换为集群名称。
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd \
--query 'capability.status' \
--output text
```
当状态显示为 `ACTIVE` 时，表示功能已准备就绪。在该状态变为 `ACTIVE` 之前，请勿继续执行下一步。
您也可以查看完整功能详细信息：
```
aws eks describe-capability \
--region region-code \
--cluster-name my-cluster \
--capability-name my-argocd
```
## 步骤 4：验证自定义资源是否可用
待该功能处于活动状态后，验证 Argo CD 自定义资源是否已在集群中正常可用：
```
kubectl api-resources | grep argoproj.io
```
您应该会看到列出的 `Application` 和 `ApplicationSet` 资源类型。
## 后续步骤
+ [使用 Argo CD](working-with-argocd.md)：配置存储库、注册集群和创建应用程序
+ [Argo CD 注意事项](argocd-considerations.md)：多集群架构和高级配置
+ [使用功能资源](working-with-capabilities.md)：管理 Argo CD 功能资源
# 使用 eksctl 创建 Argo CD 功能
本主题将介绍如何使用 eksctl 创建 Argo CD 功能。
**注意**
以下步骤需要 eksctl 版本 `0.220.0` 或更高版本。要检查版本，请运行 `eksctl version`。
## 步骤 1：创建 IAM 功能角色
创建信任策略文件：
```
cat > argocd-trust-policy.json << 'EOF'
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "capabilities.eks.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:TagSession"
]
}
]
}
EOF
```
创建 IAM 角色：
```
aws iam create-role \
--role-name ArgoCDCapabilityRole \
--assume-role-policy-document file://argocd-trust-policy.json
```
**注意**
对于此基本设置，无需其他 IAM 策略。如果计划使用 Secrets Manager 管理存储库凭证或使用 CodeConnections，则需为此角色添加相应权限。有关 IAM 策略示例和配置指南，请参阅[使用 AWS Secrets Manager 管理应用程序密钥](integration-secrets-manager.md)和[使用 AWS CodeConnections 连接到 Git 存储库](integration-codeconnections.md)。
## 步骤 2：获取 AWS Identity Center 配置
获取 Identity Center 实例 ARN 和用户 ID，用于 RBAC 配置：
```
# Get your Identity Center instance ARN
aws sso-admin list-instances --query 'Instances[0].InstanceArn' --output text
# Get a user ID for admin access (replace 'your-username' with your Identity Center username)
aws identitystore list-users \
--identity-store-id $(aws sso-admin list-instances --query 'Instances[0].IdentityStoreId' --output text) \
--query 'Users[?UserName==`your-username`].UserId' --output text
```
记下这些值，下一步将会用到。
## 步骤 3：创建 eksctl 配置文件
使用以下内容创建名为 `argocd-capability.yaml` 的文件。将占位符值替换为集群名称、集群区域、IAM 角色 ARN、Identity Center 实例 ARN、Identity Center 区域和用户 ID：
```
apiVersion: eksctl.io/v1alpha5
kind: ClusterConfig
metadata:
name: my-cluster
region: cluster-region-code
capabilities:
- name: my-argocd
type: ARGOCD
roleArn: arn:aws:iam::[.replaceable]111122223333:role/ArgoCDCapabilityRole
deletePropagationPolicy: RETAIN
configuration:
argocd:
awsIdc:
idcInstanceArn: arn:aws:sso:::instance/ssoins-123abc
idcRegion: idc-region-code
rbacRoleMappings:
- role: ADMIN
identities:
- id: 38414300-1041-708a-01af-5422d6091e34
type: SSO_USER
```
**注意**
您可以向 RBAC 映射添加多个用户或组。对于组，请使用 `type: SSO_GROUP` 并提供组 ID。可用角色包括 `ADMIN`、`EDITOR` 和 `VIEWER`。
## 步骤 4：创建 Argo CD 功能
应用配置文件：
```
eksctl create capability -f argocd-capability.yaml
```
命令会立即返回，但该功能需要一些时间才能变为活动状态。
## 步骤 5：验证功能是否处于活动状态
检查功能状态。将 *region-code* 替换为您的集群所在的 AWS 区域，并将 *my-cluster* 替换为您的集群的名称。
```
eksctl get capability \
--region region-code \
--cluster my-cluster \
--name my-argocd
```
当状态显示为 `ACTIVE` 时，表示功能已准备就绪。
## 步骤 6：验证自定义资源是否可用
待该功能处于活动状态后，验证 Argo CD 自定义资源是否已在集群中正常可用：
```
kubectl api-resources | grep argoproj.io
```
您应该会看到列出的 `Application` 和 `ApplicationSet` 资源类型。
## 后续步骤
+ [使用 Argo CD](working-with-argocd.md)：了解如何创建和管理 Argo CD 应用程序
+ [Argo CD 注意事项](argocd-considerations.md)：配置 SSO 和多集群访问权限
+ [使用功能资源](working-with-capabilities.md)：管理 Argo CD 功能资源
# Argo CD 概念
Argo CD 通过将 Git 视为应用程序部署的单一事实来源，实现了 GitOps。本主题将介绍一个实际示例，然后解释使用适用于 Argo CD 的 EKS 功能时需要了解的核心概念。
## 开始使用 Argo CD
创建 Argo CD 功能（请参阅[创建 Argo CD 功能](create-argocd-capability.md)）后，即可开始部署应用程序。本示例将演示如何注册集群和创建应用程序。
### 步骤 1：设置
**注册集群**（必需）
注册要在其中部署应用程序的集群。在本示例中，我们将注册运行 Argo CD 所在的同一集群（可以使用 `in-cluster` 作为名称，以便与大多数 Argo CD 示例兼容）：
```
# Get your cluster ARN
CLUSTER_ARN=$(aws eks describe-cluster \
--name my-cluster \
--query 'cluster.arn' \
--output text)
# Register the cluster using Argo CD CLI
argocd cluster add $CLUSTER_ARN \
--aws-cluster-name $CLUSTER_ARN \
--name in-cluster \
--project default
```
**注意**
有关配置 Argo CD CLI 以使其与 EKS 中的 Argo CD 功能结合使用的信息，请参阅[将 Argo CD CLI 与托管功能结合使用](argocd-comparison.md#argocd-cli-configuration)。
或者，您也可以使用 Kubernetes Secret 注册集群（有关详细信息，请参阅[注册目标集群](argocd-register-clusters.md)）。
**配置存储库访问权限**（可选）
此示例使用公有 GitHub 存储库，因此无需配置存储库。对于私有存储库，可使用 AWS Secrets Manager、CodeConnection 或 Kubernetes Secret 配置访问权限（有关详细信息，请参阅[配置存储库访问权限](argocd-configure-repositories.md)）。
对于 AWS 服务（用于 Helm 图表的 ECR、CodeConnections 和 CodeCommit），您可以直接在 Application 资源中引用它们，而无需创建存储库。功能角色必须具有必要的 IAM 权限。有关详细信息，请参阅 [配置存储库访问权限](argocd-configure-repositories.md)。
### 步骤 2：创建应用程序
在 `my-app.yaml` 中创建以下应用程序清单：
```
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: guestbook
namespace: argocd
spec:
project: default
source:
repoURL: https://github.com/argoproj/argocd-example-apps.git
targetRevision: HEAD
path: guestbook
destination:
name: in-cluster
namespace: guestbook
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
```
应用应用程序：
```
kubectl apply -f my-app.yaml
```
应用此应用程序后，Argo CD 会执行以下操作：1. 将应用程序从 Git 同步到集群（初始部署）2. 监控 Git 存储库中的更改 3. 自动将后续更改同步到集群 4. 检测并纠正任何与预期状态的偏差 5. 在用户界面中提供运行状况状态和同步历史记录
查看应用程序状态：
```
kubectl get application guestbook -n argocd
```
您也可以使用 Argo CD CLI 或 Argo CD 用户界面（可通过 EKS 控制台中集群的“功能”选项卡访问）查看应用程序。
**注意**
使用具有托管功能的 Argo CD CLI 时，请使用命名空间前缀指定应用程序：`argocd app get argocd/guestbook`。
**注意**
在 `destination.name` 中使用集群名称（注册集群时使用的名称）。托管功能不支持本地的集群内默认值 (`kubernetes.default.svc`)。
## 核心概念
### GitOps 原则和源类型
Argo CD 实现了 GitOps，应用程序源是部署的单一事实来源：
+ **声明式**：使用 YAML 清单、Helm 图表或 Kustomize 叠加层声明预期状态
+ **版本控制**：每次更改都有完整的审计跟踪记录
+ **自动化**：Argo CD 持续监控源并自动同步更改
+ **自我修复**：检测并纠正预期状态与集群实际状态之间的偏差
**支持的源类型**：
+ **Git 存储库**：GitHub、GitLab、Bitbucket、CodeCommit（HTTPS、SSH 或 CodeConnections）
+ **Helm 注册表**：HTTP 注册表（如 `https://aws.github.io/eks-charts`）和 OCI 注册表（如 `public.ecr.aws`）
+ **OCI 映像**：包含清单或 Helm 图表的容器映像（如 `oci://registry-1.docker.io/user/my-app`）
得益于这种灵活性，组织能够选择符合其安全性和合规性要求的源。例如，限制集群访问 Git 的组织可以使用 ECR 存放 Helm 图表或 OCI 映像。
有关更多信息，请参阅 Argo CD 文档中的 [Application Sources](https://argo-cd.readthedocs.io/en/stable/user-guide/application-sources/)。
### 同步与协调
Argo CD 会持续监控源和集群，以检测并纠正偏差：
1. 轮询源以查找变更（默认：每 6 分钟一次）
1. 将预期状态与集群实际状态进行比较
1. 将应用程序标记为 `Synced` 或 `OutOfSync`
1. 自动同步更改（如果已配置）或等待手动审批
1. 同步后监控资源运行状况
**同步波次**使用注释控制资源创建顺序：
```
metadata:
annotations:
argocd.argoproj.io/sync-wave: "0" # Default if not specified
```
按波次顺序应用资源（数字小的先执行，例如 `-1` 等负数）。如果未指定，则默认为波次 `0`。这样您就可以先创建命名空间（波次 `-1`）等依赖项，再创建部署（波次 `0`），再创建服务（波次 `1`）。
**自我修复**会自动还原手动更改：
```
spec:
syncPolicy:
automated:
selfHeal: true
```
**注意**
托管功能使用基于注释的资源跟踪（而不是基于标签），以便更好地兼容 Kubernetes 规范和其他工具。
有关同步阶段、钩子和高级模式的详细信息，请参阅 [Argo CD 同步文档](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/)。
### 应用程序运行状况
Argo CD 会监控应用程序中所有资源的运行状况：
**运行状况**：\$1 **良好**：所有资源均按预期运行 \$1 **正在处理**：正在创建或更新资源 \$1 **已降级**：部分资源运行状况不佳 [容器组（pod）崩溃、任务失败] \$1 **已暂停**：应用程序故意暂停 \$1 **缺失**：集群中缺少 Git 中定义的资源
Argo CD 内置有针对常见 Kubernetes 资源（Deployment、StatefulSets、Jobs 等）的运行状况检查，并且支持对 CRD 进行自定义运行状况检查。
应用程序运行状况由所有资源决定，如果任何资源为 `Degraded`，则应用程序为 `Degraded`。
有关更多信息，请参阅 Argo CD 文档中的 [Resource Health](https://argo-cd.readthedocs.io/en/stable/operator-manual/health/)。
### 多集群模式
Argo CD 支持两种主要的部署模式：
**轴辐式**：在专用的管理集群（部署到多个工作负载集群）上运行 Argo CD：\$1 集中控制和可见性 \$1 在所有集群之间保持策略一致 \$1 只需一个 Argo CD 实例即可进行管理 \$1 实行控制面板与工作负载之间的清晰分离
**单集群**：在每个集群上运行 Argo CD，仅管理该集群的应用程序：\$1 集群分离（一个故障不会影响其他集群）\$1 联网更简单（无需跨集群通信）\$1 初始设置更轻松（无需注册集群）
对于管理许多集群的平台团队，选择轴辐式；对于独立的团队或必须完全隔离的集群，选择单集群。
有关多集群配置的详细信息，请参阅 [Argo CD 注意事项](argocd-considerations.md)。
### Projects
项目为应用程序提供逻辑分组和访问权限控制：
+ **源限制**：限制可以使用哪些 Git 存储库
+ **目标限制**：限制可以指向哪些集群和命名空间
+ **资源限制**：限制可以部署哪些 Kubernetes 资源类型
+ **RBAC 集成**：将项目映射到 AWS Identity Center 的用户和组 ID
应用程序同属一个项目。如果未指定，它们将使用 `default` 项目（默认没有任何限制）。对于生产用途，请编辑 `default` 项目以限制访问权限，并创建具有适当限制的新项目。
有关项目配置和 RBAC 模式，请参阅[配置 Argo CD 权限](argocd-permissions.md)。
### 同步选项
使用常用选项微调同步行为：
+ `CreateNamespace=true`：自动创建目标命名空间
+ `ServerSideApply=true`：使用服务器端应用程序以更好地解决冲突
+ `SkipDryRunOnMissingResource=true`：当 CRD 尚不存在时跳过试运行（对 kro 实例非常有用）
```
spec:
syncPolicy:
syncOptions:
- CreateNamespace=true
- ServerSideApply=true
- SkipDryRunOnMissingResource=true
```
有关完整的同步选项列表，请参阅 [Argo CD 同步选项文档](https://argo-cd.readthedocs.io/en/stable/user-guide/sync-options/)。
## 后续步骤
+ [配置存储库访问权限](argocd-configure-repositories.md)：配置 Git 存储库访问权限
+ [注册目标集群](argocd-register-clusters.md)：注册用于部署的目标集群
+ [创建应用程序](argocd-create-application.md)：创建第一个应用程序
+ [Argo CD 注意事项](argocd-considerations.md)：EKS 特定模式、Identity Center 集成和多集群配置
+ [Argo CD 文档](https://argo-cd.readthedocs.io/en/stable/)：全面的 Argo CD 文档，包括同步钩子、运行状况检查和高级模式
# 配置 Argo CD 权限
Argo CD 托管功能与 AWS Identity Center 集成以进行身份验证，并使用内置的 RBAC 角色进行授权。本主题将介绍如何为用户和团队配置权限。
## Argo CD 权限的工作原理
Argo CD 功能通过 AWS 进行身份验证，并提供三个内置的 RBAC 角色进行授权。
当用户访问 Argo CD 时：
1. 他们使用 AWS Identity Center（可以与企业身份提供者联合）进行身份验证
1. AWS Identity Center 向 Argo CD 提供用户和组信息
1. Argo CD 会根据配置将用户和组映射到 RBAC 角色
1. 用户只能看到他们有权访问的应用程序和资源
## 内置 RBAC 角色
Argo CD 功能提供三个内置角色，您需要将其映射到 AWS Identity Center 的用户和组。这些角色是**全局范围的角色**，用于控制对项目、集群和存储库等 Argo CD 资源的访问权限。
**重要**
全局角色控制对 Argo CD 本身的访问权限，而非对应用程序这类项目范围内的资源的访问权限。默认情况下，EDITOR 和 VIEWER 用户无法查看或管理应用程序，他们需要项目角色才能访问项目范围内的资源。有关授予对应用程序和其他项目范围内资源的访问权限的详细信息，请参阅 [项目角色和项目范围内的访问权限](#project-roles)。
**ADMIN**
对所有 Argo CD 资源和设置的完全访问权限：
+ 创建、更新和删除任何项目中的应用程序和 ApplicationSets
+ 管理 Argo CD 配置
+ 注册和管理部署目标集群
+ 配置存储库访问权限
+ 创建和管理项目
+ 查看所有应用程序状态和历史记录
+ 列出并访问所有集群和存储库
**EDITOR**
可以更新项目和配置项目角色，但无法更改全局的 Argo CD 设置：
+ 更新现有项目（无法创建或删除项目）
+ 配置项目角色和权限
+ 查看 GPG 密钥和证书
+ 无法更改全局的 Argo CD 配置
+ 无法直接管理集群或存储库
+ 若没有项目角色，则无法查看或管理应用程序
**VIEWER**
对 Argo CD 资源的只读访问权限：
+ 查看项目配置
+ 列出所有项目（包括该用户未被分配到的项目）
+ 查看 GPG 密钥和证书
+ 无法列出集群或存储库
+ 无法进行任何更改
+ 若没有项目角色，则无法查看或管理应用程序
**注意**
要授予 EDITOR 或 VIEWER 用户访问应用程序的权限，ADMIN 或 EDITOR 必须创建项目角色，将 Identity Center 组映射到项目中的特定权限。
## 项目角色和项目范围内的访问权限
全局角色（ADMIN、EDITOR、VIEWER）将控制对 Argo CD 本身的访问。项目角色控制对特定项目内的资源和功能的访问权限，包括：
+ **资源**：应用程序、ApplicationSets、存储库凭证、集群凭证
+ **功能**：日志访问、对应用程序容器组（pod）的 exec 访问权限
**了解两级权限模型**：
+ **全局范围**：内置角色决定了用户能够对项目、集群、存储库以及 Argo CD 设置进行何种操作
+ **项目范围**：项目角色决定了用户能够对特定项目中的资源和功能进行何种操作
这意味着：
+ ADMIN 用户无需额外配置即可访问所有的项目资源和功能
+ 必须向 EDITOR 和 VIEWER 用户授予项目角色，才能访问项目资源和功能
+ EDITOR 用户可以创建项目角色，以便在他们能够更新的项目中为自己及他人授予访问权限
**工作流示例**：
1. ADMIN 将 Identity Center 组全局映射到 EDITOR 角色
1. ADMIN 为团队创建项目
1. EDITOR 在该项目中配置项目角色，以授予团队成员访问项目范围内资源的权限
1. 团队成员（可能拥有 VIEWER 全局角色）现在可以根据其项目角色权限查看并管理该项目中的应用程序
有关配置项目角色的详细信息，请参阅 [基于项目的访问控制](#_project_based_access_control)。
## 配置角色映射
创建或更新功能时，将 AWS Identity Center 用户和组映射到 Argo CD 角色。
**示例角色映射**：
```
{
"rbacRoleMapping": {
"ADMIN": ["AdminGroup", "alice@example.com"],
"EDITOR": ["DeveloperGroup", "DevOpsTeam"],
"VIEWER": ["ReadOnlyGroup", "bob@example.com"]
}
}
```
**注意**
角色名称区分大小写，必须为大写（ADMIN、EDITOR、VIEWER）。
**重要**
EKS 功能与 AWS Identity Center 集成后，每个 Argo CD 功能可支持最多 1000 个身份。身份可以是用户或组。
**更新角色映射**：
```
aws eks update-capability \
--region us-east-1 \
--cluster-name cluster \
--capability-name capname \
--endpoint "https://eks.ap-northeast-2.amazonaws.com" \
--role-arn "arn:aws:iam::[.replaceable]111122223333:role/[.replaceable]`EKSCapabilityRole`" \
--configuration '{
"argoCd": {
"rbacRoleMappings": {
"addOrUpdateRoleMappings": [
{
"role": "ADMIN",
"identities": [
{ "id": "686103e0-f051-7068-b225-e6392b959d9e", "type": "SSO_USER" }
]
}
]
}
}
}'
```
## 使用管理员账户
管理员账户专为初始设置和管理任务（例如注册集群和配置存储库）而设计。
**何时适合使用管理员账户**：
+ 初始功能设置和配置
+ 单人开发或快速演示
+ 管理任务（注册集群、配置存储库、创建项目）
**管理员账户最佳实践**：
+ 请勿将账户令牌提交给版本控制
+ 如果令牌暴露，则立即轮换
+ 将账户令牌的使用限制在设置和管理任务
+ 设置较短的过期时间（最长 12 小时）
+ 在任何给定时间只能创建 5 个账户令牌
**何时改用基于项目的访问**：
+ 与多个用户共享的开发环境
+ 任何与生产环境相似的环境
+ 需要有关操作执行者的审计跟踪记录时
+ 需要强制实施资源限制或访问边界时
对于生产环境和多用户场景，请使用基于项目的访问控制，并将专用 RBAC 角色映射到 AWS Identity Center 组。
## 基于项目的访问控制
使用 Argo CD 项目（AppProject）为团队提供精细的访问控制和资源隔离。
**重要**
在为用户或用户组分配项目特定角色之前，您必须首先在功能配置中将他们映射到全局的 Argo CD 角色（ADMIN、EDITOR 或 VIEWER）。如果没有全局角色映射，用户将无法访问 Argo CD，即使他们被分配了项目角色也是如此。
考虑将用户全局映射到 VIEWER 角色，然后通过特定于项目的角色授予其他权限。这既提供了基础的访问权限，又能在项目层面实现精细的控制。
项目提供以下功能：
+ **源限制**：限制可以使用哪些 Git 存储库
+ **目标限制**：限制可以指向哪些集群和命名空间
+ **资源限制**：限制可以部署哪些 Kubernetes 资源类型
+ **RBAC 集成**：将项目映射到 AWS Identity Center 组或 Argo CD 角色
**团队隔离示例项目**：
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
description: Team A applications
# Required: Specify which namespaces this project watches for Applications
sourceNamespaces:
- argocd
# Source restrictions
sourceRepos:
- https://github.com/myorg/team-a-apps
# Destination restrictions
destinations:
- namespace: team-a-*
server: arn:aws:eks:us-west-2:111122223333:cluster/production
# Resource restrictions
clusterResourceWhitelist:
- group: ''
kind: Namespace
namespaceResourceWhitelist:
- group: 'apps'
kind: Deployment
- group: ''
kind: Service
- group: ''
kind: ConfigMap
```
### 源命名空间
使用 EKS Argo CD 功能时，AppProject 定义中必须包含 `spec.sourceNamespaces` 字段。此字段用于指定哪个命名空间可以包含引用此项目的应用程序或 ApplicationSets。
**重要**
EKS Argo CD 功能仅支持应用程序和 ApplicationSets 的单个命名空间，即您在创建该功能时指定的命名空间（通常为 `argocd`）。这与支持多个命名空间的开源 Argo CD 不同。
**AppProject 配置**
所有 AppProjects 都必须在 `sourceNamespaces` 中包含该功能配置的命名空间：
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a-project
namespace: argocd
spec:
description: Applications for Team A
# Required: Specify the capability's configured namespace (configuration.argoCd.namespace)
sourceNamespaces:
- argocd # Must match your capability's namespace configuration
# Source repositories this project can deploy from
sourceRepos:
- 'https://github.com/my-org/team-a-*'
# Destination restrictions
destinations:
- namespace: 'team-a-*'
server: arn:aws:eks:us-west-2:111122223333:cluster/my-cluster
```
**注意**
如果您从 `sourceNamespaces` 中省略了该功能的命名空间，则该命名空间中的应用程序或 ApplicationSets 将无法引用此项目，从而导致部署失败。
**为用户分配项目**：
项目角色授予 EDITOR 和 VIEWER 用户访问项目资源（应用程序、ApplicationSets、存储库和集群凭证）和功能（日志、exec）的权限。如果没有项目角色，即便这些用户拥有全局角色访问权限，他们也无法访问这些资源。
ADMIN 用户无需项目角色即可访问所有应用程序。
**示例：向团队成员授予应用程序访问权限**
```
apiVersion: argoproj.io/v1alpha1
kind: AppProject
metadata:
name: team-a
namespace: argocd
spec:
# ... project configuration ...
sourceNamespaces:
- argocd
# Project roles grant Application-level access
roles:
- name: developer
description: Team A developers - can manage Applications
policies:
- p, proj:team-a:developer, applications, *, team-a/*, allow
- p, proj:team-a:developer, clusters, get, *, allow # See cluster names in UI
groups:
- 686103e0-f051-7068-b225-e6392b959d9e # Identity Center group ID
- name: viewer
description: Team A viewers - read-only Application access
policies:
- p, proj:team-a:viewer, applications, get, team-a/*, allow
- p, proj:team-a:viewer, clusters, get, *, allow # See cluster names in UI
groups:
- 786203e0-f051-7068-b225-e6392b959d9f # Identity Center group ID
```
**注意**
在项目角色中包含 `clusters, get, *, allow` 以允许用户在用户界面中查看集群名称。如果没有此权限，则目标集群将显示为“未知”。
**了解项目角色策略**：
策略格式为：`p, proj::, , ,