This documentation is for the developer preview release of the AWS CDK. Do not use this version of the AWS CDK in production. Subsequent releases of the AWS CDK will likely include breaking changes.

AWS CDK Docker Image Assets

This module allows bundling Docker images as assets.

Images are built from a local Docker context directory (with a Dockerfile), uploaded to ECR by the CDK toolkit and/or your app’s CI-CD pipeline, and can be naturally referenced in your CDK app.

import { DockerImageAsset } from '@aws-cdk/assets-docker';

const asset = new DockerImageAsset(this, 'MyBuildImage', {
  directory: path.join(__dirname, 'my-image')

The directory my-image must include a Dockerfile.

This will instruct the toolkit to build a Docker image from my-image, push it to an AWS ECR repository and wire the name of the repository as CloudFormation parameters to your stack.

Use asset.imageUri can be used to reference the image (it includes both the ECR image URL and tag.

Pull Permissions

Depending on the consumer of your image asset, you will need to make sure the principal has permissions to pull the image.

In most cases, you should use the asset.repository.grantPull(principal) method. This will modify the IAM policy of the principal to allow it to pull images from this repository.

If the pulling principal is not in the same account or is an AWS service that doesn’t assume a role in your account (e.g. AWS CodeBuild), pull permissions must be granted on the resource policy (and not on the principal’s policy). To do that, you can use asset.repository.addToResourcePolicy(statement) to grant the desired principal the following permissions: “ecr:GetDownloadUrlForLayer”, “ecr:BatchGetImage” and “ecr:BatchCheckLayerAvailability”.


View in Nuget


<PackageReference Include="Amazon.CDK.Assets.Docker" Version="0.25.3" />


dotnet add package Amazon.CDK.Assets.Docker --version 0.25.3


<package id="Amazon.CDK.Assets.Docker" version="0.25.3" />

View in Maven Central

Apache Buildr:


Apache Ivy:

<dependency groupId="" name="cdk-assets-docker" rev="0.25.3"/>

Apache Maven:


Gradle / Grails:

compile ''

Groovy Grape:

@Grab(group='', module='cdk-assets-docker', version='0.25.3')

View in NPM


$ npm i @aws-cdk/assets-docker@0.25.3


  "@aws-cdk/assets-docker": "^0.25.3"


$ yarn add @aws-cdk/assets-docker@0.25.3

View in NPM


$ npm i @aws-cdk/assets-docker@0.25.3


  "@aws-cdk/assets-docker": "^0.25.3"


$ yarn add @aws-cdk/assets-docker@0.25.3


class @aws-cdk/assets-docker.DockerImageAsset(scope, id, props)

Language-specific names:

using Amazon.CDK.Assets.Docker;
const { DockerImageAsset } = require('@aws-cdk/assets-docker');
import { DockerImageAsset } from '@aws-cdk/assets-docker';

An asset that represents a Docker image.

The image will be created in build time and uploaded to an ECR repository.




The full URI of the image (including a tag). Use this reference to pull

the asset.


Repository where the image is stored


Inherited from @aws-cdk/cdk.Construct

Perform final modifications before synthesis

This method can be implemented by derived constructs in order to perform

final changes before synthesis. prepare() will be called after child

constructs have been prepared.

This is an advanced framework feature. Only use this if you

understand the implications.

Protected method

toString() → string

Inherited from @aws-cdk/cdk.Construct

Returns a string representation of this construct.

Return type:string
validate() → string[]

Inherited from @aws-cdk/cdk.Construct

Validate the current construct.

This method can be implemented by derived constructs in order to perform

validation logic. It is called on all constructs before synthesis.

Protected method

Returns:An array of validation error messages, or an empty array if there the construct is valid.
Return type:string[]

Inherited from @aws-cdk/cdk.Construct

The set of constructs that form the root of this dependable

All resources under all returned constructs are included in the ordering


Type:@aws-cdk/cdk.IConstruct[] (readonly)

Inherited from @aws-cdk/cdk.Construct

Construct node.

Type:@aws-cdk/cdk.ConstructNode (readonly)

DockerImageAssetProps (interface)

class @aws-cdk/assets-docker.DockerImageAssetProps

Language-specific names:

using Amazon.CDK.Assets.Docker;
// DockerImageAssetProps is an interface
import { DockerImageAssetProps } from '@aws-cdk/assets-docker';

The directory where the Dockerfile is stored