How to Leverage the AWS ECR (Elastic Container Registry)

Published:24 October 2022 - 7 min. read

Block over 3 billion compromised passwords & strengthen your Active Directory password policy. Try Specops Password Policy for free!

Have you been searching for a reliable and secure container image registry service to host your Docker images? If yes, then Amazon Elastic Container Registry (AWS ECR) is at your service.

AWS ECR is a fully managed registry service that supports private and public repositories. And in this tutorial, you will learn how to use the Amazon ECR to host Docker images via the AWS CLI and GitHub Actions.

Ready? Stay tuned and start deploying Docker images privately with AWS ECR!

Prerequisites

This tutorial will be a hands-on demonstration. To follow along, be sure you have the following:

  • A Linux machine – This tutorial uses Ubuntu 20.04.3 LTS.
  • Docker and AWS CLI are locally installed on your machine.
  • An AWS account.

Creating and Configuring an AWS ECR Repository

Container images ideally are stored in repositories. Before deploying and hosting Docker images on AWS ECR, you’ll need first to create and configure a repository to store your Docker image.

1. Open your favorite web browser, navigate to AWS ECR, and log in with your AWS account.

2. Once logged in, click Get Started to initialize creating a repository.

Initializing creating a repository
Initializing creating a repository

3. Next, provide a unique repository name, but this tutorial uses a repository name called node-app.

Providing a repository name
Providing a repository name

4. Leave other default settings, scroll down to the bottom, and click on the Create repository button to create this repository.

Creating a repository on AWS ECR
Creating a repository on AWS ECR

After creating the repository, you will see your newly created repository listed, as shown below.

Verifying the newly-created repository
Verifying the newly-created repository

Creating an IAM User and Granting Access to ECR

You have successfully created a repository on AWS ECR, but how do you manage your repository? You will need a dedicated IAM user granted with required access to perform tasks on your ECR repository.

To create an IAM user to interact with your ECR repository, follow these steps:

1. On the AWS Management Console, search for IAM, and select the first option, as shown below, to access the IAM dashboard.

Accessing the IAM dashboard
Accessing the IAM dashboard

2. Next, select Users (left panel) on your IAM dashboard, and click Add users (top-right) to initiate adding a new IAM user.

Selecting users option
Selecting users option

3. Set the user details and AWS access type with the following:

  • Provide a unique User name, but this tutorial’s choice is aws-ecr.
  • Choose the Access key – Programmatic access option, so you will only need an access key ID and a secret access key to access your AWS ECR repository via the AWS CLI.
  • Click Next: Permissions to proceed setting permissions for the IAM user.
Providing IAM user name and selecting an AWS access type
Providing IAM user name and selecting an AWS access type

4. Now, add permission policies to the new IAM user with the following:

  • Select the Attach existing policies directly **option to search for existing policies.
  • Search container to filter policies, and select AmazonEC2ContainerRegistryFullAccess and AmazonElasticContainerRegistryPublicFullAccess policies.

These policies grant AWS ECR full access to the new IAM user since you will be working on AWS ECR.

  • After selecting policies, click Next: Tags to continue.
Granting AWS ECR full access to the new IAM user
Granting AWS ECR full access to the new IAM user

5. Skip adding tags, and click Next: Review to continue.

Skipping adding tags
Skipping adding tags

6. Next, review the current user details, and click Create user (bottom-right) to create the new IAM user.

Creating the new IAM user
Creating the new IAM user

You will see the newly-created IAM user, as shown below if created successfully.

Note down the Access key ID, and Secret access key as these are the credentials you will need to interact with your ECR repository.

Accessing user security credentials
Accessing user security credentials

7. Finally, open your terminal, and run the aws configure command below to configure your AWS CLI to work with your IAM user.

aws configure

Configure AWS CLI with the following when prompted:

  • Provide the AWS Access Key ID and AWS Secret Access Key you noted in step six.
  • Set the Default region name – This tutorial uses us-east-1.
  • Set the Default output format – This tutorial’s choice is json.

At this point, your dedicated IAM user can now connect and perform tasks on AWS ECR.

Configuring AWS CLI
Configuring AWS CLI

Pushing Docker Images to AWS ECR

After configuring your AWS CLI to work with your new IAM user, you are ready to perform tasks on your repository on AWS ECR. Specifically, pushing Docker images to your repository.

1. Navigate to the Repositories page on AWS ECR, and click on your repository’s name (node-app) to access your repository.

Accessing the repository in AWS ECR
Accessing the repository in AWS ECR

2. Next, click View push commands (top-right) to view the commands you will need to push your Docker image to your repository.

Viewing push commands
Viewing push commands

