aws-cdk.aws-ecr-assets

What it is and what it does

This package extends AWS CDK v1 with the ability to package Docker images as first-class assets within your infrastructure-as-code. It handles building images from local Dockerfiles or loading them from tarballs, then automatically uploads them to an AWS-managed ECR repository during deployment. The package integrates with the CDK toolkit and CI/CD pipelines to manage the full lifecycle—from build context preparation (with `.dockerignore` support) through image push and CloudFormation parameter wiring.

The module supports build-time customization via build arguments, target stages, networking modes, and platform selection. Images are referenced in CDK code via `asset.imageUri`, which includes both the ECR URL and tag. Pull permissions are managed through IAM policy grants on the asset's repository, with special handling for cross-account and AWS service consumers.

Use it for:

• Build and deploy custom Docker images as part of CDK stacks without manual ECR repository management.
• Package application containers with build arguments and multi-stage Dockerfile targets in infrastructure code.
• Reference built images in CDK constructs for ECS, Lambda, or other AWS services that consume container images.
• Automate image versioning and tagging through CDK asset hashing for consistent deployments across environments.
• Grant pull permissions to ECS tasks, Lambda functions, or cross-account principals via the asset's repository interface.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Bundles Docker images as AWS CDK assets, building from Dockerfiles or tarballs and uploading them to Amazon ECR for use in CDK applications.

No—do not install this package for new projects. AWS CDK v1 reached end-of-support on 2023-06-01 and is no longer being updated. Migrate to AWS CDK v2 instead, which includes the equivalent functionality in `aws-cdk-lib.aws_ecr_assets`. Installing v1 packages exposes you to unpatched security issues and lack of ongoing maintenance.

Install

aws-cdk-aws-ecr-assets on PyPI

pip install aws-cdk-aws-ecr-assets

uv add aws-cdk-aws-ecr-assets

poetry add aws-cdk-aws-ecr-assets

Installing aws-cdk.aws-ecr-assets

Before you install

Low install friction with a wheel distribution. The package is in active maintenance status but carries a critical caveat: AWS CDK v1 reached end-of-support on 2023-06-01 and is no longer being updated; users should migrate to AWS CDK v2.

License in practice

Licensed under Apache-2.0 (permissive), allowing commercial use, modification, and distribution with minimal restrictions.

Quickstart

from aws_cdk.aws_ecr_assets import DockerImageAsset
import os

asset = DockerImageAsset(self, "MyImage",
    directory=os.path.join(os.path.dirname(__file__), "my-image")
)
image_uri = asset.imageUri

Requires Docker to be installed and running on the build machine; the target directory must contain a Dockerfile.

Verify before relying

• Whether v1 packages continue to receive security patches despite end-of-support status.
• Compatibility and migration effort when upgrading from v1 to v2 in existing CDK applications.

Package facts

Evidence: aws_cdk.aws_ecr_assets-1.204.0-py3-none-any.whl

Tags

More Build Tools packages