Automatically deploy private Docker images to Amazon ECR
DevOps Engineer at Andela
This article is an introduction to using an automated CI/CD pipeline to build and push production-grade Docker images to the Amazon Elastic Container Registry (ECR) for storage.
To follow along, you will need a free CircleCI account and an AWS account.
What is Amazon ECR?
Amazon ECR is a fully-managed, private Docker container registry that makes it easy for developers to store, manage, and deploy Docker container images. Amazon ECR integrates seamlessly with Amazon Elastic Container Service (Amazon ECS) and Amazon Elastic Kubernetes Service (Amazon EKS). Amazon ECR can also be used with other cloud vendors.
Why would you want to use a private Docker registry like Amazon ECR?
- In many circumstances, it is desirable to segregate the development, test, and production registries.
- It’s fully managed, which eliminates the need to operate your own container repositories or worry about scaling the underlying infrastructure.
- It’s secure. A private container registry with scanning capabilities and role-based access control offers more security, governance (IAM), and efficient management. It transfers your container images over HTTPS and automatically encrypts your images at rest.
- Running registries close to the systems running the containers cuts deployment latency and reduces exposure to network outages.
Developers use registries to store images created during the application development process. Continuous integration pipelines can automate the process of both building container images and pushing these artifacts into Amazon ECR, making development faster and more efficient.
Imagine a pipeline where you push a commit that triggers a build on CircleCI, which then pushes a new image into Amazon ECR. Amazon ECR can then emit an Amazon EventBridge event that triggers a deployment, without any manual steps required.
Registries make it much easier to build a fully automated pipeline like this. Container images stored in the registry can then be used in various phases of development.
In a few steps, we are going to containerize a simple Node.js application, build the image, and push it to Amazon ECR, all in an automated CircleCI workflow. We’ll use CircleCI orbs to keep our pipeline configuration minimal and easy to understand.
Setting up Amazon ECR
From the AWS management console, select IAM. This service lets you manage access to AWS resources.
In the IAM console, go to IAM users and click Create user. I called mine ci-cd-ecr, but any name will work.
Next, set permissions for the user. Click Attach policies directly and select AmazonEC2ContainerRegistryFullAccess. This policy lets the pipeline create a private repository for the image and push images to it. For production pipelines, consider a custom policy that grants only the Amazon ECR actions the pipeline needs.
Finally, review the details and click Create user.
Because we need the new user to programmatically access AWS resources, we need to create an access key. Click the username of the new user, open the Security credentials tab, and click Create access key. On the Access key best practices & alternatives page, choose Other and click Next. Optionally, add a description tag, then click Create access key.
Once you are done, a banner warns that this is the only time the secret access key can be viewed or downloaded, and the page shows the user’s credentials. This page is only displayed once, so make a note of the Access key and the Secret access key which will be used later on. Alternatively, you can download the provided .csv file, which contains the same credentials.
Note: Long-lived access keys are the quickest way to get started. For production pipelines, consider using OpenID Connect (OIDC) instead, so CircleCI can assume an IAM role without storing any AWS keys.
Setting up a CircleCI pipeline using the AWS-ECR orb
The code for this demo is available on GitHub. Clone the application using the following command:
git clone https://github.com/CIRCLECI-GWP/circleci-ecr-app-demo
Find the CircleCI config.yml file in the .circleci/ folder. Using orbs, as you’ll see, you can build an image and push it to Amazon ECR using only 16 lines of config! The aws-ecr orb comes prepackaged with commands to:
- Build an image
- Log in to Amazon ECR
- Create an Amazon ECR repo, if one doesn’t exist
- Push an image to Amazon ECR
Here is the full config for your pipeline:
version: 2.1
orbs:
aws-cli: circleci/aws-cli@5.4.2
aws-ecr: circleci/aws-ecr@10.0.0
workflows:
build_and_push_image:
jobs:
- aws-ecr/build_and_push_image:
context: aws-dev
auth:
- aws-cli/setup
create_repo: true
dockerfile: Dockerfile
path: .
repo: circleci-ecr-app-demo
tag: "$CIRCLE_SHA1"
This configuration file uses the Amazon Elastic Container Registry orb to build and deploy your Docker image. The auth step uses the aws-cli/setup command from the AWS CLI orb to configure the AWS credentials from the context before the aws-ecr orb logs in to Amazon ECR. The dockerfile: command specifies the path to your Dockerfile. The demo repo uses the following Dockerfile:
# Set the base image to use for subsequent instructions
FROM node:24-alpine
# Add metadata to an image
LABEL app="simple-node-application"
# Directive to set environmental variables key to value pair
ENV NPM_CONFIG_LOGLEVEL=warn
# Set the working directory for any subsequent ADD, COPY, CMD, ENTRYPOINT,
# or RUN instructions that follow it in the Dockerfile
WORKDIR /usr/src/app
# Copy files or folders from source to the dest path in the image's filesystem.
COPY package.json /usr/src/app/
COPY . /usr/src/app/
# Execute any commands on top of the current image as a new layer and commit the results.
RUN npm install --omit=dev
# Define the network ports that this container will listen on at runtime.
EXPOSE 3000
# Configure the container to be run as an executable.
ENTRYPOINT ["npm", "start"]
Adding credentials and environment variables for Amazon ECR
CircleCI contexts allow you to securely store credentials and share them across projects. Since we will need our AWS credentials to deploy our container image, we’ll first need to set up our context.
In the CircleCI dashboard, click Org in the sidebar to open the organization settings. Next, select Contexts. Click Create context and add a unique name for your Context. The Context appears in a list with Security set to All members to indicate that anyone in your organization can access this Context at runtime. As specified in the .circleci/config.yml configuration for this tutorial, the Context name should be aws-dev.
Next, select the aws-dev context.
In the Environment variables section, click Add. Enter the variable name and value you want to associate with this context. Click Add environment variable in the dialog to save. The aws-dev context requires these four environment variables:
AWS_ACCESS_KEY_IDis the AWS access key ID for theci-cd-ecrIAM user created earlier.AWS_SECRET_ACCESS_KEYis the AWS secret access key for theci-cd-ecrIAM user created earlier.AWS_ACCOUNT_IDis the 12-digit ID of the AWS account that owns the ECR registry.AWS_DEFAULT_REGIONis the AWS region where your ECR resources will be located, for exampleus-east-2.
Note: You don’t have to set $CIRCLE_SHA1 because it is the default variable available in all CircleCI projects. It’s the SHA1 hash of the last commit of the current build. Using the Git commit hash gives you the ability to trace what’s in the containers. Ideally, it allows you to trace a container back to its Docker image, and then back to the Dockerfile and code contained in the image. In an automated execution environment, this will take you back to the commit that caused the Docker image to be built.
Connecting the application to CircleCI
The next step is to set up a repository on GitHub and link the project to CircleCI. Review Pushing a project to GitHub for instructions.
Log in to CircleCI and click Create project. Enter a project name and click Next. Under Create your first pipeline, connect GitHub if prompted and select the repository (circleci-ecr-app-demo in this case). Keep the default pipeline name and the All pushes trigger, then click Next. CircleCI detects the .circleci/config.yml file that’s already in the repository. Click Next, review the setup, and click Go to project.
If the organization still uses the CircleCI GitHub OAuth app, follow the create a project steps for that integration instead.
With the GitHub App flow, the pipeline runs on the next push, so push a commit to the repository to start it. Your first workflow will start running and complete successfully.
Now, any time you update your project, your CI pipeline will automatically build a new image and push it to ECR. To review the repository information, go to your AWS management Console.
Conclusion
With both CircleCI and Amazon ECR successfully configured, you can start building images and pushing them to the repository.
With just a few lines of code, you were able to build and push your Docker image to Amazon ECR. CircleCI orbs save time by importing pre-built commands, jobs, and executors into CircleCI configuration files, providing easy integration with cloud services and other tools.