CDK ECR Deployment

Warnings

• breaking Older major versions (e.g., v1, v2) of cdk-ecr-deployment are no longer supported. Users should migrate to version 4.x to ensure compatibility with AWS CDK v2 and receive updates and bug fixes.
  Fix: Upgrade to the latest `cdk-ecr-deployment` package (version 4.x) and ensure your AWS CDK dependencies are also updated to v2.x. (e.g., `pip install cdk-ecr-deployment~=4.2.0 aws-cdk-lib~=2.x constructs~=10.x`)
• gotcha When copying images, especially from external registries, previous versions did not automatically retry on AWS ECR rate limit errors, which could lead to deployment failures for large numbers of images or frequent pushes.
  Fix: Upgrade to `cdk-ecr-deployment` version 4.1.3 or higher, which includes a fix to retry on rate limit errors. Consider increasing the Lambda memory if deploying very large images, as noted in the documentation.
• gotcha Errors occurring within the custom resource Lambda function (which performs the actual image copying) may manifest in CloudFormation logs as a generic `Invalid PhysicalResourceId`. The true error details are typically found in the associated AWS CloudWatch Logs for the Lambda function.
  Fix: If a deployment fails with `Invalid PhysicalResourceId`, navigate to AWS CloudWatch Logs for the `ECRDeployment`'s underlying Lambda function to inspect detailed error messages.
• gotcha Authentication to public ECR registries (e.g., `public.ecr.aws`) was not natively supported or straightforward in versions prior to 4.2.0, potentially causing authentication failures.
  Fix: Upgrade to `cdk-ecr-deployment` version 4.2.0 or newer for built-in authentication support for `public.ecr.aws` destinations.
• gotcha When sourcing images from private Docker registries, credentials stored in AWS Secrets Manager must adhere to specific formats: either plain text `username:password` or a JSON object `{"username":"<username>","password":"<password>"}`.
  Fix: Ensure your Secrets Manager secret for private registry authentication follows the required plain text or JSON format specified in the documentation.
• gotcha If you are using `aws-cdk-lib.aws_ecr_assets.DockerImageAsset` as a source, the CDK only rebuilds and pushes the Docker image when its source hash changes. If changes within your Docker context (e.g., code changes not reflected in the `Dockerfile` or `.dockerignore`) do not alter this hash, the image may not be updated on deployment.
  Fix: To force a rebuild, ensure that changes affect the Docker build context hash. A common workaround is to include a version file (e.g., `build-version.txt`) in your Docker context and `COPY` it in your `Dockerfile`, incrementing its content for each desired rebuild.

Install

• pip install cdk-ecr-deployment aws-cdk-lib constructs Install with pip

Imports

• ECRDeployment

  from cdk_ecr_deployment import ECRDeployment

• DockerImageName

  from cdk_ecr_deployment import DockerImageName

• S3ArchiveName

  from cdk_ecr_deployment import S3ArchiveName

  Used for deploying images from S3 tarballs.

Quickstart

To get started, create a CDK app (`cdk init app --language python`), then replace the content of your main stack file (e.g., `your_stack.py`) and your `app.py` with the code above. Remember to install `aws-cdk-lib`, `constructs`, and `cdk-ecr-deployment`. Ensure your AWS CLI is configured and your AWS environment is bootstrapped (`cdk bootstrap`) before deploying with `cdk deploy`.

import os
from aws_cdk import (
    App,
    Stack,
    Environment,
    aws_ecr as ecr,
    Aws,
)
from constructs import Construct
from cdk_ecr_deployment import ECRDeployment, DockerImageName

class MyEcrDeploymentStack(Stack):
    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # 1. Define a destination ECR repository
        destination_repo = ecr.Repository(self, "MyDestinationEcrRepo",
            repository_name="my-app-image-destination",
            image_scan_on_push=True,
            image_tag_mutability=ecr.TagMutability.MUTABLE
        )

        # 2. Deploy a Docker image from Docker Hub (e.g., 'nginx:latest') to the ECR repository.
        #    Ensure your AWS credentials are configured (e.g., via AWS CLI) and your
        #    CDK environment is bootstrapped (run 'cdk bootstrap' once per account/region).
        ECRDeployment(self, "DeployPublicNginxImage",
            src=DockerImageName("nginx:latest"),
            dest=DockerImageName(f"{Aws.ACCOUNT_ID}.dkr.ecr.{Aws.REGION}.amazonaws.com/{destination_repo.repository_name}:latest"),
        )

app = App()
MyEcrDeploymentStack(app, "CdkEcrDeploymentExampleStack",
    env=Environment(account=os.getenv('CDK_DEFAULT_ACCOUNT'), region=os.getenv('CDK_DEFAULT_REGION')),
)

app.synth()