cdk-ecr-deployment

CDK construct to synchronize single docker image between docker registries.

Features

Copy image or multi-architecture image index from ECR/external registry to (another) ECR/external registry
Copy an archive tarball image from s3 to ECR/external registry

Usage

from aws_cdk.aws_ecr_assets import DockerImageAsset


image = DockerImageAsset(self, "CDKDockerImage",
    directory=path.join(__dirname, "docker")
)

# Copy from cdk docker image asset to another ECR.
ecrdeploy.ECRDeployment(self, "DeployDockerImage1",
    src=ecrdeploy.DockerImageName(image.image_uri),
    dest=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest")
)

# Copy from docker registry to ECR.
ecrdeploy.ECRDeployment(self, "DeployDockerImage2",
    src=ecrdeploy.DockerImageName("nginx:latest"),
    dest=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx2:latest")
)

# Copy from private docker registry to ECR.
# The format of secret in aws secrets manager must be either:
# - plain text in format <username>:<password>
# - json in format {"username":"<username>","password":"<password>"}
ecrdeploy.ECRDeployment(self, "DeployDockerImage3",
    src=ecrdeploy.DockerImageName("javacs3/nginx:latest", "username:password"),
    # src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'aws-secrets-manager-secret-name'),
    # src: new ecrdeploy.DockerImageName('javacs3/nginx:latest', 'arn:aws:secretsmanager:us-west-2:000000000000:secret:id'),
    dest=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx3:latest")
).add_to_principal_policy(iam.PolicyStatement(
    effect=iam.Effect.ALLOW,
    actions=["secretsmanager:GetSecretValue"
    ],
    resources=["*"]
))

# Copy multi-architecture image index (manifest) with all architectures.
ecrdeploy.ECRDeployment(self, "DeployDockerImage4",
    src=ecrdeploy.DockerImageName("public.ecr.aws/nginx/nginx:latest"),
    dest=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx4:manifest"),
    copy_image_index=True,
    arch_image_tags={
        "amd64": "my-nginx-amd64",
        "arm64": "my-nginx-arm64"
    }
)

# Copy image to a public ECR registry.
# The required ecr-public and sts permissions are automatically attached
# when the destination is a public.ecr.aws URI.
ecrdeploy.ECRDeployment(self, "DeployDockerImage5",
    src=ecrdeploy.DockerImageName(f"{cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/my-nginx:latest"),
    dest=ecrdeploy.DockerImageName("public.ecr.aws/your-alias/your-repo:latest"),
    copy_image_index=True,
    arch_image_tags={
        "amd64": "latest-amd64",
        "arm64": "latest-arm64"
    }
)

Examples: examples/

The examples/ directory contains a runnable CDK app per scenario (local image asset, specific architecture, multi-arch index, retry config, S3 archive, and private-registry credentials). See examples/README.md.

After cloning the repository, install dependencies and run a full build:

yarn install --immutable
yarn build

Then synth or deploy any example:

npx cdk synth --app "npx ts-node examples/docker-image-asset.ts"
npx cdk deploy --app "npx ts-node examples/docker-image-asset.ts"

The private-registry-credentials example needs a Secret in AWS Secrets Manager with your DockerHub credentials (note: secrets incur a cost):

aws secretsmanager create-secret --name DockerHubCredentials --secret-string "username:access-token"
export DOCKERHUB_SECRET_ARN="<ARN>"

If your secret is encrypted, you might have to adjust the example to also grant decrypt permissions.

API

Tech Details & Contributions

The core of this project relies on containers/image (published as the Go module go.podman.io/image/v5) which is used by Skopeo. Please take a look at those projects before contributing.

To support a new docker image source (like docker tarball in s3), you need to implement image transport interface. You could take a look at docker-archive transport for a good start.

Any error in the custom resource provider will show up in the CloudFormation error log as Invalid PhysicalResourceId, because of this: https://github.com/aws/aws-lambda-go/issues/107. You need to go into the CloudWatch Log Group to find the real error.

Metadata

Release files for cdk-ecr-deployment 4.2.59

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cdk-ecr-deployment 4.2.59
File	Size	Uploaded
cdk_ecr_deployment-4.2.59.tar.gz	24.3 MB	Sep 1, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cdk-ecr-deployment 4.2.59
File	Interpreter	ABI	Platform	Reset
cdk_ecr_deployment-4.2.59-py3-none-any.whl 24.3 MB Sep 1, 2026	Python 3	none	any	Details

Total release size: 48.5 MB

Release files / cdk_ecr_deployment-4.2.59.tar.gz

Download URL	cdk_ecr_deployment-4.2.59.tar.gz
Size	24.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`eae46e1bf339198903c6172429bce83f35b1f50f6008091589314b5e07f4c599`
BLAKE2b-256 checksum How to use checksums	`e74800c668a1ecc81ba6b3bb908e6908756c40f51412a476a5aab347d735964e`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.14.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/cdklabs/cdk-ecr-deployment
Publishing commit: github.com/cdklabs/cdk-ecr-deployment/tree/f6bd28ed209e89315a302774203b25a729d40a24

Workflow

Publishing configuration: github.com/cdklabs/cdk-ecr-deployment/blob/f6bd28ed209e89315a302774203b25a729d40a24/.github/workflows/release.yml
Publishing logs: github.com/cdklabs/cdk-ecr-deployment/actions/runs/33524091815/attempts/1

Artifact

Subject: cdk_ecr_deployment-4.2.59.tar.gz
SHA-256 checksum: eae46e1bf339198903c6172429bce83f35b1f50f6008091589314b5e07f4c599 Verifying attestations

Release files / cdk_ecr_deployment-4.2.59-py3-none-any.whl

Download URL	cdk_ecr_deployment-4.2.59-py3-none-any.whl
Size	24.3 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`c35f3d89f539a17857034e08a3d928eae3bea0ce01ca3cbeede3996859615938`
BLAKE2b-256 checksum How to use checksums	`6401e60cf7e9841e97c76bcc9a9b4b4c98a8453b83abc7d98f8a2cffab74b1d2`
Upload date	Sep 1, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.14.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/cdklabs/cdk-ecr-deployment
Publishing commit: github.com/cdklabs/cdk-ecr-deployment/tree/f6bd28ed209e89315a302774203b25a729d40a24

Workflow

Publishing configuration: github.com/cdklabs/cdk-ecr-deployment/blob/f6bd28ed209e89315a302774203b25a729d40a24/.github/workflows/release.yml
Publishing logs: github.com/cdklabs/cdk-ecr-deployment/actions/runs/33524091815/attempts/1

Artifact

Subject: cdk_ecr_deployment-4.2.59-py3-none-any.whl
SHA-256 checksum: c35f3d89f539a17857034e08a3d928eae3bea0ce01ca3cbeede3996859615938 Verifying attestations