AWS CDK ECR Construct Library (v1)

1.204.0 · abandoned · verified Thu Apr 16

This is the AWS Cloud Development Kit (CDK) v1 construct library for Amazon Elastic Container Registry (ECR). It provides high-level constructs to define ECR resources using familiar programming languages. As of June 1, 2023, AWS CDK v1 has reached End-of-Support, meaning this package is no longer updated, and users are strongly advised to migrate to AWS CDK v2. In v2, ECR constructs are part of the unified `aws-cdk-lib` package.

Common errors

```
ModuleNotFoundError: No module named 'aws_cdk.aws_ecr'
```
cause Attempting to use `aws_cdk.aws_ecr` import style (common in v2) without `aws-cdk-lib` installed, or with only the v1 `aws-cdk.aws-ecr` package. Alternatively, trying v1 imports like `aws_cdk.aws_ecr` with `aws-cdk-lib` installed, but the specific v1 package is missing.

fix For CDK v2: Ensure `aws-cdk-lib` is installed (`pip install aws-cdk-lib`) and imports are `from aws_cdk import aws_ecr`. For CDK v1: Ensure `aws-cdk.aws-ecr` is installed (`pip install aws-cdk.aws-ecr`) and imports are `import aws_cdk.aws_ecr as ecr`. Best practice is to migrate to v2.
```
RuntimeError: The CDK environment is not bootstrapped in the region 'us-east-1' for account '123456789012'. Please run 'cdk bootstrap aws://123456789012/us-east-1'.
```
cause Trying to deploy a CDK application without the required bootstrap stack in the target account/region, or the bootstrap stack is an older v1 version incompatible with a v2 CLI.

fix Run `cdk bootstrap aws://ACCOUNT-ID/REGION` (e.g., `cdk bootstrap aws://123456789012/us-east-1`) to provision or update the modern bootstrap stack. Ensure your `aws-cdk` CLI is updated to v2.
```
Assets must be enabled for this stack or a parent stack to use DockerImageFunction. If you are using 'aws-cdk-lib.aws_lambda_docker.DockerImageFunction', set 'bundling.local' to false in the construct props.
```
cause This error often occurs when deploying Docker image-based Lambda functions or similar assets. In CDK v2, the asset handling mechanism changed, and older patterns or missing bootstrap resources can trigger this. It might indicate an incompatibility between the CDK CLI and the CDK library version being used, or an outdated bootstrap stack not configured for asset publishing.

fix First, ensure your environment is bootstrapped with the latest CDK v2 bootstrap stack (`cdk bootstrap`). If the issue persists, review the specific construct's documentation, as it might require explicit `asset_options` or `bundling` configurations (e.g., `bundling=cdk.BundlingOptions(image=cdk.DockerImage.from_registry("public.ecr.aws/lambda/python:3.9"))`). This can also be a symptom of v1 constructs trying to build assets using v2 CLI, so migration to v2 is the ultimate fix.

Warnings

breaking AWS CDK v1 reached End-of-Support on June 1, 2023. This package (aws-cdk.aws-ecr) is no longer being updated, and new features, bug fixes, or security patches will not be released.
Fix: Migrate your CDK applications to AWS CDK v2. For ECR functionality, use `aws-cdk-lib` and `from aws_cdk import aws_ecr` for imports.
breaking CDK v2 consolidates all stable constructs into a single `aws-cdk-lib` package. This changes import statements from `@aws-cdk/aws-service` style (v1) to `aws_cdk.aws_service` (v2) for Python.
Fix: Update your `requirements.txt` to `aws-cdk-lib` and `constructs`, and change import statements from `import aws_cdk.aws_ecr as ecr` to `from aws_cdk import aws_ecr`.
breaking AWS CDK v2 requires a new version of the CDK Toolkit (CLI) and a re-bootstrap of your AWS environment with the modern bootstrap stack. Deploying v1 stacks with v2 CLI or vice-versa can lead to incompatibilities.
Fix: Globally update `aws-cdk` CLI to v2 (`npm install -g aws-cdk@latest`) and re-bootstrap your AWS account (`cdk bootstrap`). Ensure your deployment roles have updated permissions for v2 assets if you use fine-grained access.
gotcha Feature flags in `cdk.json` from v1 projects are largely deprecated in v2. Leaving them in can cause unexpected behavior or prevent new v2 defaults from applying.
Fix: Remove most v1 feature flags from `cdk.json` that start with `@aws-cdk/`. A small subset can be set to `false` to revert to specific v1 behaviors if necessary, but review the migration guide carefully.

Install

pip install aws-cdk.aws-ecr Install (CDK v1)
pip install aws-cdk-lib constructs Install (CDK v2 - Recommended)

Imports

Repository
wrong:
```
from aws_cdk.aws_ecr import Repository
```
correct:
```
from aws_cdk import aws_ecr as ecr
# For CDK v2, use:
# from aws_cdk import aws_ecr
```
CDK v1 typically uses `import aws_cdk.aws_ecr as ecr` while v2 consolidates to `aws_cdk.aws_ecr` directly under `aws_cdk` or `aws_cdk_lib.aws_ecr`.

Quickstart

This quickstart demonstrates creating a basic ECR repository using the `aws-cdk-aws-ecr` (v1) construct. It defines a stack that provisions an ECR repository named 'my-application-images-v1'. It is crucial to note that this is a v1 example, and migration to AWS CDK v2 is strongly recommended.

import os
from aws_cdk import (
    core as cdk,
    aws_ecr as ecr
)

class ECRStackV1(cdk.Stack):
    def __init__(self, scope: cdk.Construct, construct_id: str, **kwargs) -> None:
        super().__init__(scope, construct_id, **kwargs)

        # Create an ECR repository
        repository = ecr.Repository(self, "MyRepositoryV1",
            repository_name="my-application-images-v1"
        )

        cdk.CfnOutput(self, "RepositoryUri", value=repository.repository_uri)

app = cdk.App()
ECRStackV1(app, "ECRStackV1",
    env=cdk.Environment(
        account=os.environ.get('CDK_DEFAULT_ACCOUNT', os.environ.get('AWS_ACCOUNT_ID')),
        region=os.environ.get('CDK_DEFAULT_REGION', os.environ.get('AWS_REGION', 'us-east-1'))
    )
)
app.synth()

# NOTE: This quickstart is for AWS CDK v1, which is End-of-Support. 
# For AWS CDK v2, the import paths and package structure are different. 
# You should migrate to v2 and use `from aws_cdk import aws_ecr`.

view raw JSON →