Replicate filtered Amazon ECR container images across accounts or Regions
Created by Abdal Garuba (AWS)
Environment: Production | Technologies: Containers & microservices; DevOps | AWS services: Amazon EC2 Container Registry; Amazon CloudWatch; AWS CodeBuild; AWS Identity and Access Management; AWS CLI |
Summary
Amazon Elastic Container Registry (Amazon ECR) can replicate all container images in an image repository across Amazon Web Services (AWS) Regions and AWS accounts natively, by using the cross-Region and cross-account replication features. (For more information, see the AWS blog post Cross region replication in Amazon ECR has landed
This pattern describes how to replicate container images that are stored in Amazon ECR across AWS accounts and Regions, based on image tag patterns. The pattern uses Amazon CloudWatch Events to listen for push events for images that have a predefined, custom tag. A push event starts an AWS CodeBuild project and passes the image details to it. The CodeBuild project copies the images from the source Amazon ECR registry to the destination registry based on the details provided.
This pattern copies images that have specific tags across accounts. For example, you can use this pattern to copy only production-ready, secure images to the production AWS account. In the development account, after images are thoroughly tested, you can add a predefined tag to the secure images and use the steps in this pattern to copy the marked images to the production account.
Prerequisites and limitations
Prerequisites
An active AWS account for source and destination Amazon ECR registries
Administrative permissions for the tools used in this pattern
Docker
installed on your local machine for testing AWS Command Line Interface (AWS CLI), for authenticating into Amazon ECR
Limitations
This pattern watches the push events of the source registry in only one AWS Region. You can deploy this pattern to other Regions to watch registries in those Regions.
In this pattern, one Amazon CloudWatch Events rule listens for a single image tag pattern. If you want to check for multiple patterns, you can add events to listen for additional image tag patterns.
Architecture
Target architecture
![Architecture for replicating filtered Amazon ECR container images across accounts and Regions.](/images/prescriptive-guidance/latest/patterns/images/pattern-img/a0f635e4-3ba5-4411-b9f8-54cfc228535a/images/2cb7962d-5b45-41a2-ba8c-7a18f01b617a.png)
Automation and scale
This pattern can be automated with an infrastructure as code (IaC) script and deployed at scale. To use AWS CloudFormation templates to deploy this pattern, download the attachment and follow the instructions in the Additional information section.
You can point multiple Amazon CloudWatch Events events (with different custom event patterns) to the same AWS CodeBuild project to replicate multiple image tag patterns, but you will need to update the secondary validation in the buildspec.yaml
file (which is included in the attachment and in the Tools section) as follows to support multiple patterns.
... if [[ ${IMAGE_TAG} != release-* ]]; then ...
Tools
Amazon services
IAM
– AWS Identity and Access Management (IAM) enables you to manage access to AWS services and resources securely. In this pattern, you would need to create the cross-account IAM role that AWS CodeBuild will assume when pushing container images to the destination registry. Amazon ECR
– Amazon Elastic Container Registry (Amazon ECR) is a fully managed container registry that makes it easy to store, manage, share, and deploy your container images and artifacts anywhere. Image push actions to the source registry send system event details to the event bus that is picked up by Amazon CloudWatch Events. AWS CodeBuild
– AWS CodeBuild is a fully managed continuous integration service that provides compute power to perform jobs such as compiling source code, running tests, and producing artifacts that are ready to be deployed. This pattern uses AWS CodeBuild to perform the copy action from the source Amazon ECR registry to the destination registry. CloudWatch Events – Amazon CloudWatch Events delivers a stream of system events that describe changes in AWS resources. This pattern uses rules to match Amazon ECR push actions with a specific image tag pattern.
Tools
Docker CLI
– Docker is a tool that makes it easier to create and manage containers. Containers pack an application and all its dependencies into one unit or package that can easily be deployed on any platform that supports the container runtime.
Code
You can implement this pattern in two ways:
Automated setup: Deploy the two AWS CloudFormation templates provided in the attachment. For instructions, see the Additional information section.
Manual setup: Follow the steps in the Epics section.
Sample buildspec.yaml
If you’re using the CloudFormation templates that are provided with this pattern, the buildspec.yaml
file is included in the CodeBuild resources.
version: 0.2 env: shell: bash phases: install: commands: - export CURRENT_ACCOUNT=$(echo ${CODEBUILD_BUILD_ARN} | cut -d':' -f5) - export CURRENT_ECR_REGISTRY=${CURRENT_ACCOUNT}.dkr.ecr.${AWS_REGION}.amazonaws.com - export DESTINATION_ECR_REGISTRY=${DESTINATION_ACCOUNT}.dkr.ecr.${DESTINATION_REGION}.amazonaws.com pre_build: on-failure: ABORT commands: - echo "Validating Image Tag ${IMAGE_TAG}" - | if [[ ${IMAGE_TAG} != release-* ]]; then aws codebuild stop-build --id ${CODEBUILD_BUILD_ID} sleep 60 exit 1 fi - aws ecr get-login-password --region ${AWS_REGION} | docker login -u AWS --password-stdin ${CURRENT_ECR_REGISTRY} - docker pull ${CURRENT_ECR_REGISTRY}/${REPO_NAME}:${IMAGE_TAG} build: commands: - echo "Assume cross-account role" - CREDENTIALS=$(aws sts assume-role --role-arn ${CROSS_ACCOUNT_ROLE_ARN} --role-session-name Rolesession) - export AWS_DEFAULT_REGION=${DESTINATON_REGION} - export AWS_ACCESS_KEY_ID=$(echo ${CREDENTIALS} | jq -r '.Credentials.AccessKeyId') - export AWS_SECRET_ACCESS_KEY=$(echo ${CREDENTIALS} | jq -r '.Credentials.SecretAccessKey') - export AWS_SESSION_TOKEN=$(echo ${CREDENTIALS} | jq -r '.Credentials.SessionToken') - echo "Logging into cross-account registry" - aws ecr get-login-password --region ${DESTINATION_REGION} | docker login -u AWS --password-stdin ${DESTINATION_ECR_REGISTRY} - echo "Check if Destination Repository exists, else create" - | aws ecr describe-repositories --repository-names ${REPO_NAME} --region ${DESTINATION_REGION} \ || aws ecr create-repository --repository-name ${REPO_NAME} --region ${DESTINATION_REGION} - echo "retag image and push to destination" - docker tag ${CURRENT_ECR_REGISTRY}/${REPO_NAME}:${IMAGE_TAG} ${DESTINATION_ECR_REGISTRY}/${REPO_NAME}:${IMAGE_TAG} - docker push ${DESTINATION_ECR_REGISTRY}/${REPO_NAME}:${IMAGE_TAG}
Epics
Task | Description | Skills required |
---|---|---|
Create a CloudWatch Events role. | In the source AWS account, create an IAM role for Amazon CloudWatch Events to assume. The role should have permissions to start a AWS CodeBuild project. To create the role by using the AWS CLI, follow the instructions in the IAM documentation. Example trust policy (
Example permission policy (
| AWS administrator, AWS DevOps, AWS systems administrator, Cloud administrator, Cloud architect, DevOps engineer |
Create a CodeBuild role. | Create an IAM role for AWS CodeBuild to assume, by following the instructions in the IAM documentation. The role should have the following permissions:
Example trust policy (
Example permission policy (
Attach the managed policy
| AWS administrator, AWS DevOps, AWS systems administrator, Cloud administrator, Cloud architect, DevOps engineer |
Create a cross-account role. | In the destination AWS account, create an IAM role for the AWS CodeBuild role for the source account to assume. The cross-account role should allow container images to create a new repository and upload container images to Amazon ECR. To create the IAM role by using the AWS CLI, follow the instructions in the IAM documentation. To allow the AWS CodeBuild project from the previous step, use the following trust policy:
To allow the AWS CodeBuild project from the previous step to save images in the destination registry, use the following permission policy:
| AWS administrator, AWS DevOps, Cloud administrator, Cloud architect, DevOps engineer, AWS systems administrator |
Task | Description | Skills required |
---|---|---|
Create a CodeBuild project. | Create a AWS CodeBuild project in the source account by following the instructions in the AWS CodeBuild documentation. The project should be in the same Region as the source registry. Configure the project as follows:
| AWS administrator, AWS DevOps, AWS systems administrator, Cloud administrator, Cloud architect, DevOps engineer |
Task | Description | Skills required |
---|---|---|
Create an events rule. | Because the pattern uses the content filtering feature, you need to create the event by using Amazon EventBridge. Create the event and target by following the instructions in the EventBridge documentation, with a few modifications:
| AWS administrator, AWS DevOps, AWS systems administrator, Cloud administrator, Cloud architect, DevOps engineer |
Task | Description | Skills required |
---|---|---|
Authenticate with Amazon ECR. | Authenticate to both source and destination registries by following the steps in the Amazon ECR documentation. | AWS administrator, AWS DevOps, AWS systems administrator, Cloud administrator, DevOps engineer, Cloud architect |
Test image replication. | In your source account, push a container image to a new or existing Amazon ECR source repository with an image tag prefixed with You can monitor the progress of the CodeBuild project in the CodeBuild console After the CodeBuild project has completed successfully, sign in to the destination AWS account, open the Amazon ECR console, and confirm that the image exists in the destination Amazon ECR registry. | AWS administrator, AWS DevOps, AWS systems administrator, Cloud administrator, Cloud architect, DevOps engineer |
Test image exclusion. | In your source account, push a container image to a new or existing Amazon ECR source repository with an image tag that doesn’t have the custom prefix. Confirm that the CodeBuild project isn’t started, and that no container images appear in the destination registry. | AWS administrator, AWS DevOps, AWS systems administrator, Cloud administrator, Cloud architect, DevOps engineer |
Related resources
Additional information
To automatically deploy the resources for this pattern, follow these steps:
Download the attachment and extract the two CloudFormation templates:
part-1-copy-tagged-images.yaml
andpart-2-destination-account-role.yaml
.Log in to the AWS CloudFormation console
, and deploy part-1-copy-tagged-images.yaml
in the same AWS account and Region as the source Amazon ECR registries. Update the parameters as needed. The template deploys the following resources:Amazon CloudWatch Events IAM role
AWS CodeBuild project IAM role
AWS CodeBuild project
AWS CloudWatch Events rule
Take note of the value of
SourceRoleName
in the Outputs tab. You will need this value in the next step.Deploy the second CloudFormation template,
part-2-destination-account-role.yaml
, in the AWS account that you want to copy the Amazon ECR container images to. Update the parameters as needed. For theSourceRoleName
parameter, specify the value from step 3. This template deploys the cross-account IAM role.Validate image replication and exclusion, as described in the last step of the Epics section.
Attachments
To access additional content that is associated with this document, unzip the following file: attachment.zip