Package: aws-cdk.aws-ecr-assets
AWS CDK Docker Image Assets---AWS CDK v1 has reached End-of-Support on 2023-06-01.
This package is no longer being updated, and users should migrate to AWS CDK v2.For more information on how to migrate, see theMigrating to AWS CDK v2guide.This module allows bundling Docker images as assets.Images from DockerfileImages are built from a local Docker context directory (with aDockerfile),
uploaded to Amazon Elastic Container Registry (ECR) by the CDK toolkit
and/or your app's CI/CD pipeline, and can be naturally referenced in your CDK app.fromaws_cdk.aws_ecr_assetsimportDockerImageAssetasset=DockerImageAsset(self,"MyBuildImage",directory=path.join(__dirname,"my-image"))The directorymy-imagemust include aDockerfile.This will instruct the toolkit to build a Docker image frommy-image, push it
to an Amazon ECR repository and wire the name of the repository as CloudFormation
parameters to your stack.By default, all files in the given directory will be copied into the dockerbuild context. If there is a large directory that you know you definitely
don't need in the build context you can improve the performance by adding the
names of files and directories to ignore to a file called.dockerignore, or
pass them via theexcludeproperty. If both are available, the patterns
found inexcludeare appended to the patterns found in.dockerignore.TheignoreModeproperty controls how the set of ignore patterns is
interpreted. The recommended setting for Docker image assets isIgnoreMode.DOCKER. If the context flag@aws-cdk/aws-ecr-assets:dockerIgnoreSupportis set totruein yourcdk.json(this is by default for new projects, but must be set manually for
old projects) thenIgnoreMode.DOCKERis the default and you don't need to
configure it on the asset itself.Useasset.imageUrito reference the image. It includes both the ECR image URL
and tag.You can optionally pass build args to thedocker buildcommand by specifying
thebuildArgsproperty. It is recommended to skip hashing ofbuildArgsfor
values that can change between different machines to maintain a consistent
asset hash.fromaws_cdk.aws_ecr_assetsimportDockerImageAssetasset=DockerImageAsset(self,"MyBuildImage",directory=path.join(__dirname,"my-image"),build_args={"HTTP_PROXY":"http://10.20.30.2:1234"},invalidation=DockerImageAssetInvalidationOptions(build_args=False))You can optionally pass a target to thedocker buildcommand by specifying
thetargetproperty:fromaws_cdk.aws_ecr_assetsimportDockerImageAssetasset=DockerImageAsset(self,"MyBuildImage",directory=path.join(__dirname,"my-image"),target="a-target")You can optionally pass networking mode to thedocker buildcommand by specifying
thenetworkModeproperty:fromaws_cdk.aws_ecr_assetsimportDockerImageAsset,NetworkModeasset=DockerImageAsset(self,"MyBuildImage",directory=path.join(__dirname,"my-image"),network_mode=NetworkMode.HOST)You can optionally pass an alternate platform to thedocker buildcommand by specifying
theplatformproperty:fromaws_cdk.aws_ecr_assetsimportDockerImageAsset,Platformasset=DockerImageAsset(self,"MyBuildImage",directory=path.join(__dirname,"my-image"),platform=Platform.LINUX_ARM64)Images from TarballImages are loaded from a local tarball, uploaded to ECR by the CDK toolkit and/or your app's CI-CD pipeline, and can be
naturally referenced in your CDK app.fromaws_cdk.aws_ecr_assetsimportTarballImageAssetasset=TarballImageAsset(self,"MyBuildImage",tarball_file="local-image.tar")This will instruct the toolkit to add the tarball as a file asset. During deployment it will load the container image
fromlocal-image.tar, push it to an Amazon ECR repository and wire the name of the repository as CloudFormation parameters
to your stack.Publishing images to ECR repositoriesDockerImageAssetis designed for seamless build & consumption of image assets by CDK code deployed to multiple environments
through the CDK CLI or through CI/CD workflows. To that end, the ECR repository behind this construct is controlled by the AWS CDK.
The mechanics of where these images are published and how are intentionally kept as an implementation detail, and the construct
does not support customizations such as specifying the ECR repository name or tags.If you are looking for a way topublishimage assets to an ECR repository in your control, you should consider usingcdklabs/cdk-ecr-deployment, which is able to replicate an image asset from the CDK-controlled ECR repository to a repository of
your choice.Here an example from thecdklabs/cdk-ecr-deploymentproject:// This example available in TypeScript only

import { DockerImageAsset } from '@aws-cdk/aws-ecr-assets';
import * as ecrdeploy from 'cdk-ecr-deployment';

const image = new DockerImageAsset(this, 'CDKDockerImage', {
  directory: path.join(__dirname, 'docker'),
});

new ecrdeploy.ECRDeployment(this, 'DeployDockerImage', {
  src: new ecrdeploy.DockerImageName(image.imageUri),
  dest: new ecrdeploy.DockerImageName(`${cdk.Aws.ACCOUNT_ID}.dkr.ecr.us-west-2.amazonaws.com/test:nginx`),
});⚠️ Please note that this is a 3rd-party construct library and is not officially supported by AWS.
You are welcome to +1this GitHub issueif you would like to see
native support for this use-case in the AWS CDK.Pull PermissionsDepending 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 theasset.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 theresource policy(and not on the principal's policy).
To do that, you can useasset.repository.addToResourcePolicy(statement)to
grant the desired principal the following permissions: "ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage" and "ecr:BatchCheckLayerAvailability".