aws-cloudformation-task-ecs-deploy-gh

GitHub Actions を使用した AWS CloudFormation タスク ECS デプロイ

CloudFormation によるインフラストラクチャ管理と GitHub Actions CI/CD パイプラインを使用して、ECS コンテナをデプロイするための包括的なスキルです。

概要

GitHub Actions のワークフローを使用して、コンテナ化されたアプリケーションを Amazon ECS にデプロイします。このスキルでは、デプロイパイプライン全体を取り上げます。AWS による認証（OIDC を推奨）、Docker イメージのビルド、Amazon ECR へのプッシュ、タスク定義の更新、ECS サービスのデプロイを行います。CloudFormation と連携してインフラストラクチャ・アズ・コードを管理し、本番環境向けのデプロイ戦略を実装します。

使用する場面

• GitHub Actions を使用して Docker コンテナを Amazon ECS にデプロイする場合
• CloudFormation を使用して ECS の CI/CD パイプラインを設定する場合
• GitHub Actions 用に AWS OIDC 認証を設定する場合
• Docker イメージをビルドして Amazon ECR にプッシュする場合
• CI/CD で ECS タスク定義を動的に更新する場合
• ECS にブルー／グリーンデプロイまたはローリングデプロイを実装する場合
• GitHub Actions から CloudFormation スタックを管理する場合

手順

GitHub Actions で ECS デプロイを設定するには、次の手順に従います。

1. AWS 認証を設定する：GitHub Actions 用の OIDC プロバイダーを設定します
2. IAM ロールを作成する：デプロイ操作用のロールを定義します
3. ECR リポジトリを設定する：イメージスキャンを有効にしたリポジトリを作成します
4. ECS クラスターを作成する：クラスターのインフラストラクチャを定義します
5. タスク定義を設定する：タスクとコンテナの定義を設定します
6. ECS サービスを設定する：デプロイ戦略を指定してサービスを設定します
7. GitHub ワークフローを作成する：CI/CD パイプラインの手順を定義します
8. シークレットを設定する：認証情報を GitHub Secrets に安全に保存します

クイックスタート

基本的なデプロイワークフロー

name: Deploy to ECS
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-ecs-role
          aws-region: us-east-1

      - name: Login to ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build and push image
        env:
          ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
          ECR_REPOSITORY: my-app
          IMAGE_TAG: ${{ github.sha }}
        run: |
          docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
          docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

      - name: Verify image push
        run: |
          docker pull $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
          echo "Image $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG verified"

      - name: Update task definition
        uses: aws-actions/amazon-ecs-render-task-definition@v1
        id: render-task
        with:
          task-definition: task-definition.json
          container-name: my-app
          image: ${{ steps.login-ecr.outputs.registry }}/my-app:${{ github.sha }}

      - name: Validate task definition
        run: |
          # Validate JSON syntax
          cat ${{ steps.render-task.outputs.task-definition }} | jq empty && echo "Task definition JSON is valid"
          # Verify container image matches expected
          CONTAINER_IMAGE=$(cat ${{ steps.render-task.outputs.task-definition }} | jq -r '.containerDefinitions[0].image')
          EXPECTED_IMAGE="${{ steps.login-ecr.outputs.registry }}/my-app:${{ github.sha }}"
          if [ "$CONTAINER_IMAGE" = "$EXPECTED_IMAGE" ]; then
            echo "Container image matches expected: $CONTAINER_IMAGE"
          else
            echo "ERROR: Container image mismatch. Expected: $EXPECTED_IMAGE, Got: $CONTAINER_IMAGE"
            exit 1
          fi

      - name: Deploy to ECS
        uses: aws-actions/amazon-ecs-deploy-task-definition@v1
        with:
          task-definition: ${{ steps.render-task.outputs.task-definition }}
          service: my-service
          cluster: my-cluster
          wait-for-service-stability: true

マルチ環境やブルー／グリーンデプロイを含むワークフローの完全な例については、references/workflow-examples.mdを参照してください。

例

マルチ環境デプロイ

jobs:
  deploy:
    strategy:
      matrix:
        environment: [dev, staging, prod]
    steps:
      - uses: actions/checkout@v4
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::${{ matrix.env_account }}:role/github-actions-ecs-role
          aws-region: ${{ matrix.region }}
      - name: Deploy to ${{ matrix.environment }}
        run: |
          ECR_REGISTRY=${{ env.ECR_REGISTRY }}
          docker build -t $ECR_REGISTRY/my-app:${{ github.sha }} .
          docker push $ECR_REGISTRY/my-app:${{ github.sha }}

CodeDeploy を使用したブルー／グリーンデプロイ

- name: Deploy with CodeDeploy
  run: |
    aws deploy create-deployment \
      --application-name my-app \
      --deployment-group-name ${{ matrix.environment }} \
      --deployment-config-name CodeDeployDefault ECSAllAtOnce \
      --revision "{\"revisionType\":\"AppSpecContent\",\"appSpecContent\":{\"content\":\"$(cat appspec.yml)\",\"filename\":\"appspec.yml\"}}"
    aws deploy wait deployment-successful --deployment-id $(aws deploy list-deployments --application-name my-app --query 'deployments[0]' --output text)

ECR のライフサイクルポリシー、タスク定義テンプレート、CloudFormation スタックの更新など、追加のパターンについてはreferences/workflow-examples.mdを参照してください。

