View a markdown version of this page

使用 GitHub 動作跨 EKS 叢集啟用 Amazon EKS Auto 模式 - AWS 方案指引
摘要先決條件和限制Architecture工具最佳實務史詩疑難排解相關資源

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 GitHub 動作跨 EKS 叢集啟用 Amazon EKS Auto 模式

Urbija Goswami 和 Anugrah Lakra，Amazon Web Services

摘要

Amazon Elastic Kubernetes Service (EKS) 叢集傳統上需要透過節點群組手動管理運算資源。這會為下列項目建立營運開銷：

  • 容量規劃和擴展決策

  • 節點佈建和生命週期管理

  • 跨不同工作負載類型的成本最佳化

  • 基礎設施維護和更新

Amazon EKS Auto Mode 會根據工作負載需求動態佈建和擴展節點，以自動化運算資源管理，無需手動節點群組管理。

不過，許多組織難以在其現有和新的叢集中持續啟用和管理 Amazon EKS Auto Mode。常見的挑戰包括：

  • 從現有節點群組的複雜遷移程序

  • 轉換期間服務中斷的風險

  • 需要仔細規劃和測試容量

  • 特定 Amazon IAM 許可和組態的需求

  • 跨多個團隊和環境進行協調

此模式實作 GitHub 動作工作流程，在特定 AWS 區域中啟用 EKS 叢集上的 EKS 自動模式。啟用自動模式之前，工作流程會建立叢集狀態的時間戳記備份 （叢集組態、節點群組、Helm 版本和自訂資源），並將其上傳至 Amazon S3 儲存貯體。

啟用自動模式後，工作流程會耗盡和刪除舊節點群組、更新叢集角色許可，以及清除先前的擴展元件，例如 Karpenter 和 Cluster Autoscaler。工作流程可與現有的持續整合和持續交付/部署 (CI/CD) 管道整合。

先決條件和限制

先決條件

1。必要

2. 本機工具安裝

3. EKS 叢集需求

  • Kubernetes 1.29 版或更新版本

  • 端點存取組態：

    • 設定為公有和私有端點 

    • 或在私有子網路中使用 NAT Gateway 的私有端點

  • 已啟用 EKS API 和 ConfigMap 叢集存取 （需要允許 EKS 動態管理 Auto Mode 節點，並更新 aws-auth ConfigMap，以便在遷移期間進行適當的叢集身分驗證）

  • 作用中節點群組或受管節點集區

4. IAM OIDC 組態需求

  • GitHub 的 IAM 角色和身分提供者，包括：

    • GitHub OIDC 的信任政策

    • 的許可：

      • EKS 叢集管理

      • S3 儲存貯體存取

      • IAM 角色管理

      • EC2 網路管理

  • 如需使用 Terraform 的簡單設定，請參閱 iam.tf 程式碼。套用 Terraform 程式碼時，將會建立 IAM 角色 (GitHubActionsEKSRole)。

限制

  • 僅支援 Kubernetes 1.29 版及更高版本的 EKS 叢集

  • 僅支援 Karpenter 1.1.0 版及更新版本

  • 區域特定的實作。並非所有 AWS 區域都提供某些 AWS 服務。如需區域可用性，請參閱依區域的 AWS 服務

  • 需要叢集端點可存取性

  • 僅限 AWS 受管節點群組

Architecture

目標技術堆疊

  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. 需要啟用自動模式的叢集角色會擷取，如果 AmazonEKSComputePolicy、AmazonEKSBlockStoragePolicy、AmazonEKSLoadBalancingPolicy、AmazonEKSNetworkingPolicy、AmazonEKSClusterPolicy) 新增至叢集。此外，做為預遷移步驟，叢集的子網路會以 EKS Auto Mode 啟用的標籤更新。

  5. 工作流程會在 EKS 叢集中啟用 EKS Auto 模式。

  6. 識別和刪除舊節點群組。如果使用者尚未將許可授予以下選用設定步驟中所述的 IAM 角色，則會略過此選項。

  7. 如果先前存在，也會移除擴展元件 (Karpenter 和 Cluster Autoscaler)。

