Building multi-architecture container images with AWS CodeBuild and GitHub Actions

As the landscape of computing continues to evolve, there is a growing emphasis on supporting a diverse range of computing architectures.

This blog was authored by Zakiya Randall, Technical Account Manager and co-written with Muru Bhaskaran, Sr. Specialist Solutions Architect.

As the landscape of computing continues to evolve, there is a growing emphasis on supporting a diverse range of computing architectures. This shift is driven by the need for flexibility, efficiency, and performance optimization across different hardware platforms. Consequently, it has become increasingly important for developers and organizations to build container images that are compatible with multiple architectures (multi-arch).

AWS CodeBuild is a fully managed continuous integration service that now supports managed GitHub Actions runners, which are self-hosted runners that allow users to configure their CodeBuild projects to receive GitHub Actions workflow job events. In this post, we demonstrate a solution that uses GitHub, GitHub Actions workflows, and CodeBuild to build native container images for both x86 and AWS Graviton-based compute on AWS. Upon completion of our GitHub Actions workflow, we will proceed to push our multi-arch images to Amazon Elastic Container Registry (Amazon ECR).

Solution overview

The architecture diagram illustrates the workflow that occurs upon committing a change to the GitHub repository, detailing the subsequent steps involved in pushing the container image to Amazon ECR.

Figure 1: Solution architecture diagram

Prerequisites

The following prerequisites are necessary to complete this solution:

Walkthrough

The following steps walk you through this solution.

Creating GitHub repository files

To begin creating the solution, you need a GitHub repository to store the Dockerfile, index.html file, and GitHub Actions workflow YAML file. Refer to Creating a new GitHub repository for step by step instructions. For this example, the following files should be committed to the root of the GitHub repository.

Create two CodeBuild projects for the x86 and arm64 compute architectures

You must create two CodeBuild projects to run your GitHub Actions jobs. Your CodeBuild projects should follow the following naming structure for -x86 and -arm64. Refer to the following tutorial to set up two CodeBuild projects for the x86 and arm64 compute environments. You should use the OAuth app authentication method to connect with your GitHub repository. For the x86 and arm64 CodeBuild projects, choose a supported environment image that matches each compute architecture. Your Buildspec build specifications are ignored. Instead, CodeBuild overrides it to use commands that setup the compute runner.

Figure 2: CodeBuild Projects for x86 and arm64

Create an Amazon ECR repository

You also need to create an Amazon ECR repository to store the x86 and arm64 container images. Run the following AWS CLI command to create an Amazon ECR repository.

After creating and defining your Amazon ECR repository, you must define a role so that the CodeBuild runners can have permission to access and push your images to your Amazon ECR repository. The following role that you create allows you to push images to your Amazon ECR repository.

After creating the policy, go to the AWS Identity and Access Management (IAM) console to create an Identity Provider and choose OpenID Connect. For the Provider URL, choose https://token.actions.githubusercontent.com. For the Audience, choose sts.amazonaws.com.

2. After you create the provider, create a role and choose Web Identity. In the drop-down box, you should see the Provider URL for https://token.actions.githubusercontent.com. Choose this option and specify sts.amazonaws.com for your Audience. In the GitHub organization, specify your GitHub Organization and add the repository that you created in the initial setup. Choose Next.

Figure 3: Example of creating the role

3. On the Add Permissions page, choose the policy that you created in Step 1 so that you can push images to Amazon ECR. Choose Next. On the next screen, name the role and choose Create role.

Figure 4: Example of adding policy permissions

4. Go to Settings within your GitHub repository, and under Security in the left pane, choose Secrets and Variables. Choose the Actions tab within Secrets and Variables. Choose New repository secret. For the name, enter AWS_ROLE_ARN, enter the AWS Role ARN of the role that you created in Step 3, and choose Add secret.

Figure 5: Example of creating GitHub Actions secret for the AWS Role

5. Create another New repository secret for AWS_REGION. Specify the Region in which you created your resources and choose Add secret.

Figure 6: Example of GitHub Actions secret for the AWS Region

Prepare GitHub Actions workflow

A GitHub Actions workflow is a configurable automated process made up of one or more jobs and you can define these jobs in a YAML file. You are going to create a YAML file in the .github/workflows directory within your GitHub repository that defines the workflow for the solution. The YAML file for your GitHub Actions workflow contains the build