AWS Multi-Architecture Container Build Pipeline Library
Introduction
This repository contains an AWS Cloud Development Kit (CDK) pattern library to help you create code pipelines that build multi-architecture container images. This can help you build container images that run on both Intel/AMD and Arm 64-bit architectures so you can take advantage of new technologies such as the recently-introduced EC2 instance families based on the AWS Graviton2 processor.
The AWS Graviton2 processor uses the Arm 64-bit (arm64) architecture. It runs many workloads significantly faster than on legacy Intel/AMD 64-bit (amd64) processors, and the cost per instance-hour is significantly less expensive than Intel-based instances with the same vCPU count and memory. Many applications are easily adaptable to the arm64 architecture by simply recompiling the code. Scripts and applications based on compiled byte code can often be run without any modification by using a native arm64 runtime. For example, many Java applications can easily be run on Graviton2 instances using the arm64 build of Amazon Corretto.
The Docker Image Manifest V2 specification allows container image repositories,
including Amazon ECR, to host images for multiple
architectures. This allows you to run docker pull
on a host and automatically
receive the correct image for the host's CPU architecture. This pipeline library
takes advantage of this functionality by constructing the multi-architecture
manifest for you.
Theory of operations
This library builds a pipeline using AWS CodePipeline to produce an easily-accessible multi-architecture Docker image in Amazon ECR.
The pipeline stages are as follows:
- Source stage: obtain the source code for the Docker image.
- Build stage: the architecture-specific container images are built in parallel.
- Test stage: the architecture-specific container images are tested in parallel.
- Manifest build stage: the multi-architecture image manifest is produced and pushed to Amazon ECR.
Usage
First, you'll need to build an application using AWS CDK. Your application must import the library:
;
Source action
Your application will need to create a CodePipeline source action. All of the source actions provided by the aws-codepipeline-actions library are supported, including BitBucket, CodeBuild, GitHub, and S3.
Here's a trivial example:
;
ECR repository
Your application will need to create an ECR repository or reference an existing repository.
To create a new one:
;
To reference an existing repository, you can use one of the static
fromRepository*
methods available in the Repository
class. Here's an example:
;
Construct the pipeline
Then, your application can construct the pipeline:
new Pipelinethis, 'Pipeline', ;
The following attributes can be passed to the pipeline constructor:
Attribute | Description | Required? |
---|---|---|
sourceAction |
A CodePipeline source action. Tells the pipeline where to get the source code and is used as the source stage. | Yes |
imageRepo |
An ECR image repository. Used for storing and fetching images and manifests. | Yes |
architectures |
Array of CPU architectures used for building and testing images. Defaults to amd64 . Supported values include amd64 and arm64 . |
|
buildPath |
Path inside repository in which Dockerfile is located. Defaults to . . |
|
dockerBuildArgs |
Optional map of Docker build args. Equivalent to passing --build-arg to docker build . |
|
imageTag |
Tag to apply to generated images. Defaults to output of git describe --tags --always . You can use CodePipeline variable substitutions here, such as '#{Source.CommitId}' . |
|
buildTimeout |
Build timeout | |
testTimeout |
Test timeout | |
testBuildSpecPath |
Location of CodeBuild buildspec path used for test stage inside repository. Defaults to ./buildspec-test.yml . |
Notes
By default, the image tag will be either the latest Git tag (if the HEAD commit of the branch is tagged), the latest Git commit ID (if there are no tags reachable from the HEAD commit), or both (if HEAD is not tagged but a tag is reachable from the HEAD commit). This is consistent with best practice.
AWS CodePipeline does not currently include the .git
folder if you use
CodeCommit, BitBucket, or GitHub as a source action. This will cause the
automated tag generation to fail because the full commit history will not be
accessible. As a workaround, we suggest using an S3 bucket for the source stage
of the pipeline. Then, use a CodeBuild project to pull the source code from the
Git repository and simply dump the output to the S3 bucket. This will preserve
all the Git metadata.
The example project included in this repository has an example of this design for reference.
Example
An example of a minimal CDK application that uses this library can be found in the example folder of this repository.
License
MIT