概要前提条件と制限アーキテクチャツールベストプラクティスエピックトラブルシューティング関連リソース

GitHub Actions を使用して EKS クラスター間で Amazon EKS Auto Mode を有効にする

Urbija Goswami と Anugrah Lakra、Amazon Web Services

概要

Amazon Elastic Kubernetes Service (EKS) クラスターでは、従来、ノードグループを介したコンピューティングリソースの手動管理が必要です。これにより、以下の運用オーバーヘッドが発生します。

キャパシティプランニングとスケーリングの決定
ノードのプロビジョニングとライフサイクル管理
さまざまなワークロードタイプのコスト最適化
インフラストラクチャのメンテナンスと更新

Amazon EKS Auto Mode は、ワークロードの需要に基づいてノードを動的にプロビジョニングおよびスケーリングすることでコンピューティングリソース管理を自動化するため、手動ノードグループ管理が不要になります。

ただし、多くの組織は、既存のクラスターと新しいクラスター全体で Amazon EKS Auto Mode を一貫して有効化および管理することに苦労しています。一般的な課題は次のとおりです。

既存のノードグループからの複雑な移行プロセス
移行中のサービス中断のリスク
慎重なキャパシティプランニングとテストが必要
特定の Amazon IAM アクセス許可と設定の要件
複数のチームや環境間の調整

このパターンは、特定の AWS リージョンの EKS クラスターで EKS Auto Mode を有効にする GitHub Actions ワークフローを実装します。自動モードを有効にする前に、ワークフローはクラスター状態 (クラスター設定、ノードグループ、Helm リリース、カスタムリソース) のタイムスタンプ付きバックアップを作成し、Amazon S3 バケットにアップロードします。

自動モードを有効にすると、ワークフローは古いノードグループをドレインおよび削除し、クラスターロールのアクセス許可を更新し、Karpenter や Cluster Autoscaler などの以前のスケーリングコンポーネントをクリーンアップします。ワークフローは、既存の継続的インテグレーションおよび継続的デリバリー/デプロイ (CI/CD) パイプラインと統合できます。

前提条件と制限

前提条件

1. 必須

ワークフローを実行するための GitHub アカウントと独自の GitHub リポジトリ
管理権限を持つアクティブな AWS アカウント

2。ローカルツールのインストール

Terraform バージョン 1.13.0 以降
適切な認証情報で設定された GitHub CLI (gh)
クラスター管理用に設定された kubectl と eksctl

3. EKS クラスターの要件

Kubernetes バージョン 1.29 以降
エンドポイントアクセス設定:
- パブリックエンドポイントとプライベートエンドポイントのいずれかに設定されている場合
- または、プライベートサブネットに NAT Gateway を持つプライベートエンドポイント
EKS API と ConfigMap クラスターアクセスが有効 (EKS が Auto Mode ノードを動的に管理し、移行中に適切なクラスター認証のために aws-auth ConfigMap を更新できるようにするために必要)
アクティブなノードグループまたはマネージド型ノードプール

4. IAM OIDC 設定要件

以下を含む GitHub の IAM ロールと ID プロバイダー。
- GitHub OIDC の信頼ポリシー
- 以下のアクセス許可:
  - EKS クラスター管理
  - S3 バケットアクセス
  - IAM ロールの管理
  - EC2 ネットワーク管理
Terraform を使用した簡単なセットアップについては、iam.tf コードを参照してください。Terraform コードが適用されると、IAM ロール (GitHubActionsEKSRole) が作成されます。

制限事項

Kubernetes バージョン 1.29 以降の EKS クラスターのみをサポート
Karpenter バージョン 1.1.0 以降のみをサポート
リージョン固有の実装。一部の AWS サービスは、すべての AWS リージョンで利用できるわけではありません。リージョンの可用性については、「リージョン別の AWS のサービス」を参照してください。
クラスターエンドポイントのアクセシビリティが必要です
AWS マネージド型ノードグループに限定

