Deploying a Container Image to AWS ECR using a GitHub Action

AWS Elastic Container Registry (ECR) is a fully managed container registry service that makes it easy to store, manage, and deploy container images. GitHub Actions allows you to automate your software development workflows, including building and deploying container images. In this tutorial, we will walk you through the process of deploying a container image to AWS ECR using a GitHub Action.

Prerequisites

Before you begin, make sure you have the following prerequisites:

1. An AWS account with appropriate permissions to create and manage ECR repositories.
2. A GitHub repository where you want to deploy your container image.
3. Docker installed on your local machine.

Step 1: Set up AWS Credentials

To interact with AWS services, you need to set up AWS credentials. Follow these steps to configure AWS CLI on your local machine:

1. Install AWS CLI by following the instructions in the official AWS CLI documentation: Installing the AWS CLI.
2. Open a terminal and run the following command:

aws configure

3. Provide your AWS Access Key ID, Secret Access Key, default region name, and output format. This information can be obtained from your AWS account.

Step 2: Create an AWS ECR Repository

Next, create an AWS ECR repository to store your container image. Follow these steps:

1. Log in to the AWS Management Console.
2. Navigate to the AWS ECR service.
3. Click on “Create repository.”
4. Provide a repository name and optionally add a tag prefix or configure lifecycle policy settings.
5. Click on “Create repository” to create the repository.

Step 3: Prepare GitHub Actions Workflow

In your GitHub repository, create a new directory named .github/workflows. Inside this directory, create a YAML file (e.g., deploy.yml) to define the GitHub Actions workflow.

Copy the following code into the deploy.yml file:

name: Deploy to AWS ECR

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest

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

      - name: Login to AWS ECR
        uses: aws-actions/amazon-ecr-login@v1
        with:
          registry: <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

      - name: Build and push Docker image
        run: |
          docker build -t <IMAGE_NAME> .
          docker tag <IMAGE_NAME>:latest <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPO_NAME>:latest
          docker push <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPO_NAME>:latest

Replace the placeholders <AWS_ACCOUNT_ID>, <REGION>, <IMAGE_NAME>, and <REPO_NAME> with your AWS account ID, AWS region, Docker image name, and ECR repository name, respectively.

This workflow configuration specifies that the deployment will occur on every push to the main branch. It includes steps to checkout the repository, login to AWS ECR, build the Docker image, tag it, and push it to ECR.

Step 4: Configure GitHub Secrets

To securely store your AWS credentials and other sensitive information, use GitHub Secrets. Follow these steps to configure the necessary secrets:

1. In your GitHub repository, go to the “Settings” tab.
2. Click on “Secrets” in the left sidebar.
3. Click on “New repository secret.”
4. Add two secrets: AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. Enter the corresponding values for your AWS credentials.

Step 5: Push and Deploy

Commit and push the deploy.yml file to your GitHub repository. This action triggers the GitHub workflow, which will build and push the Docker image to AWS ECR.

Navigate to the “Actions” tab in your GitHub repository to monitor the progress of the workflow. Once the workflow is successfully completed, your container image will be deployed to AWS ECR.

Troubleshooting

If you encounter any issues during the deployment process, here are a few troubleshooting tips:

1. Invalid AWS credentials: Ensure that the AWS credentials provided in the GitHub Secrets are correct. Double-check the Access Key ID and Secret Access Key for accuracy.
2. Incorrect repository name: Verify that the ECR repository name specified in the workflow file (deploy.yml) matches the actual repository name in AWS ECR.
3. Missing Docker image: Ensure that the Dockerfile and the Docker image you are trying to build and deploy exist in the repository.
4. Missing Docker build dependencies: If your Dockerfile has dependencies or requires certain files or packages, ensure that they are present in the repository or accessible during the build process.
5. Permissions issues: Check if the AWS IAM user associated with the provided AWS credentials has the necessary permissions to access ECR and perform actions like pushing images.
6. Invalid region: Make sure the AWS region specified in the workflow file (deploy.yml) matches the actual region where your ECR repository is located.

If you encounter specific error messages or issues, refer to the GitHub Actions logs and AWS ECR documentation for more detailed troubleshooting steps.

Enhancements and Further Customization

The provided GitHub Actions workflow is a basic example to get you started with deploying container images to AWS ECR. Depending on your requirements, you can further customize the workflow by adding additional steps or modifying existing ones. Here are a few possible enhancements:

• Build Docker image from a specific branch/tag: Modify the on.push.branches section in the workflow file to specify a different branch or tag for triggering the deployment.
• Build and push multiple Docker images: If you have multiple Docker images to build and push, you can add additional steps to build and push each image individually.
• Add additional checks or tests: Integrate additional steps in the workflow to run tests, linting, or other checks before building and deploying the Docker image.
• Tag Docker images with versioning: Customize the Docker image tagging process to include version numbers or other identifiers based on your project requirements.
• Trigger deployment on pull requests: Modify the on section in the workflow file to include pull request events if you want to trigger the deployment when pull requests are opened or updated.

Feel free to adapt and modify the workflow according to your specific needs and best practices.

Conclusion

Deploying container images to AWS ECR using GitHub Actions streamlines the deployment process and allows for seamless integration within your development workflow. By following the steps outlined in this tutorial and customizing the workflow as needed, you can automate the deployment of container images to AWS ECR, enabling efficient and consistent deployment practices.