View a markdown version of this page

使用 GitHub 操作在 EKS 集群中启用 Amazon EKS 自动模式 - AWS 规范指引
Summary先决条件和限制架构工具最佳实践操作说明问题排查相关资源

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

使用 GitHub 操作在 EKS 集群中启用 Amazon EKS 自动模式

Urbija Goswami 和 Anugrah Lakra，Amazon Web Services

Summary

传统上，Amazon Elastic Kubernetes Service (EKS) 集群需要通过节点组手动管理计算资源。这会给以下方面带来运营开销：

  • 容量规划和扩展决策

  • 节点配置和生命周期管理

  • 不同工作负载类型的成本优化

  • 基础设施维护和更新

Amazon EKS 自动模式可根据工作负载需求动态配置和扩展节点，从而自动管理计算资源，无需手动管理节点组。

但是，许多组织难以在其现有集群和新集群中持续启用和管理 Amazon EKS 自动模式。常见的挑战包括：

  • 从现有节点组迁移的复杂过程

  • 过渡期间服务中断的风险

  • 需要仔细规划和测试容量

  • 对特定 Amazon IAM 权限和配置的要求

  • 跨多个团队和环境的协调

此模式实现了一个GitHub 操作工作流程，可在特定 AWS 区域的 EKS 集群上启用 EKS 自动模式。在启用自动模式之前，该工作流程会创建带有时间戳的集群状态备份（集群配置、节点组、Helm 版本和自定义资源），并将其上传到 Amazon S3 存储桶。

启用自动模式后，该工作流程会耗尽并删除旧的节点组，更新集群角色权限，并清理以前的扩展组件，例如 Karpenter 和 Cluster Autoscaler。工作流程可以与现有的持续集成和连续 delivery/deployment (CI/CD) 管道集成。

先决条件和限制

先决条件

1。必填项

2。本地工具安装

3。EKS 集群要求

  • Kubernetes 版本 1.29 或更高版本

  • 端点访问配置：

    • 要么将其设置为公有端点和私有端点 

    • 或者私有子网中带有 NAT 网关的私有终端节点

  • 已启用 EKS API 和ConfigMap集群访问权限（需要允许 EKS 动态管理自动模式节点并更新 aws-auth 以在迁移期间 ConfigMap 进行正确的集群身份验证）

  • 主动节点组或托管节点池

4。IAM OIDC 配置要求

  • 用于的 IAM 角色和身份提供 GitHub 商包括：

    • GitHub OIDC 的信任政策

    • 以下各项的权限：

      • EKS 集群管理

      • S3 存储桶访问

      • IAM 角色管理

      • EC2 网络管理

  • 有关使用 Terraform 的简单设置，请参阅 iam.tf 代码。IAM 角色 (GitHubActionsEKSRole) 将在应用 Terraform 代码时创建。

限制

  • 仅支持 Kubernetes 版本 1.29 及以上版本的 EKS 集群

  • 仅支持 Karpenter 版本 1.1.0 及更高版本

  • Region-specific 实施。某些 AWS 服务并非在所有 AWS 地区都可用。有关区域可用性，请参阅按地区划分的 AWS 服务

  • 需要集群终端节点可访问性

  • 仅限于 AWS-managed 节点组

架构

目标技术堆栈

  1. GitHub 操作

  2. AWS IAM

  3. AWS EKS

  4. Amazon S3

目标架构

  1. GitHub 操作工作流程由用户从 GitHub 存储库触发。

  2. GitHub 操作工作流程扮演使用 OIDC 的 IAM 角色在 AWS 账户中进行必要的更改。它还会检查账户中是否存在 EKS Auto Node 角色，如果不存在，则会创建该角色并附加必要的策略。

  3. 需要启用自动模式的 EKS 集群当前状态的备份已上传到 S3 存储桶。

  4. 检索需要启用自动模式的集群的集群角色，如果不存在 EKS Auto Mode AmazonEKSComputePolicy AmazonEKSBlockStoragePolicy AmazonEKSLoadBalancingPolicy AmazonEKSNetworkingPolicy，则会向其添加其他权限（、、、、 AmazonEKSClusterPolicy）。此外，作为迁移前的步骤，集群的子网将使用启用 EKS 自动模式的标签进行更新。

  5. 该工作流程在 EKS 集群中启用 EKS 自动模式。

  6. 识别并删除旧的节点组。如果用户尚未向下方可选设置步骤中所述的 IAM 角色授予权限，则会跳过此选项。

  7. 如果以前存在缩放组件（Karpenter 和 Cluster Autoscaler），也会被移除。

GitHub 操作工作流程由三个主要任务组成：

  1. check-clusters：识别未启用自动模式的集群并更新 IAM 策略和子网标签。

  2. backup-and-check：在迁移之前备份群集状态。

  3. gradual-migration：启用自动模式，同时逐渐耗尽现有节点组并清理旧的扩展组件。它还会在迁移后对集群的状态进行最终验证。

