{"id":6558,"library":"cdk-ecr-deployment","title":"CDK ECR Deployment","description":"cdk-ecr-deployment is a CDK construct that facilitates the deployment and synchronization of Docker images to Amazon ECR. It enables copying images from various sources, including Docker Hub, other ECR repositories, and S3 archive tarballs, to a specified ECR destination. The library is actively maintained, with version 4.2.0 currently available, and receives frequent minor and patch releases.","status":"active","version":"4.2.0","language":"en","source_language":"en","source_url":"https://github.com/cdklabs/cdk-ecr-deployment","tags":["aws","cdk","ecr","docker","deployment","container"],"install":[{"cmd":"pip install cdk-ecr-deployment aws-cdk-lib constructs","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required Python interpreter version for the library.","package":"python","version":"~=3.9","optional":false},{"reason":"Peer dependency as this is an AWS CDK construct, essential for defining and deploying AWS infrastructure.","package":"aws-cdk-lib","version":">=2.0.0","optional":false},{"reason":"Core peer dependency for all AWS CDK constructs.","package":"constructs","version":">=10.0.0","optional":false}],"imports":[{"symbol":"ECRDeployment","correct":"from cdk_ecr_deployment import ECRDeployment"},{"symbol":"DockerImageName","correct":"from cdk_ecr_deployment import DockerImageName"},{"note":"Used for deploying images from S3 tarballs.","symbol":"S3ArchiveName","correct":"from cdk_ecr_deployment import S3ArchiveName"}],"quickstart":{"code":"import os\nfrom aws_cdk import (\n    App,\n    Stack,\n    Environment,\n    aws_ecr as ecr,\n    Aws,\n)\nfrom constructs import Construct\nfrom cdk_ecr_deployment import ECRDeployment, DockerImageName\n\nclass MyEcrDeploymentStack(Stack):\n    def __init__(self, scope: Construct, construct_id: str, **kwargs) -> None:\n        super().__init__(scope, construct_id, **kwargs)\n\n        # 1. Define a destination ECR repository\n        destination_repo = ecr.Repository(self, \"MyDestinationEcrRepo\",\n            repository_name=\"my-app-image-destination\",\n            image_scan_on_push=True,\n            image_tag_mutability=ecr.TagMutability.MUTABLE\n        )\n\n        # 2. Deploy a Docker image from Docker Hub (e.g., 'nginx:latest') to the ECR repository.\n        #    Ensure your AWS credentials are configured (e.g., via AWS CLI) and your\n        #    CDK environment is bootstrapped (run 'cdk bootstrap' once per account/region).\n        ECRDeployment(self, \"DeployPublicNginxImage\",\n            src=DockerImageName(\"nginx:latest\"),\n            dest=DockerImageName(f\"{Aws.ACCOUNT_ID}.dkr.ecr.{Aws.REGION}.amazonaws.com/{destination_repo.repository_name}:latest\"),\n        )\n\napp = App()\nMyEcrDeploymentStack(app, \"CdkEcrDeploymentExampleStack\",\n    env=Environment(account=os.getenv('CDK_DEFAULT_ACCOUNT'), region=os.getenv('CDK_DEFAULT_REGION')),\n)\n\napp.synth()","lang":"python","description":"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`."},"warnings":[{"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`)","message":"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.","severity":"breaking","affected_versions":"<4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<4.1.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade to `cdk-ecr-deployment` version 4.2.0 or newer for built-in authentication support for `public.ecr.aws` destinations.","message":"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.","severity":"gotcha","affected_versions":"<4.2.0"},{"fix":"Ensure your Secrets Manager secret for private registry authentication follows the required plain text or JSON format specified in the documentation.","message":"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>\"}`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions (when using DockerImageAsset)"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}