GitHub 動作工作流程包含三個主要任務：

  1. check-clusters：識別未啟用自動模式的叢集，並更新 IAM 政策和子網路標籤。

  2. backup-and-check：在遷移之前備份叢集狀態。

  3. gradual-migration ：啟用自動模式，同時逐漸耗盡現有的節點群組並清除舊的擴展元件。它也會在遷移後對叢集的狀態進行最終驗證。

注意

如果您需要節點組態備份，或計劃在遷移至 EKS Auto Mode 期間刪除節點/節點群組，則可以將使用 terraform 程式碼建立的 IAM 角色新增至 aws-auth ConfigMap。如果沒有它，您仍然可以檢視節點群組組態。 

工具

AWS CLI：

AWS Command Line Interface (AWS CLI) 是一種開放原始碼工具，可協助您透過命令列 shell 中的命令與 AWS 服務互動。在我們的解決方案中，我們使用 AWS 服務的命令列界面，在整個自動化過程中執行 EKS 叢集組態更新、IAM 角色更新和查詢叢集狀態。

Amazon EKS：

Amazon Elastic Kubernetes Service (Amazon EKS) 可協助您在 AWS 上執行 Kubernetes，而不需要安裝或維護您自己的 Kubernetes 控制平面或節點。在此模式中，Amazon EKS 是啟用自動模式的目標服務，可在特定區域中跨叢集自動化運算佈建和節點擴展。

IAM：

AWS Identity and Access Management (IAM) 可透過控制已驗證並獲授權使用的人員，協助您安全地管理對 AWS 資源的存取。在我們的解決方案中，我們使用它來管理 GitHub 動作的許可，以透過 OIDC 聯合修改 EKS 叢集組態。解決方案也會修改叢集角色許可，並新增任務來建立 EKS 節點角色，讓 EKS Auto Mode 可以在新節點中排程待定 Pod，並將其作為節點集區的一部分啟動。

Amazon S3：

Amazon Simple Storage Service (Amazon S3) 是一種雲端型物件儲存服務，可協助您儲存、保護和擷取任何數量的資料。在我們的解決方案中，我們使用 S3 儲存貯體在啟用 EKS Auto Mode 之前存放叢集的時間戳記備份，這有助於災難復原。

其他工具：

GitHub 動作：

GitHub Actions 是一種 CI/CD 平台，用於我們的解決方案，以自動化 EKS Auto Mode 啟用工作流程。它也透過 OIDC 提供安全身分驗證，並管理跨多個叢集的管道執行。  

HashiCorp Terraform：

Terraform 是一種基礎設施即程式碼 (IaC) 工具，可協助您使用程式碼來佈建和管理雲端基礎設施和資源。我們的解決方案使用 terraform 來佈建 IAM 角色和政策，並新增 OIDC 提供者組態，以實現安全的 GitHub Actions 整合。 

程式碼儲存庫

此模式的程式碼可透過 GitHub 動作儲存庫在 GitHub EKS 自動模式啟用中取得。