注意

如果您需要节点配置备份或计划在迁移到 EKS 自动模式期间删除 nodes/node 群组，则可以将使用 terraform 代码创建的 IAM 角色添加到 aws-auth。 ConfigMap没有它，您仍然可以查看节点组配置。 

工具

AWS CLI：

AWS 命令行界面（AWS CLI）是一种开源工具，可帮助您在命令行 Shell 中通过命令与 AWS 服务进行交互。在我们的解决方案中，我们利用 AWS 服务的命令行界面在整个自动化过程中执行 EKS 集群配置更新、IAM 角色更新和查询集群状态。

亚马逊 EKS：

Amazon Elastic Kubernetes Service (Amazon EKS) 可帮助您在 AWS 上运行 Kubernetes，而无需安装或维护您自己的 Kubernetes 控制面板或节点。在这种模式下，Amazon EKS 是启用自动模式的目标服务，可在特定区域的集群之间自动进行计算配置和节点扩展。

IAM：

AWS Identity and Access Management (AWS IAM) 通过控制验证和授权使用您 AWS 资源的用户，帮助您安全地管理对您 AWS 资源的访问。在我们的解决方案中，我们使用它来管理 GitHub 操作的权限，以便通过 OIDC 联合来修改 EKS 集群配置。该解决方案还修改了集群角色权限并添加了创建 EKS 节点角色的任务，这样 EKS Auto Mode 就可以将待处理的 pod 调度到作为节点池一部分启动的新节点中。

亚马逊 S3：

Amazon Simple Storage Service（Amazon S3）是一项基于云的对象存储服务，可帮助您存储、保护和检索任意数量的数据。在我们的解决方案中，在集群中启用 EKS 自动模式之前，我们使用 S3 存储桶存储带有时间戳的集群备份，这将有助于灾难恢复。

其他工具：

GitHub 操作：

GitHub A ctions 是我们的解决方案中使用的 CI/CD 平台，用于自动执行 EKS 自动模式启用工作流程。它还通过 OIDC 提供安全的身份验证，并管理跨多个集群的管道执行。  

HashiCorp Terraform：

Terraform 是一款基础设施即代码（IaC）工具，可帮助您使用代码来预调配和管理云基础设施和资源。我们的解决方案使用 terraform 来配置 IAM 角色和策略，并添加 OIDC 提供商配置以实现安全的操作集成。 GitHub  

代码存储库

此模式的代码可通过 Actions 存储库 GitHub 在 EKS 自动模式启用中找 GitHub 到。

最佳实践

  • 安全性：

  • 可靠性：

    • 首先针对非生产集群测试工作流程。在迁移生产集群之前，请验证自动模式节点上的工作负载是否正确重新调度。 

    • 在继续启用自动模式之前，请验证 S3 备份是否成功完成并包含有效的集群配置、节点组、Helm 版本和自定义资源数据。 

    • 启用自动模式后，使用 Amazon Container Insights 监控 CloudWatch 容器调度事件和节点配置延迟，以尽早发现问题。 

  • 性能：

    • 定期查看自动模式节点池扩展模式，调整工作负载资源请求和限制，以避免过度配置或调度延迟。

  • 成本:

    • 使用环境和所有权元数据标记 EKS 集群和相关资源（IAM 角色、S3 备份存储桶、子网），以支持成本跟踪和运营可见性。有关更多信息，请参阅标记 AWS 资源文档。在迁移过程中，您可以编辑工作流程文件以添加自定义标签。 

    • 设置 AWS Cost Explorer 警报以监控启用自动模式后计算成本的变化，因为自动模式可能会更改实例类型和扩展行为。有关更多信息，请参阅使用 AWS Cost Explorer 文档分析成本。  

  • 操作：

    • 将工作流程文件和 Terraform 配置保留在版本控制中，并记录任何特定于环境的替代，例如区域、角色 ARN 或 S3 存储桶名称。   

操作说明

Task说明所需技能

配置 GitHub 存储库。

  1. 克隆并分叉 GitHub 存储库。克隆后，将工作流程文件复制到存储库 GitHub  

    git clone https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions.git
    cd sample-enable-eks-auto-mode-using-github-actions
    cp .github/workflows/enable-eks-auto-mode.yml /path/to/your/repository/.github/workflows

  2. 提交更改并将其推送到您的存储 GitHub 库

    cd <path/to/your/repository>
git add .
git commit -m "Added EKS Auto Mode configurations"
git push origin main

  3. 为存储库设置 git 密钥：

    gh auth login --web  #authenticate to your github account using web
    #create secrets
