{"id":8858,"library":"aws-cdk-aws-ecr-assets","title":"AWS CDK ECR Assets","description":"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.","status":"active","version":"1.204.0","language":"en","source_language":"en","source_url":"https://github.com/aws/aws-cdk.git","tags":["aws","cdk","ecr","docker","assets","infrastructure-as-code","cloud"],"install":[{"cmd":"pip install aws-cdk-aws-ecr-assets aws-cdk.core","lang":"bash","label":"Install for AWS CDK v1"}],"dependencies":[{"reason":"Required as the core library for AWS CDK v1 applications, which this construct library extends.","package":"aws-cdk.core","optional":false}],"imports":[{"note":"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.","wrong":"from aws_cdk.aws_ecr import DockerImageAsset","symbol":"DockerImageAsset","correct":"from aws_cdk.aws_ecr_assets import DockerImageAsset"}],"quickstart":{"code":"import os\nimport aws_cdk as cdk\nfrom aws_cdk.aws_ecr_assets import DockerImageAsset\n\n# Create a dummy Dockerfile for the example\ndocker_context_path = \"docker_context\"\nos.makedirs(docker_context_path, exist_ok=True)\nwith open(os.path.join(docker_context_path, \"Dockerfile\"), \"w\") as f:\n    f.write(\"\"\"\nFROM public.ecr.aws/amazonlinux/amazonlinux:2\nRUN echo \"Hello from Docker!\" > /app/hello.txt\nCMD [\"cat\", \"/app/hello.txt\"]\n\"\"\")\n\napp = cdk.App()\n\nclass MyDockerImageStack(cdk.Stack):\n    def __init__(self, scope: cdk.App, construct_id: str, **kwargs) -> None:\n        super().__init__(scope, construct_id, **kwargs)\n\n        # Creates a Docker image asset from the local 'docker_context' directory.\n        # The Dockerfile within this directory will be used to build the image.\n        docker_image_asset = DockerImageAsset(\n            self, \"MyDockerImageAsset\",\n            directory=docker_context_path,\n            # repository_name=\"my-cdk-ecr-repo\" # Optional: specify ECR repo name\n        )\n\n        cdk.CfnOutput(self, \"ImageUri\", value=docker_image_asset.image_uri)\n\nMyDockerImageStack(app, \"MyDockerImageStack\")\napp.synth()\n\n# Optional: Clean up dummy Dockerfile and directory after synthesis/deployment\n# os.remove(os.path.join(docker_context_path, \"Dockerfile\"))\n# os.rmdir(docker_context_path)","lang":"python","description":"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."},"warnings":[{"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`.","message":"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).","severity":"breaking","affected_versions":"All v1 versions (including 1.204.0) vs. v2.x.x"},{"fix":"Ensure Docker Desktop or your Docker service is running before executing CDK commands. Run `docker info` to verify.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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='.'`.","message":"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'`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Start your Docker daemon (e.g., Docker Desktop) before running `cdk synth` or `cdk deploy`.","cause":"The local Docker service required for building the image is not active.","error":"Docker daemon is not running"},{"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.","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.","error":"ModuleNotFoundError: No module named 'aws_cdk.aws_ecr_assets'"},{"fix":"Correct the `directory` path to point to an actual directory on your filesystem that contains your Dockerfile and build context files.","cause":"The path provided to the `directory` argument of `DockerImageAsset` does not point to an existing local directory.","error":"directory './nonexistent/path' does not exist"},{"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.).","cause":"The AWS credentials used by CDK do not have the required permissions to authenticate with ECR and push images.","error":"AccessDeniedException: User: arn:aws:sts::... is not authorized to perform: ecr:GetAuthorizationToken on resource: ..."}]}