Skip to content
Docs
Cancel

Deploy service update to AWS ECS

Last updated
Tags Cloud Server v3.x

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 Using Environment Variables 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@8.1.2 # use the AWS ECR orb
  aws-ecs: circleci/aws-ecs@2.1.1 # use the AWS ECS orb
  aws-cli: circleci/aws-cli@3.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-name: '${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/configure:
          aws-access-key-id: $AWS_ACCESS_KEY_ID
          aws-region: $AWS_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-name: '${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-name: '${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@2.1.1 # 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/configure:
          aws-access-key-id: $AWS_ACCESS_KEY_ID
          aws-region: $AWS_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-name: '${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-name: '${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.

Creative Commons License
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

6,000 Minutes Free

CircleCI, now with more build minutes
than anyone else for FREE 🎉

Sign up for Free

These teams get it

CCI customer teams