最佳實務

  • 安全性：

    • 遵循最低權限原則，並授予執行任務所需的最低許可。如需詳細資訊，請參閱 IAM 文件中的授予最低權限和安全最佳實務。如需最低必要組態，請參閱 儲存庫中的 iam.tf 檔案。 

    • 將 IAM 角色信任政策範圍限定在您的特定 GitHub 儲存庫和分支，以防止未經授權的工作流程執行擔任該角色。 

    • 在開始遷移之前啟用 EKS 控制平面記錄 (API 伺服器、稽核、驗證器），以便在啟用自動模式後診斷排程或身分驗證問題。 

    • 將 --sse AES256 新增至備份指令碼中的所有 aws s3 cp 命令，以在叢集狀態備份上強制執行伺服器端加密。 

  • 可靠性：

    • 先針對非生產叢集測試工作流程。在遷移生產叢集之前，請確認工作負載在自動模式節點上正確重新排程。 

    • 在繼續啟用自動模式之前，請確認 S3 備份已成功完成，並包含有效的叢集組態、節點群組、 Helm Release 和自訂資源資料。 

    • 啟用自動模式後，請使用 Amazon CloudWatch Container Insights 監控 Pod 排程事件和節點佈建延遲，以提早偵測問題。 

  • 效能：

    • 定期檢閱自動模式節點集區擴展模式，並調整工作負載資源請求和限制，以避免過度佈建或排程延遲。

  • 費用：

    • 使用環境和擁有權中繼資料來標記 EKS 叢集和相關資源 (IAM 角色、S3 備份儲存貯體、子網路），以支援成本追蹤和營運可見性。如需詳細資訊，請參閱標記 AWS 資源文件。您可以編輯工作流程檔案，在遷移過程中新增自訂標籤。 

    • 設定 AWS Cost Explorer 警示，以在啟用自動模式後監控運算成本的變更，因為自動模式可能會變更執行個體類型和擴展行為。如需詳細資訊，請參閱使用 AWS Cost Explorer 文件分析您的成本。  

  • 操作：

    • 在版本控制中保留工作流程檔案和 Terraform 組態，並記錄任何環境特定的覆寫，例如區域、角色 ARN 或 S3 儲存貯體名稱。   

史詩

任務Description所需的技能

設定 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，雲端架構師
任務Description所需的技能

設定 IAM 進行備份和節點群組刪除

  1. 使用終端機將角色新增至 aws-auth ConfigMap：

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。

  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_REGION 和 $ROLE_ARN 分別取代為上述建立的特定區域和 IAM 角色。

AWS DevOps，雲端架構師
任務Description所需的技能

觸發 GitHub 動作工作流程。

當任何變更推送到功能、主要或開發分支時，工作流程會自動觸發。若要透過 GitHub UI 手動觸發：1. 前往 GitHub 2 上的儲存庫。按一下「動作」索引標籤 3。選取工作流程 auto-mode-pipeline) 4. 按一下「執行工作流程」按鈕 5。選擇分支，然後按一下「執行工作流程」

工作流程會在遷移後處理驗證，方法是使用 AWS CLI 查詢每個遷移叢集的運算組態，以確認 EKS Auto Mode 已成功啟用，並以資料表格式顯示目前的運算設定。

AWS DevOps，雲端架構師
任務Description所需的技能

實作多環境部署。

  • 該解決方案可以透過利用分支型部署來實現環境特有的解決方案。

  • 透過 GitHub 秘密 (AWS_REGION、AWS_ROLE_ARN、S3_BACKUP_BUCKET)，不同的分支 (main、dev、feat/*) 會觸發具有環境特定組態的工作流程。

  • 這允許每個環境個別的 AWS 區域、IAM 角色和叢集集，同時在所有環境中維持一致的自動化邏輯。

任務Description所需的技能

清除資源。

  1. 若要從 aws-auth ConfigMap 分離 IAM 角色，請使用下列終端機命令：

    eksctl delete iamidentitymapping \   --cluster $cluster \   --region $AWS_REGION \   --arn $ROLE_ARN
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-arn> --role-session-name test-session aws eks list-clusters

• 確保角色具有 eks：UpdateClusterConfig 和 eks：DescribeCluster 許可

叢集相容性

• 確認 EKS 叢集正在執行 Kubernetes 1.29 或更新版本：Bash aws eks describe-cluster --name <cluster-name> --query 'cluster.version'

• 啟用自動模式之前，請確認叢集處於 ACTIVE 狀態

工作流程失敗

• 檢查 GitHub 動作日誌是否有特定錯誤訊息

• 驗證 .github/workflows/auto-mode-pipeline.yml 中的工作流程檔案語法

• 確保在工作流程中正確設定環境變數

相關資源

  1. EKS Auto Mode 官方文件以開始使用

  2. 更新叢集組態 CLI 文件

  3. GitHub 動作的 GitHub 秘密

  4. GitHub 動作文件 

  5. OIDC 聯合文件