**帮助改进此页面** 要帮助改进本用户指南，请选择位于每个页面右侧窗格中的**在 GitHub 上编辑此页面**链接。 # 通过 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 和权限