AWS CDK ECR Assets

1.204.0 · active · verified Thu Apr 16

The `aws-cdk-aws-ecr-assets` library provides constructs for managing Docker image assets that are deployed to Amazon Elastic Container Registry (ECR). This package specifically targets AWS CDK v1 applications. It simplifies the process of building local Docker images and pushing them to ECR as part of your CDK deployment. The current version is `1.204.0`, following the frequent release cadence of the AWS CDK.

Common errors

```
Docker daemon is not running
```
cause The local Docker service required for building the image is not active.

fix Start your Docker daemon (e.g., Docker Desktop) before running `cdk synth` or `cdk deploy`.
```
ModuleNotFoundError: No module named 'aws_cdk.aws_ecr_assets'
```
cause The `aws-cdk-aws-ecr-assets` library or `aws-cdk-lib` (for v2) is not installed in your Python environment, or there's a version mismatch.

fix For CDK v1: `pip install aws-cdk-aws-ecr-assets aws-cdk.core`. For CDK v2: `pip install aws-cdk-lib`. Ensure your virtual environment is active.
```
directory './nonexistent/path' does not exist
```
cause The path provided to the `directory` argument of `DockerImageAsset` does not point to an existing local directory.

fix Correct the `directory` path to point to an actual directory on your filesystem that contains your Dockerfile and build context files.
```
AccessDeniedException: User: arn:aws:sts::... is not authorized to perform: ecr:GetAuthorizationToken on resource: ...
```
cause The AWS credentials used by CDK do not have the required permissions to authenticate with ECR and push images.

fix Verify that your AWS user or role has an IAM policy attached that grants ECR push permissions (e.g., `ecr:*` on the relevant repository, or specific actions like `ecr:GetAuthorizationToken`, `ecr:PutImage`, etc.).

Warnings

breaking This 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).
Fix: For 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`.
gotcha The 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.
Fix: Ensure Docker Desktop or your Docker service is running before executing CDK commands. Run `docker info` to verify.
gotcha The `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'`.
Fix: Provide 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='.'`.
gotcha The 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.
Fix: Attach 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.

Install

pip install aws-cdk-aws-ecr-assets aws-cdk.core Install for AWS CDK v1

Imports

DockerImageAsset
wrong:
```
from aws_cdk.aws_ecr import DockerImageAsset
```
correct:
```
from aws_cdk.aws_ecr_assets 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.

Quickstart

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)

view raw JSON →