Build and push Docker images to Amazon ECR using GitHub Actions and Terraform

Created by Ruchika Modi (AWS)

Code repository: docker-ecr-actions-workflow	Environment: Production	Technologies: DevOps; Containers & microservices; Infrastructure
Workload: All other workloads	AWS services: Amazon ECR

Summary

This pattern explains how you can create reusable GitHub workflows to build your Dockerfile and push the resulting image to Amazon Elastic Container Registry (Amazon ECR). The pattern automates the build process of your Dockerfiles by using Terraform and GitHub Actions. This minimizes the possibility of human error and substantially reduces deployment time.

A GitHub push action to the main branch of your GitHub repository initiates the deployment of resources. The workflow creates a unique Amazon ECR repository based on the combination of the GitHub organization and repository name. It then pushes the Dockerfile image to the Amazon ECR repository.

Prerequisites and limitations

Prerequisites

• An active AWS account.

• An active GitHub account.

• A GitHub repository.

• Terraform version 1 or later installed and configured.

• An Amazon Simple Storage Service (Amazon S3) bucket for the Terraform backend.

• An Amazon DynamoDB table for Terraform state locking and consistency. The table must have a partition key named LockID with a type of String. If this isn't configured, state locking will be disabled.

• An AWS Identity and Access Management (IAM) role that has permissions to set up the Amazon S3 backend for Terraform. For configuration instructions, see the Terraform documentation.

Limitations

This reusable code has been tested only with GitHub Actions.

Architecture

Target technology stack

• Amazon ECR repository

• GitHub Actions

• Terraform

Target architecture

The diagram illustrates the following:

1. A user adds a Dockerfile and Terraform templates to the GitHub repository.

2. These additions initiate a GitHub Actions workflow.

3. The workflow checks whether an Amazon ECR repository exists. If not, it creates the repository based on the GitHub organization and repository name.

4. The workflow builds the Dockerfile and pushes the image to the Amazon ECR repository.

Tools

Amazon services

• Amazon Elastic Container Registry (Amazon ECR) is a managed container registry service that’s secure, scalable, and reliable.

Other tools

• GitHub Actions is integrated into the GitHub platform to help you create, share, and run workflows within your GitHub repositories. You can use GitHub Actions to automate tasks such as building, testing, and deploying your code.

• Terraform is an open source infrastructure as code (IaC) tool from HashiCorp that helps you create and manage cloud and on-premises infrastructure.

Code repository

The code for this pattern is available in the GitHub Docker ECR Actions Workflow repository.

• When you create GitHub Actions, Docker workflow files are saved in the /.github/workflows/ folder of this repository. The workflow for this solution is in the workflow.yaml file.

• The e2e-test folder provides a sample Dockerfile for reference and testing.

Best practices

• For best practices for writing Dockerfiles, see the Docker documentation.

• Use a VPC endpoint for Amazon ECR. VPC endpoints are powered by AWS PrivateLink, a technology that enables you to privately access Amazon ECR APIs through private IP addresses. For Amazon ECS tasks that use the Fargate launch type, the VPC endpoint enables the task to pull private images from Amazon ECR without assigning a public IP address to the task.

Epics

Set up the OIDC provider and GitHub repository

Task	Description	Skills required
Configure OpenID Connect.	Create an OpenID Connect (OIDC) provider. You will use the provider in the trust policy for the IAM role used in this action. For instructions, see Configuring OpenID Connect in Amazon Web Services in the GitHub documentation.	AWS administrator, AWS DevOps, General AWS
Clone the GitHub repository.	Clone the GitHub Docker ECR Actions Workflow repository into your local folder: $git clone https://github.com/aws-samples/docker-ecr-actions-workflow	DevOps engineer

Customize the GitHub reusable workflow and deploy the Docker image

Task	Description	Skills required
Customize the event that initiates the Docker workflow.	The workflow for this solution is in workflow.yaml. This script is currently configured to deploy resources when it receives the workflow_dispatch event. You can customize this configuration by changing the event to workflow_call and calling the workflow from another parent workflow.	DevOps engineer
Customize the workflow.	The workflow.yaml file is configured to create a dynamic, reusable GitHub workflow. You can edit this file to customize the default configuration, or you can pass the input values from the GitHub Actions console if you're using the workflow_dispatch event to initiate deployment manually. Make sure to specify the correct AWS account ID and target Region. Create an Amazon ECR lifecycle policy (see sample policy) and update the default path (e2e-test/policy.json) accordingly. The workflow file requires two IAM roles as input: An IAM role that has permissions to set up the Amazon S3 backend for Terraform (see the Prerequisites section). You can update the default role name workload-assumable-role in the .yaml file accordingly. An IAM role that has permissions to access GitHub. This role is also used in the Amazon ECR policy to restrict Amazon ECR operations. For more information, see the data.tf file.	DevOps engineer
Deploy the Terraform templates.	The workflow automatically deploys the Terraform templates that create the Amazon ECR repository, based on the GitHub event you configured. These templates are available as .tf files at the root of the Github repository.	AWS DevOps, DevOps engineer

Troubleshooting

Issue	Solution
Issues or errors when you configure Amazon S3 and DynamoDB as the Terraform remote backend.	Follow the instructions in the Terraform documentation to set up the required permissions on the Amazon S3 and DynamoDB resources for the remote backend configuration.
Unable to run or start the workflow with the workflow_dispatch event.	The workflow that's configured to deploy from the workflow_dispatch event will work only if the workflow is configured on the main branch as well.

Related resources

• Reusing workflows (GitHub documentation)

• Triggering a workflow (GitHub documentation)