Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Deploy service update to AWS ECS

4 days ago2 min read
Cloud
Server v4.x
Server v3.x
On This Page

Overview

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

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

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@8.1.2 # use the AWS ECR orb
  aws-ecs: circleci/aws-ecs@3.2.0 # use the AWS ECS orb
  aws-cli: circleci/aws-cli@3.1.1 # use the AWS CLI orb

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
          aws-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@8.1.2 # use the AWS ECR orb
  aws-ecs: circleci/aws-ecs@3.2.0 # use the AWS ECS orb
  aws-cli: circleci/aws-cli@3.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
          aws-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

Next steps

  • Find more detailed information in the CircleCI orb Registry for the CircleCI AWS ECS and AWS ECR orbs.


Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.