---
title: "Push image to AWS ECR and deploy to AWS ECS"
description: "Build and push a Docker image to AWS ECR, then deploy it to an existing AWS ECS service using CircleCI and a sample project with Terraform."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-15"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Push image to AWS ECR and deploy to AWS ECS

This page is outdated. CircleCI is working on a new updated sample project. The information on this page is still relevant, but the sample project will be replaced.

This document describes how to use CircleCI to deploy to Amazon Elastic Container Service (ECS) from Amazon Elastic Container Registry (ECR).

## Overview

This guide has two phases:

*   Building and pushing a Docker image to AWS ECR.
    
*   Deploying the new Docker image to an existing AWS ECS service.
    

This project includes a simple [Dockerfile](https://github.com/CircleCI-Public/circleci-demo-aws-ecs-ecr/blob/master/Dockerfile). Visit the [Creating a Custom Image Manually](https://circleci.com/docs/guides/server/execute/custom-images/#creating-a-custom-image-manually) page for more information.

## Prerequisites

### 1\. Use Terraform to create AWS resources

Several AWS resources are required to build and deploy the application in this guide. CircleCI provides [several Terraform scripts](https://github.com/CircleCI-Public/circleci-demo-aws-ecs-ecr/tree/master/terraform_setup) to create these resources. To use these scripts, follow the steps below.

1.  [Create an AWS account](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/).
    
2.  [Install Terraform](https://www.terraform.io/).
    
3.  Clone the [sample project](https://github.com/CircleCI-Public/circleci-demo-aws-ecs-ecr) and go to its root directory.
    
4.  Update `~/terraform_setup/terraform.tfvars` with real values for the AWS variables. For more details, see the [Configure CircleCI environment variables](#configure-circleci-environment-variables) section below.
    
5.  Create the AWS resources by running the following commands.
    

```shell
cd terraform_setup
terraform init
terraform plan  # review the plan
terraform apply  # apply the plan and create AWS resources
```

You can destroy most AWS resources by running `terraform destroy`. If any resources remain, check the [AWS Management Console](https://console.aws.amazon.com/), particularly the **ECS**, **CloudFormation** and **VPC** pages. If `apply` fails, check that the user has permissions for EC2, Elastic Load Balancing, and IAM services.

### 2\. Configure CircleCI environment variables

In the CircleCI application, set the following [Project Environment Variables](https://circleci.com/docs/guides/server/security/set-environment-variable/#set-an-environment-variable-in-a-project).

| Variable | Description |
| --- | --- |
| AWS\_ACCESS\_KEY\_ID | Security credentials for AWS. |
| AWS\_SECRET\_ACCESS\_KEY | Security credentials for AWS. |
| AWS\_REGION | Used by the AWS CLI. |
| AWS\_ACCOUNT\_ID | Required for deployment. [Find your AWS Account ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/console_account-alias.html#FindingYourAWSId). |
| AWS\_RESOURCE\_NAME\_PREFIX | Prefix for some required AWS resources. Must correspond to the value of `aws_resource_prefix` in `terraform_setup/terraform.tfvars`. |
| AWS\_ECR\_REGISTRY\_ID | The 12 digit AWS id associated with the ECR account. |

## Configuration walkthrough

Every CircleCI project requires a configuration file called [`.circleci/config.yml`](https://circleci.com/docs/reference/configuration-reference/). Follow the steps below to create a complete `config.yml` file.

The sample project described in this section makes use of the CircleCI AWS-ECR and AWS-ECS orbs. You can find them in the CircleCI developer hub using the following links:

*   [AWS-ECR](https://circleci.com/developer/orbs/orb/circleci/aws-ecr)
    
*   [AWS-ECS](https://circleci.com/developer/orbs/orb/circleci/aws-ecs)
    

Notice the orbs are versioned with tags, for example, `aws-ecr: circleci/aws-ecr@x.y.z`. If you copy paste any examples you will need to edit `x.y.z` to specify a version. You can find the available versions listed on the individual orb pages in the [CircleCI Orbs Registry](https://circleci.com/developer/orbs).

### 1\. Build and push the Docker image to AWS ECR

The `build-and-push-image` job builds a Docker image from a Dockerfile in the default location (that is, the root of the checkout directory) and pushes it to the specified ECR repository.

```yaml
version: 2.1

orbs:
  aws-ecr: circleci/aws-ecr@x.y.z
  aws-ecs: circleci/aws-ecs@0x.y.z

workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build-and-push-image:
          repo: "${AWS_RESOURCE_NAME_PREFIX}"
          tag: "${CIRCLE_SHA1}"
```

### 2\. Deploy the new Docker image to an existing AWS ECS service

The `deploy-service-update` job of the AWS-ECS orb completes the following:

*   Creates a new task definition that is based on the current task definition, but with the new Docker image specified in the task definition’s container definitions.
    
*   Deploys the new task definition to the specified ECS service.
    

If you would like more information about the CircleCI AWS-ECS orb, go to the [CircleCI AWS-ECS orb](https://circleci.com/developer/orbs/orb/circleci/aws-ecs) page on the developer hub.

The `deploy-service-update` job depends on `build-and-push-image` because of the `requires` key.

```yaml
version: 2.1

orbs:
  aws-ecr: circleci/aws-ecr@x.y.z
  aws-ecs: circleci/aws-ecs@0x.y.z

workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build-and-push-image:
          repo: "${AWS_RESOURCE_NAME_PREFIX}"
          tag: "${CIRCLE_SHA1}"
      - aws-ecs/deploy-service-update:
          requires:
            - aws-ecr/build-and-push-image # only run this job once aws-ecr/build-and-push-image has completed
          family: "${AWS_RESOURCE_NAME_PREFIX}-service"
          cluster: "${AWS_RESOURCE_NAME_PREFIX}-cluster"
          container-image-name-updates: "container=${AWS_RESOURCE_NAME_PREFIX}-service,tag=${CIRCLE_SHA1}"
```

Note the use of Workflows to define job run order/concurrency. See the [Using Workflows to Orchestrate Jobs](https://circleci.com/docs/guides/server/orchestrate/workflows/) page for more information.

## See also

*   Go to the [AWS-ECS-ECR Orbs](https://github.com/CircleCI-Public/circleci-demo-aws-ecs-ecr/tree/orbs) demo page to review an example that builds, tests, and pushes the Docker image to ECR. It then uses the `aws-ecs` orb to deploy the update.
    
*   If you would also like to review an example that does **not** use CircleCI orbs, go to the [non-orb AWS ECR-ECS demo](https://github.com/CircleCI-Public/circleci-demo-aws-ecs-ecr/tree/without_orbs) page.