本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用 GitHub 動作跨 EKS 叢集啟用 Amazon EKS Auto 模式 *Urbija Goswami 和 Anugrah Lakra，Amazon Web Services* ## 摘要 [Amazon Elastic Kubernetes Service (EKS) ](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/amazon-elastic-kubernetes-service.html)叢集傳統上需要透過節點群組手動管理運算資源。這會為下列項目建立營運開銷： + 容量規劃和擴展決策 + 節點佈建和生命週期管理 + 跨不同工作負載類型的成本最佳化 + 基礎設施維護和更新 Amazon EKS [Auto Mode](https://docs.aws.amazon.com/eks/latest/userguide/automode.html) 會根據工作負載需求動態佈建和擴展節點，以自動化運算資源管理，無需手動節點群組管理。 不過，許多組織難以在其現有和新的叢集中持續啟用和管理 Amazon EKS Auto Mode。常見的挑戰包括： + 從現有節點群組的複雜遷移程序 + 轉換期間服務中斷的風險 + 需要仔細規劃和測試容量 + 特定 [Amazon IAM ](https://aws.amazon.com/iam/?trk=6a436c72-0178-4620-97ad-0220ccc59fd0&sc_channel=ps&ef_id=CjwKCAjw7vzOBhBxEiwAc7WNr57daOn9724PwXVGy7aBxG_uuEHktjCWJbcY1q1BrZBaApyi1sAb_BoCQj0QAvD_BwE:G:s&s_kwcid=AL!4422!3!795924581177!e!!g!!amazon%20iam!23523526050!193629723318&gad_campaignid=23523526050&gbraid=0AAAAADjHtp_aCwsziIR-n3ST_xwoCqAuc&gclid=CjwKCAjw7vzOBhBxEiwAc7WNr57daOn9724PwXVGy7aBxG_uuEHktjCWJbcY1q1BrZBaApyi1sAb_BoCQj0QAvD_BwE)許可和組態的需求 + 跨多個團隊和環境進行協調 此模式實作 [GitHub 動作](https://docs.github.com/en/actions)工作流程，在特定 AWS 區域中啟用 EKS 叢集上的 EKS 自動模式。啟用自動模式之前，工作流程會建立叢集狀態的時間戳記備份 （叢集組態、節點群組、Helm 版本和自訂資源），並將其上傳至 [Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) 儲存貯體。 啟用自動模式後，工作流程會耗盡和刪除舊節點群組、更新叢集角色許可，以及清除先前的擴展元件，例如 Karpenter 和 Cluster Autoscaler。工作流程可與現有的持續整合和持續交付/部署 (CI/CD) 管道整合。 ## 先決條件和限制 **先決條件** **1。必要 ** + 執行工作流程的 [GitHub 帳戶](https://github.com/)和您自己的 GitHub 儲存庫 + 具有管理許可的作用中 [AWS 帳戶](https://aws.amazon.com/account/) **2. 本機工具安裝** + [Terraform](https://developer.hashicorp.com/terraform/install) 1.13.0 版或更新版本 + [GitHub CLI](https://cli.github.com/) (gh)，使用適當的登入資料設定 + [kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html) 和 [eksctl](https://docs.aws.amazon.com/eks/latest/eksctl/installation.html)，設定為叢集管理 **3. EKS 叢集需求** + Kubernetes 1.29 版或更新版本 + 端點存取組態： + 設定為公有和私有端點  + 或在私有子網路中使用 NAT Gateway 的私有端點 + 已啟用 [EKS API](https://docs.aws.amazon.com/eks/latest/userguide/grant-k8s-access.html) 和 [ConfigMap](https://docs.aws.amazon.com/eks/latest/userguide/auth-configmap.html) 叢集存取 （需要允許 EKS 動態管理 Auto Mode 節點，並更新 aws-auth ConfigMap，以便在遷移期間進行適當的叢集身分驗證） + 作用中[節點群組或受管節點集區](https://docs.aws.amazon.com/eks/latest/userguide/managed-node-groups.html) **4. IAM OIDC 組態需求** + GitHub 的 IAM 角色和身分提供者，包括： + GitHub OIDC 的信任政策 + 的許可： + EKS 叢集管理 + S3 儲存貯體存取 + IAM 角色管理 + EC2 網路管理 + 如需使用 Terraform 的簡單設定，請參閱 [iam.tf](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/iam.tf) 程式碼。套用 Terraform 程式碼時，將會建立 IAM 角色 (GitHubActionsEKSRole)。 **限制 ** + 僅支援 Kubernetes 1.29 版及更高版本的 EKS 叢集 + 僅支援 Karpenter 1.1.0 版及更新版本 + 區域特定的實作。並非所有 AWS 區域都提供某些 AWS 服務。如需區域可用性，請參閱[依區域的 AWS 服務](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/) + 需要叢集端點可存取性 + 僅限 AWS 受管節點群組 ## Architecture **目標技術堆疊 ** 1. [https://docs.github.com/en/actions](https://docs.github.com/en/actions) 1. [https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) 1. [https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/amazon-elastic-kubernetes-service.html](https://docs.aws.amazon.com/whitepapers/latest/overview-deployment-options/amazon-elastic-kubernetes-service.html) 1. [https://aws.amazon.com/s3/](https://aws.amazon.com/s3/) **目標架構 ** ![](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/images/pattern-img/e1fa4e49-96a5-42ae-9886-766298664db4/images/a2c46a84-3bf5-4f1e-8216-ab29b4ba894e.png) 1. GitHub 動作工作流程是由使用者從 GitHub 儲存庫觸發。 1. GitHub 動作工作流程使用 OIDC 擔任 IAM 角色，以在 AWS 帳戶中進行必要的變更。它也會檢查帳戶中是否存在 EKS Auto Node 角色，如果不存在，則會建立角色並連接必要的政策。 1. 需要啟用自動模式的 EKS 叢集目前狀態的備份會上傳至 S3 儲存貯體。 1. 需要啟用自動模式的叢集角色會擷取，如果 AmazonEKSComputePolicy、AmazonEKSBlockStoragePolicy、AmazonEKSLoadBalancingPolicy、AmazonEKSNetworkingPolicy、AmazonEKSClusterPolicy) 新增至叢集。此外，做為預遷移步驟，叢集的子網路會以 EKS Auto Mode 啟用的標籤更新。 1. 工作流程會在 EKS 叢集中啟用 EKS Auto 模式。 1. 識別和刪除舊節點群組。如果使用者尚未將許可授予以下選用設定步驟中所述的 IAM 角色，則會略過此選項。 1. 如果先前存在，也會移除擴展元件 (Karpenter 和 Cluster Autoscaler)。 GitHub 動作工作流程包含三個主要任務： 1. `check-clusters`：識別未啟用自動模式的叢集，並更新 IAM 政策和子網路標籤。 1. `backup-and-check`：在遷移之前備份叢集狀態。 1. `gradual-migration` ：啟用自動模式，同時逐漸耗盡現有的節點群組並清除舊的擴展元件。它也會在遷移後對叢集的狀態進行最終驗證。 **注意** 如果您需要節點組態備份，或計劃在遷移至 EKS Auto Mode 期間刪除節點/節點群組，則可以將使用 terraform 程式碼建立的 IAM 角色新增至 aws-auth ConfigMap。如果沒有它，您仍然可以檢視節點群組組態。  ## 工具 *AWS CLI：* [AWS Command Line Interface (AWS CLI)](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) 是一種開放原始碼工具，可協助您透過命令列 shell 中的命令與 AWS 服務互動。在我們的解決方案中，我們使用 AWS 服務的命令列界面，在整個自動化過程中執行 EKS 叢集組態更新、IAM 角色更新和查詢叢集狀態。 *Amazon EKS：* [Amazon Elastic Kubernetes Service (Amazon EKS)](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html) 可協助您在 AWS 上執行 Kubernetes，而不需要安裝或維護您自己的 Kubernetes 控制平面或節點。在此模式中，Amazon EKS 是啟用自動模式的目標服務，可在特定區域中跨叢集自動化運算佈建和節點擴展。 *IAM：* [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) 可透過控制已驗證並獲授權使用的人員，協助您安全地管理對 AWS 資源的存取。在我們的解決方案中，我們使用它來管理 GitHub 動作的許可，以透過 OIDC 聯合修改 EKS 叢集組態。解決方案也會修改叢集角色許可，並新增任務來建立 EKS 節點角色，讓 EKS Auto Mode 可以在新節點中排程待定 Pod，並將其作為節點集區的一部分啟動。 *Amazon S3***：** [Amazon Simple Storage Service (Amazon S3)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html) 是一種雲端型物件儲存服務，可協助您儲存、保護和擷取任何數量的資料。在我們的解決方案中，我們使用 S3 儲存貯體在啟用 EKS Auto Mode 之前存放叢集的時間戳記備份，這有助於災難復原。 **其他工具：** *GitHub 動作：* [GitHub Actions](https://docs.github.com/en/actions) 是一種 CI/CD 平台，用於我們的解決方案，以自動化 EKS Auto Mode 啟用工作流程。它也透過 OIDC 提供安全身分驗證，並管理跨多個叢集的管道執行。   *HashiCorp Terraform：* [Terraform](https://developer.hashicorp.com/terraform/docs) 是一種基礎設施即程式碼 (IaC) 工具，可協助您使用程式碼來佈建和管理雲端基礎設施和資源。我們的解決方案使用 terraform 來佈建 IAM 角色和政策，並新增 OIDC 提供者組態，以實現安全的 GitHub Actions 整合。  **程式碼儲存庫** 此模式的程式碼可透過 GitHub [動作儲存庫在 GitHub EKS 自動模式啟用](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/tree/main)中取得。 ## 最佳實務 + **安全性**： + 遵循最低權限原則，並授予執行任務所需的最低許可。如需詳細資訊，請參閱 [IAM 文件中的授予最低權限和安全最佳實務。](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege.)如需最低必要組態，請參閱 儲存庫中的 [iam.tf](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/iam.tf) 檔案。  + 將 IAM 角色信任政策範圍限定在您的特定 GitHub 儲存庫和分支，以防止未經授權的工作流程執行擔任該角色。  + 在開始遷移之前啟用 EKS 控制平面記錄 (API 伺服器、稽核、驗證器），以便在啟用自動模式後診斷排程或身分驗證問題。  + 將 --sse AES256 新增至[備份指令碼](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/main/scripts/backup-cluster-state.sh)中的所有 aws s3 cp 命令，以在叢集狀態備份上強制執行伺服器端加密。  + **可靠性**： + 先針對非生產叢集測試工作流程。在遷移生產叢集之前，請確認工作負載在自動模式節點上正確重新排程。  + 在繼續啟用自動模式之前，請確認 S3 備份已成功完成，並包含有效的叢集組態、節點群組、 Helm Release 和自訂資源資料。  + 啟用自動模式後，請使用 [Amazon CloudWatch Container Insights ](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/ContainerInsights.html)監控 Pod 排程事件和節點佈建延遲，以提早偵測問題。  + **效能**： + 定期檢閱自動模式節點集區擴展模式，並調整工作負載資源請求和限制，以避免過度佈建或排程延遲。 + **費用：** + 使用環境和擁有權中繼資料來標記 EKS 叢集和相關資源 (IAM 角色、S3 備份儲存貯體、子網路），以支援成本追蹤和營運可見性。如需詳細資訊，請參閱[標記 AWS 資源文件](https://docs.aws.amazon.com/general/latest/gr/aws_tagging.html.)。您可以編輯工作流程檔案，在遷移過程中新增自訂標籤。  + 設定 AWS Cost Explorer 警示，以在啟用自動模式後監控運算成本的變更，因為自動模式可能會變更執行個體類型和擴展行為。如需詳細資訊，請參閱使用 [AWS Cost Explorer ](https://docs.aws.amazon.com/cost-management/latest/userguide/ce-what-is.html.)文件分析您的成本。   + **操作**： + 在版本控制中保留工作流程檔案和 Terraform 組態，並記錄任何環境特定的覆寫，例如區域、角色 ARN 或 S3 儲存貯體名稱。    ## 史詩 ### 工具SetUp | 任務 | Description | 所需的技能 | | --- | --- | --- | | 設定 GitHub 儲存庫。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html) | AWS DevOps，雲端架構師 | ### （選用） 設定 IAM 角色 | 任務 | Description | 所需的技能 | | --- | --- | --- | | 設定 IAM 進行備份和節點群組刪除 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html)
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** 和 **$ACCOUNT\_ID**。[See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html)
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\_REGION** 和 **$ROLE\_ARN** 分別取代為上述建立的特定區域和 IAM 角色。 | AWS DevOps，雲端架構師 | ### 執行和驗證 | 任務 | Description | 所需的技能 | | --- | --- | --- | | 觸發 GitHub 動作工作流程。 | 當任何變更推送到功能、主要或開發分支時，工作流程會自動觸發。若要透過 GitHub UI 手動觸發：1. 前往 GitHub 2 上的儲存庫。按一下「動作」索引標籤 3。選取工作流程 auto-mode-pipeline) 4. 按一下「執行工作流程」按鈕 5。選擇分支，然後按一下「執行工作流程」
工作流程會在遷移後處理[驗證](https://github.com/aws-samples/sample-enable-eks-auto-mode-using-github-actions/blob/22b546b05630c63e5637928ad8a4f5947ad8fb33/.github/workflows/enable-eks-auto-mode.yml#L283)，方法是使用 AWS CLI 查詢每個遷移叢集的運算組態，以確認 EKS Auto Mode 已成功啟用，並以資料表格式顯示目前的運算設定。 | AWS DevOps，雲端架構師 | ### 設定多環境部署 | 任務 | Description | 所需的技能 | | --- | --- | --- | | 實作多環境部署。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html) | | ### 清除 | 任務 | Description | 所需的技能 | | --- | --- | --- | | 清除資源。 | [See the AWS documentation website for more details](http://docs.aws.amazon.com/zh_tw/prescriptive-guidance/latest/patterns/enable-eks-auto-mode-using-github-actions.html) | General AWS，雲端架構師 | ## 疑難排解 | 問題 | 解決方案 | | --- | --- | | **身分驗證問題**

| • 確認 GitHub OIDC 供應商已在 AWS IAM 中正確設定
• 檢查 git 秘密中的 IAM 角色 ARN 是否符合使用 terraform 建立的實際角色 (GitHubActionsEKSRole)
• 確保 GitHub 儲存庫已設定必要的秘密 - AWS\_REGION 和 AWS\_ROLE\_ARN。
• 驗證 AWS 區域設定是否符合您的叢集位置 | | **許可問題**

| • 在本機測試 IAM 角色許可：Bash aws sts assume-role --role-arn --role-session-name test-session aws eks list-clusters
• 確保角色具有 eks：UpdateClusterConfig 和 eks：DescribeCluster 許可 | | **叢集相容性**

| • 確認 EKS 叢集正在執行 Kubernetes 1.29 或更新版本：Bash aws eks describe-cluster --name --query 'cluster.version'
• 啟用自動模式之前，請確認叢集處於 ACTIVE 狀態 | | **工作流程失敗**
| • 檢查 GitHub 動作日誌是否有特定錯誤訊息
• 驗證 .github/workflows/auto-mode-pipeline.yml 中的工作流程檔案語法
• 確保在工作流程中正確設定環境變數 | ## 相關資源 1. [EKS Auto Mode 官方文件以開始使用](https://docs.aws.amazon.com/eks/latest/userguide/automode.html) 1. [更新叢集組態 CLI 文件](https://docs.aws.amazon.com/cli/latest/reference/eks/update-cluster-config.html) 1. [GitHub 動作的 GitHub 秘密](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) 1. [GitHub 動作文件](https://docs.github.com/en/actions)  1. [OIDC 聯合文件](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)