Deploying to AWS ECR/ECS

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

• Overview
• Prerequisites
  • Use Terraform to Create AWS Resources
  • Configure CircleCI Environment Variables
• Configuration Walkthrough
  • Build and Push the Docker image to AWS ECR
  • Deploy the new Docker image to an existing AWS ECS service
  • Set Up a Workflow
• Full Configuration File
• See Also

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.

You can also find the application building on CircleCI.

Note: This project includes a simple Dockerfile.

See Creating a Custom Image Manually for more information.

Prerequisites

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.

1. Create an AWS account.
2. Install Terraform.
3. Clone the sample project 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 section below.
5. 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

Note: You can destroy most AWS resources by running terraform destroy. If any resources remain, check the AWS Management Console, particularly the ECS, CloudFormation and VPC pages.

Configure CircleCI Environment Variables

In the CircleCI application, set the following project environment variables.

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:

• [AWS-ECR]https://circleci.com/orbs/registry/orb/circleci/aws-ecr
• [AWS-ECS]https://circleci.com/orbs/registry/orb/circleci/aws-ecs

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@0.0.2
  aws-ecs: circleci/aws-ecs@0.0.3
workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image:
          account-url: "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com"
          repo: "${AWS_RESOURCE_NAME_PREFIX}"
          region: ${AWS_DEFAULT_REGION}
          tag: "${CIRCLE_SHA1}"
      - ...

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/orbs/registry/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@0.0.2
  aws-ecs: circleci/aws-ecs@0.0.3
workflows:
  build-and-deploy:
    jobs:
      - ...
      - aws-ecs/deploy-service-update:
          requires:
            - aws-ecr/build_and_push_image
          aws-region: ${AWS_DEFAULT_REGION}
          family: "${AWS_RESOURCE_NAME_PREFIX}-service"
          cluster-name: "${AWS_RESOURCE_NAME_PREFIX}-cluster"
          container-image-name-updates: "container=${AWS_RESOURCE_NAME_PREFIX}-service,tag=${CIRCLE_SHA1}"

Set Up a Workflow

Use workflows to link the build_and_push_image and deploy-service-update jobs.

version: 2.1
orbs:
  aws-ecr: circleci/aws-ecr@0.0.2
  aws-ecs: circleci/aws-ecs@0.0.3
workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image:
          account-url: "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com"
          repo: "${AWS_RESOURCE_NAME_PREFIX}"
          region: ${AWS_DEFAULT_REGION}
          tag: "${CIRCLE_SHA1}"
      - aws-ecs/deploy-service-update:
          requires:
            - aws-ecr/build_and_push_image
          aws-region: ${AWS_DEFAULT_REGION}
          family: "${AWS_RESOURCE_NAME_PREFIX}-service"
          cluster-name: "${AWS_RESOURCE_NAME_PREFIX}-cluster"
          container-image-name-updates: "container=${AWS_RESOURCE_NAME_PREFIX}-service,tag=${CIRCLE_SHA1}"

See the Using Workflows to Schedule Jobs for more information.

Full Configuration File

version: 2.1
orbs:
  aws-ecr: circleci/aws-ecr@0.0.2
  aws-ecs: circleci/aws-ecs@0.0.3
workflows:
  build-and-deploy:
    jobs:
      - aws-ecr/build_and_push_image:
          account-url: "${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_DEFAULT_REGION}.amazonaws.com"
          repo: "${AWS_RESOURCE_NAME_PREFIX}"
          region: ${AWS_DEFAULT_REGION}
          tag: "${CIRCLE_SHA1}"
      - aws-ecs/deploy-service-update:
          requires:
            - aws-ecr/build_and_push_image
          aws-region: ${AWS_DEFAULT_REGION}
          family: "${AWS_RESOURCE_NAME_PREFIX}-service"
          cluster-name: "${AWS_RESOURCE_NAME_PREFIX}-cluster"
          container-image-name-updates: "container=${AWS_RESOURCE_NAME_PREFIX}-service,tag=${CIRCLE_SHA1}"

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.