Install & Compatibility
Where this runs
tested against v1.204.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 35.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.4s · import 0.000s · 36MB
35MB installed
● package 35MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DockerImageAsset
✓ from aws_cdk.aws_ecr_assets import DockerImageAsset
✗ from aws_cdk.aws_ecr import DockerImageAsset
While `DockerImageAsset` exists in `aws_cdk.aws_ecr` for CDK v2's consolidated library, this `aws-cdk-aws-ecr-assets` package (v1) explicitly uses its own namespace.
Demonstrates creating a Docker image asset from a local directory containing a Dockerfile. During `cdk deploy`, this image will be built locally and pushed to an ECR repository. Ensure Docker is running when synthesizing or deploying.
import os
import aws_cdk as cdk
from aws_cdk.aws_ecr_assets import DockerImageAsset
# Create a dummy Dockerfile for the example
docker_context_path = "docker_context"
os.makedirs(docker_context_path, exist_ok=True)
with open(os.path.join(docker_context_path, "Dockerfile"), "w") as f:
f.write("""
FROM public.ecr.aws/amazonlinux/amazonlinux:2
RUN echo "Hello from Docker!" > /app/hello.txt
CMD ["cat", "/app/hello.txt"]
""")
app = cdk.App()
class MyDockerImageStack(cdk.Stack):
def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:
super().__init__(scope, construct_id, **kwargs)
# Creates a Docker image asset from the local 'docker_context' directory.
# The Dockerfile within this directory will be used to build the image.
docker_image_asset = DockerImageAsset(
self, "MyDockerImageAsset",
directory=docker_context_path,
# repository_name="my-cdk-ecr-repo" # Optional: specify ECR repo name
)
cdk.CfnOutput(self, "ImageUri", value=docker_image_asset.image_uri)
MyDockerImageStack(app, "MyDockerImageStack")
app.synth()
# Optional: Clean up dummy Dockerfile and directory after synthesis/deployment
# os.remove(os.path.join(docker_context_path, "Dockerfile"))
# os.rmdir(docker_context_path)
Debug
Known issues
breakingThis package (`aws-cdk-aws-ecr-assets`) is for AWS CDK v1. For AWS CDK v2, the `DockerImageAsset` construct is integrated directly into `aws-cdk-lib` under `aws_cdk.aws_ecr_assets`. While the import path `from aws_cdk.aws_ecr_assets import DockerImageAsset` remains consistent, ensure you are installing and using the correct core CDK library (`aws-cdk.core` for v1 or `aws-cdk-lib` for v2).fixFor CDK v2, install `aws-cdk-lib` (`pip install aws-cdk-lib`) and ensure your `cdk.json` targets v2 features. For v1, install `aws-cdk.core`.
affects: All v1 versions (including 1.204.0) vs. v2.x.x
gotchaThe Docker daemon must be running on your local machine when you run `cdk synth` or `cdk deploy` for stacks that include `DockerImageAsset`. The CDK CLI invokes Docker to build your images.fixEnsure Docker Desktop or your Docker service is running before executing CDK commands. Run `docker info` to verify.
affects: All versions
gotchaThe `directory` argument for `DockerImageAsset` specifies the Docker build context, not just the Dockerfile's path. The Dockerfile itself should reside within this directory (or be specified with `file`). For example, if your Dockerfile is `my_app/Dockerfile`, you should set `directory='my_app'`.fixProvide the path to the directory containing your Dockerfile and any other files needed for the build context. For a Dockerfile named `Dockerfile` in the current directory, use `directory='.'`.
affects: All versions
gotchaThe AWS account and role used for CDK deployment must have sufficient permissions to push images to ECR. This typically includes `ecr:GetAuthorizationToken`, `ecr:BatchCheckLayerAvailability`, `ecr:PutImage`, `ecr:InitiateLayerUpload`, `ecr:UploadLayerPart`, and `ecr:CompleteLayerUpload` actions.fixAttach an IAM policy with the necessary ECR push permissions to your CDK deployment role or user. If using AWS SSO, ensure your SSO permission set includes these.
affects: All versions
Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredRequired as the core library for AWS CDK v1 applications, which this construct library extends.