gh secret set AWS_REGION --body "us-east-1" 
    gh secret set AWS_ROLE_ARN --body "arn:aws:iam:ACCOUNT_ID:role/GitHubActionsEKSRole" 
#replace the account id with your account ID
AWS DevOps，云架构师
Task说明所需技能

设置 IAM 以进行备份和节点组删除

  1. ConfigMap 使用您的终端将角色添加到 aws-auth：

eksctl create iamidentitymapping \ --cluster $CLUSTER_NAME\ --region us-east-1 \ --arn arn:aws:iam::$ACCOUNT_ID:role/GitHubActionsEKSRole \ --group system:masters \ --username github-actions

将 $ CLUSTER_NAME 和 $AC COUNT_ ID 替换为相应的值。

  1. 对于多个集群，您可以假设对您的账户具有管理员或同等级别访问权限的角色在终端中运行以下命令：

CLUSTERS=$(aws eks list-clusters --region $AWS_REGION --query 'clusters[]' --output text)

CLUSTERS_NEEDING_AUTO_MODE=""

for cluster in $CLUSTERS; do
    
    
    AUTO_MODE=$(aws eks describe-cluster --name $cluster --region $AWS_REGION --query 'cluster.computeConfig.enabled' --output text 2>/dev/null || echo "false")
    
    if [ "$AUTO_MODE" != "True" ]; then
       
        CLUSTERS_NEEDING_AUTO_MODE="$CLUSTERS_NEEDING_AUTO_MODE $cluster"
        
        echo " Adding role access to cluster..."
        eksctl create iamidentitymapping \
          --cluster $cluster \
          --region $AWS_REGION \
          --arn $ROLE_ARN \
          --group system:masters\
          --username github-actions || echo "  ⚠️  Role mapping may already exist"
        
        echo "  ✅ Role access configured for $cluster"
done

将 $AWS_RE GION 和 $ROLE_ARN 分别替换为上面创建的 IAM 角色的特定区域和 arn。

AWS DevOps，云架构师
Task说明所需技能

触发 GitHub 操作工作流程。

当任何更改推送到功能、主分支或开发分支时，工作流程会自动触发。要通过 GitHub UI 手动触发，请执行以下操作：1. 转到 GitHub 2 的存储库。单击 “操作” 选项卡 3. 选择工作流程（自动模式管道）4. 单击 “运行工作流程” 按钮 5. 选择分支并单击 “运行工作流程”

该工作流程通过使用 AWS CLI 查询每个迁移集群的计算配置来确认已成功启用 EKS 自动模式，并以表格格式显示当前的计算设置，从而处理迁移后的验证。

AWS DevOps，云架构师
Task说明所需技能

实施多环境部署。

  • 通过利用基于分支的部署，可以使该解决方案针对特定于环境。

  • 不同的分支（主分支、开发分支、功能分支/*）通过 GitHub 密钥（AWS_REGION、、S3_BACKUP_BUCKEP_BUCKET）触发具有特定环境配置的工作流程。 AWS_ROLE_ARN

  • 这允许为每个环境设置单独的 AWS 区域、IAM 角色和集群集，同时在所有环境中保持一致的自动化逻辑。

Task说明所需技能

清理资源。

  1. 要将 IAM 角色与 aws-auth 分离 ConfigMap，请使用以下终端命令：

    eksctl delete iamidentitymapping \   --cluster $cluster \   --region $AWS_REGION \   --arn $ROLE_ARN
常规 AWS，云架构师

问题排查

问题解决方案

身份验证问题

• 验证 GitHub OIDC 提供商在 AWS IAM 中的配置是否正确

• 检查 git 机密中的 IAM 角色 ARN 是否与使用 terraform () 创建的实际角色相匹配 GitHubActionsEKSRole

• 确保 GitHub 存储库配置了必要的密钥-AWS_REGION 和。 AWS_ROLE_ARN

• 验证 AWS 区域设置与您的集群位置相匹配

权限问题

<role-arn>• 在本地测试 IAM 角色权限：bash aws sts assume-role-arn--role-session-name 测试会话 aws eks 列表集群

• 确保该角色具有 eks: UpdateClusterConfig 和 eks: DescribeCluster 权限

集群兼容性

<cluster-name>• 确认 EKS 集群正在运行 Kubernetes 1.29 或更高版本：bash aws eks describe-cluster--name--query 'cluster.version '

• 在启用自动模式之前，请验证集群是否处于活动状态

工作流程失败

• 查看 GitHub 操作日志以获取特定的错误消息

• 在中验证工作流文件语法。 github/workflows/auto-mode-pipeline.yml

• 确保在工作流程中正确设置环境变量

相关资源

  1. EKS 自动模式官方入门文档

  2. 更新集群配置 CLI 文档

  3. GitHub GitHub 行动秘诀

  4. GitHub 操作文档 

  5. OIDC 联合会文档