Deploy service update to AWS ECS

Cloud

Server v4.x

Server v3.x

Introduction

The Amazon Elastic Container Service (ECS) is a scalable container orchestration service that enables you to support Docker containers and allows you to run and scale containerized applications on AWS. By using Amazon ECS, you will be able to use this service without installing and configuring your own container orchestration software, thereby eliminating the complexity of your deployment and ensuring you have a simple and optimized container deployment on the CircleCI platform. This guide shows you how to deploy software changes to Amazon ECS using CircleCI orbs.

1. Set environment variables

The following environment variables need to be set. For more information on how to set environment variables, refer to the Set an environment variable page. You can also use a context:

AWS_ECR_ACCOUNT_URL
MY_APP_PREFIX
AWS_REGION
AWS_ACCESS_KEY_ID

the CIRCLE_SHA1 variable used in this example is built-in, so it is always available.

2. Specify a version

Every CircleCI config.yml starts with the version key. This key is used to issue warnings about breaking changes.

version: 2.1

2.1 is the latest CircleCI version, and it ensures you have access to all our latest features and improvements.

3. Use orbs

In this example you will need to use three orbs in your configuration. Add them at the start of your .circleci/config.yaml, as follows:

orbs:
  aws-ecr: circleci/aws-ecr@9.3.5 # use the AWS ECR orb
  aws-ecs: circleci/aws-ecs@6.0.0 # use the AWS ECS orb
  aws-cli: circleci/aws-cli@5.1.1 # use the AWS CLI orb

When using orbs, it is a good idea to check the Orb Registry to ensure you are using the most recent version, or the version that fits best with your project.

4. Create workflow

A workflow is a set of rules for defining a collection of jobs and their run order. Workflows support complex job orchestration using a set of configuration keys to help you resolve failures sooner. Inside the workflow, you define the jobs you want to run. CircleCI will run this workflow on every commit. Learn more about workflow configuration.

workflows:
  build-and-deploy: # this can be any name you choose

5. Build, push and deploy a service update

To configure an AWS service update to deploy a newly built image from AWS ECR, you can use orbs to keep your configuration as simple as possible:

The build_and_push_image job from the ECR orb to build and push an updated image to ECR
The deploy_service_update from the ECS orb to deploy your service update

workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image: # orb built-in job
          repo: '${MY_APP_PREFIX}'
          tag: '${CIRCLE_SHA1}'
      - aws-ecs/deploy_service_update: # orb built-in job
          requires:
            - aws-ecr/build_and_push_image
          family: '${MY_APP_PREFIX}-service'
          cluster: '${MY_APP_PREFIX}-cluster'
          container-image-name-updates: 'container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1}'

For a full list of usage options and orb elements see the AWS-ECS orb page in the CircleCI orbs registry.

6. Verify the deployment

Once you have updated the Amazon ECS service, you can verify the update was correctly applied. To keep your config as simple as possible, use the AWS CLI and ECS orbs. This time, rather than using an orb’s built-in job to perform the required process, commands from the orbs are used as steps in a newly-defined job named verify-deployment.

jobs:
  verify-deployment:
    executor: aws-cli/default
    steps:
      - aws-cli/install
      - aws-cli/setup:
          aws_access_key_id: AWS_SECRET_ACCESS_KEY
          region: AWS_DEFAULT_REGION
          aws_secret_access_key: AWS_DEFAULT_REGION
      - run:
          name: Get last task definition
          command: >
            TASK_DEFINITION_ARN=$(aws ecs describe-task-definition \
                --task-definition ${MY_APP_PREFIX}-service \
                --output text \
                --query 'taskDefinition.taskDefinitionArn')
            echo "export TASK_DEFINITION_ARN='${TASK_DEFINITION_ARN}'" >>
            "$BASH_ENV"
      - aws-ecs/verify_revision_is_deployed:
          family: '${MY_APP_PREFIX}-service'
          cluster: '${MY_APP_PREFIX}-cluster'
          task_definition_arn: '${TASK_DEFINITION_ARN}'

This section illustrates how you can use the orb to install and configure the AWS CLI, retrieve the task definition that was previously deployed, and then verify the revision has been deployed using the verify-revision-is-deployed command from the AWS-ECS orb.

7. Add verification job to the workflow

Now that we have our verification job, verify-deployment, we can add it to our build-and-deploy workflow and ensure it runs sequentially, after the build and deploy jobs using the requires key.

workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image: # orb built-in job
          repo: '${MY_APP_PREFIX}'
          tag: '${CIRCLE_SHA1}'
      - aws-ecs/deploy_service_update: # orb built-in job
          requires:
            - aws-ecr/build_and_push_image
          family: '${MY_APP_PREFIX}-service'
          cluster: '${MY_APP_PREFIX}-cluster'
          container-image-name-updates: 'container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1}'
      - verify-deployment:
          requires:
            - aws-ecs/deploy_service_update

Full config.yml

version: 2.1 # 2.1 config required to use orbs

orbs:
  aws-ecr: circleci/aws-ecr@9.3.5 # use the AWS ECR orb
  aws-ecs: circleci/aws-ecs@6.0.0 # use the AWS ECS orb
  aws-cli: circleci/aws-cli@5.1.1 # use the AWS CLI orb

jobs:
  verify-deployment:
    executor: aws-cli/default
    steps:
      - aws-cli/install
      - aws-cli/setup:
          aws_access_key_id: AWS_SECRET_ACCESS_KEY
          region: AWS_DEFAULT_REGION
          aws_secret_access_key: AWS_DEFAULT_REGION
      - run:
          name: Get last task definition
          command: >
            TASK_DEFINITION_ARN=$(aws ecs describe-task-definition \
                --task-definition ${MY_APP_PREFIX}-service \
                --output text \
                --query 'taskDefinition.taskDefinitionArn')
            echo "export TASK_DEFINITION_ARN='${TASK_DEFINITION_ARN}'" >>
            "$BASH_ENV"
      - aws-ecs/verify_revision_is_deployed:
          family: '${MY_APP_PREFIX}-service'
          cluster: '${MY_APP_PREFIX}-cluster'
          task_definition_arn: '${TASK_DEFINITION_ARN}'

workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image: # orb built-in job
          repo: '${MY_APP_PREFIX}'
          tag: '${CIRCLE_SHA1}'
      - aws-ecs/deploy_service_update: # orb built-in job
          requires:
            - aws-ecr/build_and_push_image
          family: '${MY_APP_PREFIX}-service'
          cluster: '${MY_APP_PREFIX}-cluster'
          container-image-name-updates: 'container=${MY_APP_PREFIX}-service,tag=${CIRCLE_SHA1}'
      - verify-deployment:
          requires:
            - aws-ecs/deploy_service_update