Push image to ECR and deploy to ECS
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. Visit the 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 to create these resources. To use these scripts, follow the steps below.
- Create an AWS account.
- Install Terraform.
- Clone the sample project and go to its root directory.
- Update
~/terraform_setup/terraform.tfvars
with real values for the AWS variables. For more details, see the Configure CircleCI environment variables section below. - Create the AWS resources by running the following commands.
cd terraform_setup
terraform init
terraform plan # review the plan
terraform apply # apply the plan and create AWS resources
terraform destroy
. If any resources remain, check the AWS Management Console, 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.
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. |
AWS_RESOURCE_NAME_PREFIX | Prefix for some required AWS resources. Should 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
. Follow the steps below to create a complete config.yml
file.
Note: The sample project described in this section makes use of the CircleCI AWS-ECR and AWS-ECS orbs, which can be found here:
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.
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 (i.e. root of the checkout directory) and pushes it to the specified ECR repository.
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 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, and deploys the new task definition to the specified ECS service. If you would like more information about the CircleCI AWS-ECS orb, go to: https://circleci.com/developer/orbs/orb/circleci/aws-ecs
Note The deploy-service-update
job depends on build-and-push-image
because of the requires
key.
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 page for more information.
See also
- If you would like to review an example that builds, tests and pushes the Docker image to ECR and then uses the
aws-ecs
orb to deploy the update, go to the AWS-ECS-ECR Orbs demo page. - If you would also like to review an example that does not use CircleCI orbs, go to the Non-Orbs AWS ECR-ECS Demo demo page.
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.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
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.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.