Push & Pull Docker images from Amazon ECR : A Comprehensive Guide

Introduction

Amazon Elastic Container Registry (ECR) is a fully managed Docker container registry that makes it easy to store, manage, and deploy container images. In this article, we’ll explore how to push and pull Docker images from ECR, both locally and in a GitHub Actions (GHA) workflow.

Amazon ECR facilitates the Quick saving of Configuration related data. It enables efficient deployment into production and reduces the overall workloads.

Amazon ECR comes with a command-line-interface and APIs  that can be used to manage the docker repositories. We can also manage integrated services like the Amazon Elastic Container Service(Amazon ECS). Amazon ECR provides the repository that stores the code written and packaged as a Docker Image. Amazon ECS makes use of these file in deploying the applications. Docker command line interface can be used to push or pull container images to or from an AWS region.

How Amazon ECR works

The working of Amazon ECR is best explained in the three step process:

1. Amazon Elastic Container Registry is responsible for Containerisation of the application code into docker images.
2. Once the code is converted into a docker image, it then compresses, encrypts and manages access to the images. It also controls the lifecycle of the image.
3. The third step involves Amazon ECS pulling the necessary Docker images from ECR that needs to be used in the deployment of the apps. Amazon ECS is also responsible for managing containers in Amazon Kubernetes Services and AWS Cloud.

Why Use ECR?

• Scalability: The need for operating our own container repositories is eliminated by using Amazon ECR. One also need not worry about scaling of the underlying infrastructure. It does all the heavy lifting enabling us to focus on our core competence, the application development.
• Security: ECR comes integrated with the AWS IAM. This enables provision of resource-level control of each repository. Policies can be formulated to specify who can push and pull the docker images. These features ensure the security and the integrity of our images.
• Integration: ECR enables CI/CD workflows of our containerized application achieved through integration with AWS services like ECS & AWS Lambda.

• Efficiency: ECR provides pull-through cache feature(that we will discuss later in this post).  Through this feature, ECR can automatically cache images from public registries. This reduces download time and external data transfer costs. This streamlines accessing and deploying widely used public images, enhancing workflow efficiency and security.

Components of Amazon ECR:

Amazon ECR has the following components:

• Registry: Each AWS account comes with Amazon ECR registry access by default. Image repositories can be created and stored in the registries
• Authorization Token: Amazon ECR registries require an authenticated Docker client as an AWS user prior to pulling and pushing of the images. The AWS Command Line Interface provides a get-login command, which gives the user the authentication credentials to pass to Docker.
• Repository: The docker image is contained inside the Amazon ECR image repository.
• Repository Policy: This enables the users to have control on the access to their repository and the image within it.
• Image: User pushes to and pulls images from the Docker repository.The user can use the image of the repository on their local system or it could be used in Amazon ECS task definitions.

1. Pulling Images from ECR Locally

1.1 Authenticating with Amazon ECR

Before pulling an image from ECR, you need to authenticate your Docker client. Follow these steps:

1. Obtain an authentication token for the ECR registry you intend to pull from. These tokens are valid for 12 hours.
   
2. Use the docker login command to authenticate. For example:

aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com

1.2 Pulling the Image

Once authenticated, you can pull the image using the docker pull command. The image name format should be:

docker pull <account-id>.dkr.ecr <region>.amazonaws.com/<repository>:<tag>

Replace <account-id>, <region>, <repository>, and <tag> with your specific values.

1.3 Troubleshooting

If you encounter a “repository not found” error, ensure proper authentication. Refer to the official documentation for detailed instructions.

2. Pulling Images from Amazon ECR in GitHub Actions (GHA)

2.1 Setting Up GitHub Secrets

In your GitHub repository, navigate to Settings > Secrets. Add the following secrets:

• AWS_ACCESS_KEY_ID: Your AWS access key ID.
• AWS_SECRET_ACCESS_KEY: Your AWS secret access key.

2.2 Creating a Workflow

Create a .github/workflows/ecr-pull.yml file with the following content:

name: Pull ECR Image

on:
  push:
    branches:
      - main

jobs:
  pull-ecr-image:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Configure AWS credentials
        run: |
          echo "AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID" >> $GITHUB_ENV
          echo "AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY" >> $GITHUB_ENV

      - name: Pull ECR image
        run: |
          aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com
          docker pull <account-id>.dkr.ecr.<region>.amazonaws.com/<repository>:<tag>

Replace <region>, <account-id>, <repository>, and <tag> as before.

2.3 Workflow Execution

Whenever you push changes to the main branch, this workflow will authenticate with ECR and pull the specified image.

Advanced Feature: Using ECR as a Pull-Through Cache Repository

The pull-through cache repositories are one of the most powerful capability of Amazon ECR. This allows on demand fetching and storing of images from public Docker registries. It serves as a proxy, thereby enabling you to access and deploy public images as if they were part of your private ECR repositories. Workflow  is streamlined by reducing the need to manually copy images into ECR  and also improves security and efficiency in several ways:

• Efficiency and Speed: Caching public images reduces the need for repetitive downloads from external sources, accelerating deployment processes.
• Cost-Effectiveness: By minimizing the data transfer required from external repositories, we can reduce the amazon ECR costs significantly.
• Reliability: Ensures high availability of external images by caching them within your AWS infrastructure, mitigating the risk of third-party downtimes affecting your deployments.
• Enhanced Security: Offers the opportunity to scan cached images for vulnerabilities using ECR’s scanning capabilities, providing an additional layer of security before deployment.

Conclusion

By following these steps, you can seamlessly pull Docker images from Amazon ECR both locally and within your GitHub Actions workflows. Remember to secure your AWS credentials and adapt the workflow to your specific needs.

Happy containerising! 🐳🚀

If you are interested about docker basics, you can read full blog series here.