> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Deploy service update to AWS ECS

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](https://circleci.com/docs/guides/security/set-environment-variable/) page. You can also use a [Context](https://circleci.com/docs/guides/security/contexts/):

*   `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.

```yaml
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:

```yaml
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](https://circleci.com/developer/orbs) 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](https://circleci.com/docs/reference/configuration-reference/#workflows).

```yaml
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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/update-service.html) 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.
    

```yaml
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](https://circleci.com/developer/orbs/orb/circleci/aws-ecs) 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`.

```yaml
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](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) 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 you have our verification job, `verify-deployment`, you can add it to our `build-and-deploy` workflow and ensure it runs sequentially, after the build and deploy jobs using the `requires` key.

```yaml
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

```yaml
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](https://circleci.com/docs/guides/deploy/set-up-rollbacks/) or [Deploy Pipeline](https://circleci.com/docs/guides/deploy/set-up-deploys/). 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](https://circleci.com/docs/guides/deploy/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](https://circleci.com/developer/orbs/orb/circleci/aws-ecs) and [AWS ECR](https://circleci.com/developer/orbs/orb/circleci/aws-ecr) orbs.