アーキテクチャ

ターゲットテクノロジースタック

ターゲットアーキテクチャ

GitHub Actions ワークフローは、ユーザーによって GitHub リポジトリからトリガーされます。
GitHub Actions ワークフローは、OIDC を使用して IAM ロールを引き受け、AWS アカウントに必要な変更を加えます。また、アカウント内に EKS Auto Node ロールが存在するかどうかもチェックし、存在しない場合はロールが作成され、必要なポリシーがアタッチされます。
Auto Mode が有効になっている EKS クラスターの現在の状態のバックアップが S3 バケットにアップロードされます。
Auto Mode を有効にする必要があるクラスターのクラスターロールが取得され、EKS Auto Mode に存在しない場合は追加のアクセス許可 (AmazonEKSComputePolicy、AmazonEKSBlockStoragePolicy、AmazonEKSLoadBalancingPolicy、AmazonEKSNetworkingPolicy、AmazonEKSClusterPolicy) が追加されます。さらに、移行前のステップとして、クラスターのサブネットは EKS Auto Mode を有効にするためのタグで更新されます。
ワークフローは、EKS クラスターで EKS Auto Mode を有効にします。
古いノードグループは識別され、削除されます。これは、ユーザーが以下のオプションのセットアップステップで説明されている IAM ロールにアクセス許可を付与していない場合はスキップされます。
スケーリングコンポーネント (Karpenter と Cluster Autoscaler) も、以前に存在する場合は削除されます。

GitHub Actions ワークフローは、3 つの主要なジョブで構成されます。

check-clusters: Auto Mode が有効になっていないクラスターを識別し、IAM ポリシーとサブネットタグを更新します。
backup-and-check: 移行前にクラスターの状態をバックアップします。
gradual-migration : 既存のノードグループを徐々にドレインし、古いスケーリングコンポーネントをクリーンアップしながら、自動モードを有効にします。また、移行後にクラスターの状態の最終検証も行います。

注記

ノード設定のバックアップが必要な場合、または EKS Auto Mode への移行中にノード/ノードグループを削除する予定がある場合は、Terraform コードを使用して作成された IAM ロールを aws-auth ConfigMap に追加できます。これがない場合でも、ノードグループ設定を表示できます。

ツール

AWS CLI:

AWS コマンドラインインターフェイス (AWS CLI) は、コマンドラインシェルのコマンドを使用して AWS サービスとやり取りすることができる、オープンソースのツールです。このソリューションでは、AWS サービスのコマンドラインインターフェイスを使用して、オートメーションプロセス全体で EKS クラスター設定の更新、IAM ロールの更新、クラスターステータスのクエリを実行します。

Amazon EKS:

Amazon Elastic Kubernetes Service (Amazon EKS) は、で Kubernetes を実行する際に役立ちます。独自の Kubernetes コントロールプレーンまたはノードをインストールおよび維持する必要はありません。このパターンでは、Amazon EKS は、Auto Mode を有効にして、特定のリージョンのクラスター間でコンピューティングプロビジョニングとノードスケーリングを自動化できるターゲットサービスです。

IAM:

「AWS Identity and Access Management (IAM)」は、AWS リソースへのアクセスを安全に管理し、誰が認証され、使用する権限があるかを制御するのに役立ちます。当社のソリューションでは、これを使用してGitHub Actions が OIDC フェデレーションを介して EKS クラスター設定を変更するためのアクセス許可を管理します。このソリューションでは、クラスターロールのアクセス許可を変更し、ジョブを追加して EKS ノードロールを作成します。これにより、EKS Auto Mode はノードプールの一部としてスピンアップする新しいノードで保留中のポッドをスケジュールできます。

Amazon S3:

Amazon Simple Storage Service (Amazon S3) は、あらゆる量のデータを保存、保護、取得できるクラウドベースのオブジェクトストレージサービスです。このソリューションでは、EKS Auto Mode が有効になる前に、S3 バケットを使用してクラスターのタイムスタンプ付きバックアップを保存します。これはディザスタリカバリに役立ちます。

その他のツール:

GitHub アクション:

GitHub Actions は、EKS Auto Mode の有効化ワークフローを自動化するソリューションで使用される CI/CD プラットフォームです。また、OIDC を介した安全な認証を提供し、複数のクラスターでのパイプライン実行を管理します。

HashiCorp Terraform:

Terraform は、コードを使用してクラウドインフラストラクチャとリソースをプロビジョニングして管理するのに役立つ infrastructure as code (IaC) ツールです。当社のソリューションは terraform を使用して IAM ロールとポリシーをプロビジョニングし、安全な GitHub Actions 統合のための OIDC プロバイダー設定を追加します。

コードリポジトリ

このパターンのコードは、GitHub Actions リポジトリを介して GitHub EKS Auto Mode Enablement で使用できます。

ベストプラクティス

のセキュリティ
- 最小特権の原則に従い、タスクの実行に必要な最小限の権限を付与します。詳細については、IAM ドキュメントの「最小特権を付与する」と「セキュリティのベストプラクティス」を参照してください。最低限必要な設定については、リポジトリの iam.tf ファイルを参照してください。
- IAM ロールの信頼ポリシーを特定の GitHub リポジトリとブランチにスコープして、不正なワークフロー実行がロールを引き受けるのを防ぎます。
- 移行を開始する前に EKS コントロールプレーンのログ記録 (API サーバー、監査、認証) を有効にすると、Auto Mode が有効になった後にスケジューリングまたは認証の問題を診断できます。
- バックアップスクリプト内のすべての aws s3 cp コマンドに --sse AES256 を追加して、クラスター状態のバックアップにサーバー側の暗号化を適用します。
信頼性:
- まず、非本番稼働用クラスターに対してワークフローをテストします。本番稼働用クラスターを移行する前に、ワークロードが Auto Mode ノードで正しく再スケジュールされていることを確認します。
- Auto Mode を有効にする前に、S3 バックアップが正常に完了し、有効なクラスター設定、ノードグループ、Helm リリース、カスタムリソースデータが含まれていることを確認します。
- 自動モードを有効にしたら、Amazon CloudWatch Container Insights を使用してポッドスケジューリングイベントとノードプロビジョニングのレイテンシーをモニタリングし、問題を早期に検出します。
パフォーマンス:
- Auto Mode ノードプールのスケーリングパターンを定期的に確認し、ワークロードリソースのリクエストと制限を調整して、過剰なプロビジョニングやスケジュールの遅延を回避します。
料金:
- EKS クラスターおよび関連リソース (IAM ロール、S3 バックアップバケット、サブネット) に環境と所有権のメタデータをタグ付けして、コストの追跡と運用の可視性をサポートします。詳細については、「AWS リソースドキュメントのタグ付け」を参照してください。ワークフローファイルを編集して、移行プロセス中にカスタムタグを追加できます。
- Auto Mode はインスタンスタイプとスケーリング動作を変更する可能性があるため、Auto Mode を有効にした後のコンピューティングコストの変化をモニタリングするように AWS Cost Explorer アラートを設定します。詳細については、「AWS Cost Explorer ドキュメントによるコストの分析」を参照してください。
オペレーション:
- ワークフローファイルと Terraform 設定をバージョン管理に保持し、リージョン、ロール ARN、S3 バケット名などの環境固有のオーバーライドを文書化します。

エピック

タスク説明必要なスキル