ベストプラクティス

セキュリティ

1. 長期有効な IAM キーの代わりに、OIDC 認証を使用します
2. 最小権限の IAM ロールを実装し、権限を具体的に設定します
3. プッシュ時のECR イメージスキャンを有効にします
4. 機密データにはAWS Secrets Manager を使用します
5. KMS でECR リポジトリを暗号化します
6. インターネットゲートウェイを経由しない ECR および ECS 用のVPC エンドポイントを使用します
7. セキュリティグループでアクセスを必要最小限に制限します

パフォーマンス

1. GitHub Actions キャッシュを使用してDocker レイヤーをキャッシュします
2. イメージサイズを最小限にするためにマルチステージビルドを使用します
3. 複数の環境への並列デプロイを行います
4. 重要度の低いワークロードでは、コスト削減のためにFargate Spot を使用します
5. 適切な保持ポリシーを設定してCloudWatch Logs を使用します

コストの最適化

1. 古いイメージを削除するためにECR ライフサイクルポリシーを使用します
2. 開発／テスト環境ではFargate Spot インスタンスを使用します
3. タスクの CPU とメモリを適切なサイズに設定します
4. メトリクスに基づいてオートスケーリングを行います
5. 予測可能なトラフィックパターンに合わせてスケジュールされたスケーリングを行います

セキュリティ、パフォーマンス、コスト最適化に関する詳しいガイドラインは、references/best-practices.mdを参照してください。

よくあるトラブルシューティング

認証の失敗

• OIDC の信頼関係が GitHub の組織／リポジトリと一致していることを確認します
• IAM ロールに ECR と ECS 用の適切な権限があることを確認します
• GitHub Actions リポジトリに id-token: write 権限が設定されていることを確認します

デプロイの失敗

• アプリケーションのエラーについて CloudWatch Logs を確認します
• タスク定義がサービスの要件と一致していることを確認します
• Fargate クラスターに十分な CPU とメモリがあることを確認します
• ヘルスチェックの設定を確認します

ECR へのプッシュの失敗

• リポジトリが存在し、権限が正しく設定されていることを確認します
• イメージタグの形式とレジストリ URL を確認します
• GitHub Actions ランナーで Docker デーモンが起動していることを確認します
• イメージサイズが ECR の制限を超えていないことを確認します

CloudFormation のロールバック

• AWS コンソールでスタックイベントを確認します
• パラメーター値がリソースの制約に適合していることを確認します
• IAM ロールに cloudformation:UpdateStack の権限があることを確認します
• 本番スタックでは削除保護を有効にします

デバッグコマンドを含む完全なトラブルシューティングガイドについては、references/best-practices.md を参照してください。

関連スキル

• aws-cloudformation-ecs - ECS クラスターアーキテクチャを設計、実装します
• aws-cloudformation-lambda - GitHub Actions で Lambda 関数をデプロイします
• aws-cloudformation-security - ECS デプロイのセキュリティに関するベストプラクティス

参考資料

完全な例

• references/workflow-examples.md - 基本的なデプロイ、複数環境、ブルー／グリーン、CI/CD パイプラインを含む GitHub Actions ワークフローの完全な例

設定

• references/authentication.md - OIDC プロバイダーのセットアップ、IAM ロール、クロスアカウントデプロイ、環境ごとのロール
• references/ecr-and-task-definitions.md - ECR リポジトリの設定、タスク定義の管理、複数コンテナのセットアップ
• references/deployment-strategies.md - ローリングデプロイとブルー／グリーンデプロイ、CloudFormation テンプレート、スタックの更新

ベストプラクティス

• references/best-practices.md - セキュリティガイドライン、パフォーマンスの最適化、コストの最適化、モニタリング、完全なトラブルシューティングガイド

制約と警告

リソースの制限

• GitHub Actions の制限：アカウントごとの使用量制限（実行時間、ストレージ）
• ワークフローファイルのサイズ：1 MB を超えることはできません
• ジョブマトリックスの制限：マトリックスの組み合わせ総数に上限があります
• アーティファクトの保持期間：デフォルトの保持期間は 90 日です

認証の制約

• OIDC トークン：有効期間に制限があります（通常は 5 分）
• ロールセッションの期間：最大 12 時間
• 権限の範囲：最小権限の権限が必要です
• クロスアカウントアクセス：適切な信頼関係が必要です

運用上の制約

• デプロイ速度：CloudFormation のデプロイには時間がかかる場合があります
• スタックのロック：別のデプロイが進行中の場合、更新できません
• ECR のレート制限：API のレート制限により、大規模なデプロイに影響が出る場合があります
• ECS サービスの制限：サービスあたりのタスク数とクラスターあたりのサービス数に上限があります

セキュリティ上の制約

• シークレットの管理：リポジトリやワークフローファイルにシークレットを保存しないでください
• OIDC プロバイダー：初回使用前に AWS アカウントで設定する必要があります
• リポジトリへのアクセス：ワークフローのシークレットはリポジトリごとに適用されます
• トークンのセキュリティ：必要最小限の権限のみを付与します（contents: read、id-token: write）

コストに関する考慮事項

• GitHub Actions：無料枠を超える実行時間には費用が発生します
• ECR ストレージ：コンテナイメージの月額ストレージ料金
• ECS/Fargate：vCPU とメモリリソースの費用
• データ転送：GitHub と AWS 間のデータ転送費用