Deploying to Amazon Elastic Container Service

Introduction

This guide explains how to use GitHub Actions to build a containerized application, push it to Amazon Elastic Container Registry (ECR), and deploy it to Amazon Elastic Container Service (ECS) when there is a push to the main branch.

On every new push to main in your GitHub repository, the GitHub Actions workflow builds and pushes a new container image to Amazon ECR, and then deploys a new task definition to Amazon ECS.

Prerequisites

Before creating your GitHub Actions workflow, you will first need to complete the following setup steps for Amazon ECR and ECS:

1. Create an Amazon ECR repository to store your images.

   For example, using the AWS CLI:

   Shell

   aws ecr create-repository \ --repository-name MY_ECR_REPOSITORY \ --region MY_AWS_REGION

   Ensure that you use the same Amazon ECR repository name (represented here by MY_ECR_REPOSITORY) for the ECR_REPOSITORY variable in the workflow below.

   Ensure that you use the same AWS region value for the AWS_REGION (represented here by MY_AWS_REGION) variable in the workflow below.

2. Create an Amazon ECS task definition, cluster, and service.

   For details, follow the Getting started wizard on the Amazon ECS console, or the Getting started guide in the Amazon ECS documentation.

   Ensure that you note the names you set for the Amazon ECS service and cluster, and use them for the ECS_SERVICE and ECS_CLUSTER variables in the workflow below.

3. Store your Amazon ECS task definition as a JSON file in your GitHub repository.

   The format of the file should be the same as the output generated by:

   Shell

   aws ecs register-task-definition --generate-cli-skeleton

   Ensure that you set the ECS_TASK_DEFINITION variable in the workflow below as the path to the JSON file.

   Ensure that you set the CONTAINER_NAME variable in the workflow below as the container name in the containerDefinitions section of the task definition.

4. Create GitHub Actions secrets named AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to store the values for your Amazon IAM access key.

   For more information on creating secrets for GitHub Actions, see "Encrypted secrets."

   See the documentation for each action used below for the recommended IAM policies for the IAM user, and methods for handling the access key credentials.

5. Optionally, configure a deployment environment. 环境用于描述常规部署目� �，例如 production、staging 或 development。 当 GitHub Actions 工作流部署到某个环境时，该环境将显示在存储库的主页上。 � 可以使用环境来要求批准才能继续作业，限制哪些分支可以触发工作流，或限制对机密的访问。 有关创建环境的详细信息，请参阅“使用环境进行部署”。

Creating the workflow

Once you've completed the prerequisites, you can proceed with creating the workflow.

The following example workflow demonstrates how to build a container image and push it to Amazon ECR. It then updates the task definition with the new image ID, and deploys the task definition to Amazon ECS.

Ensure that you provide your own values for all the variables in the env key of the workflow.

如果配置了部署环境，请将 environment 的值更改为环境的名称。 如果未配置环境 ，请� 除 environment 密钥。

# 此工作流使用未经 GitHub 认证的操作。 # 它们由第三方提供，并受 # 单独的服务条款、隐私政策和支持 # 文档。 # GitHub 建议将操作固定到提交 SHA。 # 若要获取较新版本，需要更新 SHA。 # 还可以引用� �记或分支，但该操作可能会更改而不发出警告。 name: Deploy to Amazon ECS on: push: branches: - main env: AWS_REGION: MY_AWS_REGION # set this to your preferred AWS region, e.g. us-west-1 ECR_REPOSITORY: MY_ECR_REPOSITORY # set this to your Amazon ECR repository name ECS_SERVICE: MY_ECS_SERVICE # set this to your Amazon ECS service name ECS_CLUSTER: MY_ECS_CLUSTER # set this to your Amazon ECS cluster name ECS_TASK_DEFINITION: MY_ECS_TASK_DEFINITION # set this to the path to your Amazon ECS task definition # file, e.g. .aws/task-definition.json CONTAINER_NAME: MY_CONTAINER_NAME # set this to the name of the container in the # containerDefinitions section of your task definition jobs: deploy: name: Deploy runs-on: ubuntu-latest environment: production steps: - name: Checkout uses: actions/checkout@v2 - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@13d241b293754004c80624b5567555c4a39ffbe3 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: ${{ env.AWS_REGION }} - name: Login to Amazon ECR id: login-ecr uses: aws-actions/amazon-ecr-login@aaf69d68aa3fb14c1d5a6be9ac61fe15b48453a2 - name: Build, tag, and push image to Amazon ECR id: build-image env: ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }} IMAGE_TAG: ${{ github.sha }} run: | # Build a docker container and # push it to ECR so that it can # be deployed to ECS. docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG . docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG echo "::set-output name=image::$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG"  - name: Fill in the new image ID in the Amazon ECS task definition id: task-def uses: aws-actions/amazon-ecs-render-task-definition@97587c9d45a4930bf0e3da8dd2feb2a463cf4a3a with: task-definition: ${{ env.ECS_TASK_DEFINITION }} container-name: ${{ env.CONTAINER_NAME }} image: ${{ steps.build-image.outputs.image }} - name: Deploy Amazon ECS task definition uses: aws-actions/amazon-ecs-deploy-task-definition@de0132cf8cdedb79975c6d42b77eb7ea193cf28e with: task-definition: ${{ steps.task-def.outputs.task-definition }} service: ${{ env.ECS_SERVICE }} cluster: ${{ env.ECS_CLUSTER }} wait-for-service-stability: true

Additional resources

For the original starter workflow, see aws.yml in the GitHub Actions starter-workflows repository.

For more information on the services used in these examples, see the following documentation:

• "Security best practices in IAM" in the Amazon AWS documentation.
• Official AWS "Configure AWS Credentials" action.
• Official AWS Amazon ECR "Login" action.
• Official AWS Amazon ECS "Render Task Definition" action.
• Official AWS Amazon ECS "Deploy Task Definition" action.