aws-cloudformation-task-ecs-deploy-gh

使用 GitHub Actions 部署 AWS CloudFormation 任务 ECS

全面介绍如何使用 GitHub Actions CI/CD 管道部署 ECS 容器，并通过 CloudFormation 管理基础设施。

概述

使用 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)

请参阅 references/workflow-examples.md，了解其他模式，包括 ECR 生命周期策略、任务定义模板和 CloudFormation 堆栈更新。

最佳实践

安全性

1. 使用 OIDC 身份验证，而非长期有效的 IAM 密钥
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 - 完整的 GitHub Actions 工作流，包括基本部署、多环境、蓝绿部署和 CI/CD 流水线

配置

• 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 之间的数据传输费用