开始使用 ACK 资源生命周期与协调状态条件删除策略资源接管跨账户和跨区域资源错误处理和重试行为使用 kro 进行资源组合后续步骤

ACK 概念

ACK 通过 Kubernetes API 管理 Amazon 资源，方法是根据清单中定义的预期状态，持续协调 Amazon 中的实际状态。创建或更新 Kubernetes 自定义资源时，ACK 会进行必要的 Amazon API 调用来创建或修改相应的 Amazon 资源，随后持续监控其状态是否存在偏差，并更新 Kubernetes 中的资源状态以反映当前实际状态。借助此方法，您可以使用熟悉的 Kubernetes 工具和工作流程来管理基础设施，同时保持集群与 Amazon 之间的一致性。

本主题将阐释有关 ACK 如何通过 Kubernetes API 管理 Amazon 资源的基本概念。

开始使用 ACK

创建 ACK 功能后（请参阅创建 ACK 功能），即可开始在集群中使用 Kubernetes 清单管理 Amazon 资源。

例如，将以下 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

验证存储桶是否已在 Amazon 中创建：


aws s3 ls | grep my-unique-bucket-name-12345

删除 Kubernetes 资源：


kubectl delete bucket my-test-bucket

验证存储桶是否已从 Amazon 中删除：


aws s3 ls | grep my-unique-bucket-name-12345

该存储桶不应再出现在列表中，这表明 ACK 正在管理 Amazon 资源的完整生命周期。

有关 ACK 入门的更多信息，请参阅 ACK 入门。

资源生命周期与协调

ACK 使用持续的协调循环，以确保 Amazon 资源与 Kubernetes 清单中定义的预期状态保持一致。

协调的工作原理：

您创建或更新 Kubernetes 自定义资源（例如 S3 存储桶）
ACK 检测到更改，并将预期状态与 Amazon 中的实际状态进行比较
如果两者不一致，ACK 会进行 Amazon API 调用来协调差异
ACK 会更新 Kubernetes 中的资源状态以反映当前状态
该循环持续重复，通常每隔几个小时运行一次

在以下情况下会触发协调：创建新的 Kubernetes 资源、更新现有资源的 spec，或 ACK 检测到在 ACK 外部进行的手动更改导致 Amazon 中的状态存在偏差。此外，ACK 还会定期进行协调，其重新同步周期为 10 个小时。对 Kubernetes 资源进行更改会立即触发协调，而对上游 Amazon 资源更改的被动偏差检测则会在重新同步周期内发生。

当您完成上述开始使用示例后，ACK 会执行以下步骤：

检查 Amazon 中是否存在存储桶
如果不存在，则调用 s3:CreateBucket
使用存储桶 ARN 和状态更新 Kubernetes 状态
持续监控状态偏差

要了解有关 ACK 工作原理的更多信息，请参阅 ACK 协调。

状态条件

ACK 资源使用状态条件来传达其状态。理解这些条件有助于您排查问题并了解资源运行状况。

Ready：表示资源已准备就绪，可供使用（标准化的 Kubernetes 条件）。
ACK.ResourceSynced：表示资源规范与 Amazon 资源状态相匹配。
ACK.Terminal：表示发生了不可恢复的错误。
ACK.Adopted：表示资源是从现有 Amazon 资源接管而来，而非新建的。
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 条件。

删除策略

ACK 的删除策略决定了当您删除 Kubernetes 资源时，相应 Amazon 资源的处置方式。

删除（默认）

删除 Kubernetes 资源时，相应的 Amazon 资源也将删除，这是默认行为。


# No annotation needed - this is the default
apiVersion: s3.services.k8s.aws/v1alpha1
kind: Bucket
metadata:
  name: temp-bucket
spec:
  name: temporary-bucket

删除此资源将同时删除 Amazon 中的 S3 存储桶。

Retain：

删除 Kubernetes 资源时，相应的 Amazon 资源将保留：


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 中移除，但会保留 Amazon 中的 S3 存储桶。

retain 策略适用于以下场景：生产数据库的生命周期超过 Kubernetes 资源，多个应用程序使用共享资源，资源包含不应意外删除的重要数据，或者临时管理 ACK（即先接管一个资源，对其进行配置，然后将其释放回手动管理）。

要了解有关 ACK 删除策略的更多信息，请参阅 ACK 删除策略。

资源接管

通过接管，您可以将现有的 Amazon 资源纳入 ACK 管理，而无需重新创建它们。

何时使用接管：

将现有基础设施迁移到 ACK 管理
在 Kubernetes 中意外删除资源的情况下，恢复孤立的 Amazon 资源
导入由其他工具（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 会检查 Amazon 中是否存在具有该名称的存储桶
如果找到存储桶，ACK 就会接管它（无需调用 API 创建）
ACK 从 Amazon 读取当前配置
ACK 会更新 Kubernetes 状态以反映实际状态
未来的更新会正常协调该资源

接管后，资源将像任何其他 ACK 资源一样进行管理，并且删除 Kubernetes 资源时将删除相应的 Amazon 资源，除非您使用了 retain 删除策略。

接管资源时，Amazon 资源必须已存在，并且 ACK 需要读取权限才能发现它。如果资源存在，adopt-or-create 策略会接管该资源，如果资源不存在，则会创建。当您需要一个无论资源是否存在都能正常工作的声明式工作流程时，这将非常有用。

要了解有关 ACK 资源接管的更多信息，请参阅 ACK 资源接管。

跨账户和跨区域资源

ACK 可以从单个集群管理位于不同 Amazon 账户和区域的资源。

跨区域资源注释

您可以使用注释指定 Amazon 资源的区域：


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

您还可以为特定命名空间中创建的所有 Amazon 资源指定默认区域：

命名空间注释

为命名空间中的所有资源设置默认区域：


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 跨账户资源管理。有关跨账户配置的详细信息，请参阅配置 ACK 权限。

错误处理和重试行为

ACK 会自动处理瞬态错误并重试失败的操作。

重试策略：

瞬态错误（速率限制、临时服务问题、权限不足）会触发自动重试
指数回退可防止 API Amazon 负载过重
最大重试次数因错误类型而异
永久错误（参数无效、资源名称冲突）不会重试

使用 kubectl describe 检查资源状态以了解错误详情：


kubectl describe bucket my-bucket

查找包含错误消息的状态条件、显示最近协调尝试的事件，以及状态条件中说明失败原因的 message 字段。常见错误包括 IAM 权限不足、Amazon 中的资源名称冲突、spec 中的配置值无效、超出 Amazon 服务配额等。

有关如何排查常见错误，请参阅排查 ACK 功能问题。

使用 kro 进行资源组合

如需将多个 ACK 资源组合并连接在一起，请使用适用于 kro 的 EKS 功能（Kube Resource Orchestrator）。kro 提供了一种声明方式来定义资源组，通过在资源之间传递配置，来简化复杂基础设施模式的管理。

有关使用 ACK 资源创建自定义资源组合的详细示例，请参阅 kro 概念

后续步骤

针对 EKS 的 ACK 注意事项：EKS 特定模式与集成策略

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

eksctl

配置权限