3. On the pop-up Push commands window, copy the first command (aws ecr get-login-password).

Coping authentication token from ASW ECR
Coping authentication token from ASW ECR

4. Now, paste the command in your terminal and hit Enter. This command retrieves an authentication token and authenticates your Docker client to your AWS ECR.

If successful, you will see the following output with a message that says Login Succeeded.

Authenticating Docker client
Authenticating Docker client

5. Run the following commands to change your working directory (cd) to your project directory and build (docker build) a Docker image (node-app).

cd nodeapp
docker build -t node-app .

If the build is successful, you will see a similar output to the one below.

Building the Docker image
Building the Docker image

6. Copy the third push command (docker tag) in the Push commands window, and run the command in your terminal to add the latest tag to your image. Doing so allows you to push the image to your repository.

Copying the docker tag command
Copying the docker tag command

7. Finally, copy the fourth command (docker push), and run it on your terminal to push your Docker image to your repository on ECR.

Copying push command on AWS ECR
Copying push command on AWS ECR

You will see an output similar to the one below if you have pushed your Docker image to your repository successfully.

Pushing Docker image to the repository on AWS ECR via the AWS CLI
Pushing Docker image to the repository on AWS ECR via the AWS CLI

Registering Docker Images on AWS ECR with GitHub Actions

You have just successfully configured resources and pushed Docker images to your repository on AWS ECR. As incredible as these all sounds, the process could be most times time-consuming and stressful, performing everything by yourself.

Is there a way to save yourself the hassle of manually configuring everything? Yes! By using a CI/CD pipeline. And what better platform to choose than GitHub Actions? GitHub Actions is a CI/CD platform that allows you to perform and automate your build, test, and deployment pipeline.

1. Create a directory called .github in your project directory and a sub-directory called workflows. The workflows directory will hold your configuration files.

2. Next, create a file called deploy-to-aws-ecr.yaml, populate the code below, and ensure you replace the following:

  • ACCESS_KEY_ID and SECRET_ACCESS_KEY – your access key ID and secret access key.
  • node-app - your repository name on ECR.

The following code monitors all push commits on the main branch of your GitHub repository and builds a Docker image using the latest Ubuntu (ubuntu-latest) version.

For GitHub Actions to work successfully, build and deploy your Docker image to your AWS ECR repository. You must have a Dockerfile in your project that GitHub Actions will use to build your Docker image.

name: Deployment From GitHub to AWS Elastic Container Registry 

on:
  push:
    branches: [ main ]

jobs:
  build: 
    name: Build Docker image
    runs-on: ubuntu-latest

    steps:
    - name: Checkout
      uses: actions/[email protected]
      
    - name: Configure AWS credentials
      uses: aws-actions/[email protected]
      with:
        aws-access-key-id: ACCESS_KEY_ID
        aws-secret-access-key: SECRET_ACCESS_KEY
        aws-region: us-east-1

    - name: Login to Amazon ECR Private
      id: login-ecr
      uses: aws-actions/[email protected]

    - name: Build, tag, and push Docker image to Amazon ECR
      env:
        REGISTRY: ${{ steps.login-ecr.outputs.registry }}
        REPOSITORY: node-app
        IMAGE_TAG: latest
      run: |
        docker build -t $REGISTRY/$REPOSITORY:$IMAGE_TAG .
        docker push $REGISTRY/$REPOSITORY:$IMAGE_TAG

3. On your project root directory, run the following git commands to commit and push your code to your GitHub repository.

git add . # Adds changes to staging area
git commit -m "update" # Commits your changes
git push # Push code to GitHub

4. Now, navigate your GitHub repository via your web browser, and click on the Actions tab to see all workflows.

The output below indicates GitHub Actions have successfully built and pushed a Docker image for your project to your repository on AWS ECR.

Confirming workflow on GitHub repository
Confirming workflow on GitHub repository

5. Finally, navigate your AWS ECR repository to confirm your Docker image was pushed successfully.

Accessing the Docker image
Accessing the Docker image

Below, you can see your Docker image was built and deployed successfully and tagged as latest.

Viewing the newly-pushed Docker image on the ECR repository
Viewing the newly-pushed Docker image on the ECR repository

Conclusion

Manual deployment can be a pain. But thanks to AWS ECR, and GitHub actions, you get to automate your Docker image deployments. And in this tutorial, you have learned how to create an IAM user to enable interaction with your repository on AWS ECR via the AWS CLI.

How else will you like to expand on this knowledge? Perhaps pull the Docker image via the Image URI to your local machine?

Hate ads? Want to support the writer? Get many of our tutorials packaged as an ATA Guidebook.

Explore ATA Guidebooks

Looks like you're offline!