Documentation structure for LLMs (llms.txt)
CircleCI Logo

Deploy service update to AWS ECS

3 days ago
Cloud Server v4+

In this how-to guide, you will learn how to configure CircleCI to deploy to AWS ECS using CircleCI orbs.

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 not need to configure and install your own container orchestration software, 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
          auth:
            - aws-cli/setup:
                role_arn: arn:aws:iam::123456789012
          repo: '${MY_APP_PREFIX}'
          tag: '${CIRCLE_SHA1}'
      - aws-ecs/deploy_service_update: # orb built-in job
          requires:
            - aws-ecr/build_and_push_image
          auth:
            - aws-cli/setup:
                role_arn: arn:aws:iam::123456789012
          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/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.

  • 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
          auth:
            - aws-cli/setup:
                role_arn: arn:aws:iam::123456789012
          repo: '${MY_APP_PREFIX}'
          tag: '${CIRCLE_SHA1}'
      - aws-ecs/deploy_service_update: # orb built-in job
          requires:
            - aws-ecr/build_and_push_image
          auth:
            - aws-cli/setup:
                role_arn: arn:aws:iam::123456789012
          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/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}'
          auth:
            - aws-cli/setup:
                role_arn: arn:aws:iam::123456789012
      - aws-ecs/deploy_service_update: # orb built-in job
          requires:
            - aws-ecr/build_and_push_image
          auth:
            - aws-cli/setup:
                role_arn: arn:aws:iam::123456789012
          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

Track your deployments with deploy markers

Deploy markers provide a way to track and manage your AWS ECS service updates in the CircleCI web app. When you add deploy markers to your deployment job, you can view a timeline of all deployments, track their status, and enable rollback and deploy pipelines.

You have two options for setting up deploy markers:

  • In-app setup: Use the guided setup in the CircleCI web app when configuring a Rollback Pipeline or Deploy Pipeline. The setup will walk you through adding deploy markers to your configuration. If you are using GitHub and have the CircleCI GitHub App installed, you can use AI to generate the deploy marker configuration automatically.

  • Manual setup: Add deploy marker commands directly to your .circleci/config.yml file by following the Configure Deploy Markers guide.

Both approaches will enable you to track deployment history and manage rollbacks directly from the CircleCI web app.

Next steps

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