タスク	説明	必要なスキル
GitHub リポジトリを設定します。	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` 変更をコミットして GitHub リポジトリにプッシュする `cd <path/to/your/repository> git add . git commit -m "Added EKS Auto Mode configurations" git push origin main` リポジトリの 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、クラウドアーキテクト

GitHub リポジトリを設定します。

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

変更をコミットして GitHub リポジトリにプッシュする


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

リポジトリの 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、クラウドアーキテクト

タスク説明必要なスキル

タスク	説明	必要なスキル
バックアップとノードグループの削除用に IAM を設定する	ターミナルを使用して 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 を適切な値に置き換えます。複数のクラスターの場合、管理者レベルまたは同等のレベルのアクセス権を持つロールを引き受けて、ターミナルで次のコマンドを実行できます。 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 ロールの arn に置き換えます。	AWS DevOps、クラウドアーキテクト

バックアップとノードグループの削除用に IAM を設定する

ターミナルを使用して 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 を適切な値に置き換えます。

複数のクラスターの場合、管理者レベルまたは同等のレベルのアクセス権を持つロールを引き受けて、ターミナルで次のコマンドを実行できます。


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 ロールの arn に置き換えます。

AWS DevOps、クラウドアーキテクト

タスク	説明	必要なスキル
GitHub Actions ワークフローをトリガーします。	ワークフローは、変更が機能、メイン、または開発ブランチにプッシュされると自動的にトリガーされます。GitHub UI を使用して手動でトリガーするには: 1。GitHub 2 のリポジトリに移動します。「アクション」タブ 3 をクリックします。ワークフロー (auto-mode-pipeline) を選択します 4。「ワークフローの実行」ボタン 5 をクリックします。ブランチを選択し、「ワークフローの実行」をクリックします。ワークフローは、AWS CLI を使用して移行された各クラスターのコンピューティング設定をクエリすることで、移行後の検証を処理し、EKS Auto Mode が正常に有効になっていることを確認し、現在のコンピューティング設定をテーブル形式で表示します。	AWS DevOps、クラウドアーキテクト

タスク

説明

必要なスキル

GitHub Actions ワークフローをトリガーします。

ワークフローは、変更が機能、メイン、または開発ブランチにプッシュされると自動的にトリガーされます。GitHub UI を使用して手動でトリガーするには: 1。GitHub 2 のリポジトリに移動します。「アクション」タブ 3 をクリックします。ワークフロー (auto-mode-pipeline) を選択します 4。「ワークフローの実行」ボタン 5 をクリックします。ブランチを選択し、「ワークフローの実行」をクリックします。

ワークフローは、AWS CLI を使用して移行された各クラスターのコンピューティング設定をクエリすることで、移行後の検証を処理し、EKS Auto Mode が正常に有効になっていることを確認し、現在のコンピューティング設定をテーブル形式で表示します。

AWS DevOps、クラウドアーキテクト

タスク	説明	必要なスキル
マルチ環境デプロイの実装。	このソリューションは、ブランチベースのデプロイを活用することで、環境固有にすることができます。異なるブランチ (main、dev、feat/*) は、GitHub シークレット (AWS_REGION、AWS_ROLE_ARN、S3_BACKUP_BUCKET) を介して環境固有の設定でワークフローをトリガーします。これにより、すべての環境で一貫した自動化ロジックを維持しながら、環境ごとに個別の AWS リージョン、IAM ロール、クラスターセットが可能になります。

タスク	説明	必要なスキル
リソースをクリーンアップします。	aws-auth ConfigMap から IAM ロールをデタッチするには、次のターミナルコマンドを使用します。 `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 リージョン設定を検証する
アクセス許可の問題	• 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 Actions ログで特定のエラーメッセージを確認する • .github/workflows/auto-mode-pipeline.yml でワークフローファイルの構文を検証する • ワークフローで環境変数が適切に設定されていることを確認します。

問題

ソリューション

認証の問題

• 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 Actions ログで特定のエラーメッセージを確認する

• .github/workflows/auto-mode-pipeline.yml でワークフローファイルの構文を検証する

• ワークフローで環境変数が適切に設定されていることを確認します。