Language	Package
.NET	`Amazon.CDK.AWS.ECR`
Go	`github.com/aws/aws-cdk-go/awscdk/v2/awsecr`
Java	`software.amazon.awscdk.services.ecr`
Python	`aws_cdk.aws_ecr`
TypeScript	`aws-cdk-lib` » `aws_ecr`

Amazon ECR Construct Library

This package contains constructs for working with Amazon Elastic Container Registry.

Repositories

Define a repository by creating a new instance of Repository. A repository holds multiple versions of a single container image.

const repository = new ecr.Repository(this, 'Repository');

Example not in your language?

Image scanning

Amazon ECR image scanning helps in identifying software vulnerabilities in your container images. You can manually scan container images stored in Amazon ECR, or you can configure your repositories to scan images when you push them to a repository. To create a new repository to scan on push, simply enable imageScanOnPush in the properties.

const repository = new ecr.Repository(this, 'Repo', {
  imageScanOnPush: true,
});

Example not in your language?

To create an onImageScanCompleted event rule and trigger the event target

declare const repository: ecr.Repository;
declare const target: SomeTarget;

repository.onImageScanCompleted('ImageScanComplete')
  .addTarget(target);

Example not in your language?

Authorization Token

Besides the Amazon ECR APIs, ECR also allows the Docker CLI or a language-specific Docker library to push and pull images from an ECR repository. However, the Docker CLI does not support native IAM authentication methods and additional steps must be taken so that Amazon ECR can authenticate and authorize Docker push and pull requests. More information can be found at at Registry Authentication.

A Docker authorization token can be obtained using the GetAuthorizationToken ECR API. The following code snippets grants an IAM user access to call this API.

const user = new iam.User(this, 'User');
ecr.AuthorizationToken.grantRead(user);

Example not in your language?

If you access images in the Public ECR Gallery as well, it is recommended you authenticate to the registry to benefit from higher rate and bandwidth limits.

See Pricing in https://aws.amazon.com/blogs/aws/amazon-ecr-public-a-new-public-container-registry/ and Service quotas.

The following code snippet grants an IAM user access to retrieve an authorization token for the public gallery.

const user = new iam.User(this, 'User');
ecr.PublicGalleryAuthorizationToken.grantRead(user);

Example not in your language?

This user can then proceed to login to the registry using one of the authentication methods.

Other Grantee

grantPush

The grantPush method grants the specified IAM entity (the grantee) permission to push images to the ECR repository. Specifically, it grants permissions for the following actions:

'ecr:CompleteLayerUpload'
'ecr:UploadLayerPart'
'ecr:InitiateLayerUpload'
'ecr:BatchCheckLayerAvailability'
'ecr:PutImage'
'ecr:GetAuthorizationToken'

Here is an example of granting a user push permissions:

declare const repository: ecr.Repository;

const role = new iam.Role(this, 'Role', {
  assumedBy: new iam.ServicePrincipal('codebuild.amazonaws.com'),
});
repository.grantPush(role);

Example not in your language?

grantPull

The grantPull method grants the specified IAM entity (the grantee) permission to pull images from the ECR repository. Specifically, it grants permissions for the following actions:

'ecr:BatchCheckLayerAvailability'
'ecr:GetDownloadUrlForLayer'
'ecr:BatchGetImage'
'ecr:GetAuthorizationToken'

declare const repository: ecr.Repository;

const role = new iam.Role(this, 'Role', {
  assumedBy: new iam.ServicePrincipal('codebuild.amazonaws.com'),
});
repository.grantPull(role);

Example not in your language?

grantPullPush

The grantPullPush method grants the specified IAM entity (the grantee) permission to both pull and push images from/to the ECR repository. Specifically, it grants permissions for all the actions required for pull and push permissions.

Here is an example of granting a user both pull and push permissions:

declare const repository: ecr.Repository;

const role = new iam.Role(this, 'Role', {
  assumedBy: new iam.ServicePrincipal('codebuild.amazonaws.com'),
});
repository.grantPullPush(role);

Example not in your language?

By using these methods, you can grant specific operational permissions on the ECR repository to IAM entities. This allows for proper management of access to the repository and ensures security.

Image tag immutability

You can set tag immutability on images in your repository using the imageTagMutability construct prop.

new ecr.Repository(this, 'Repo', { imageTagMutability: ecr.TagMutability.IMMUTABLE });

Example not in your language?

Image tag mutability with exclusion filters

ECR supports more granular control over image tag mutability by allowing you to specify exclusion filters. This enables you to make your repository immutable while allowing specific tag patterns to remain mutable (or vice versa).

There are two new mutability options that work with exclusion filters:

MUTABLE_WITH_EXCLUSION: Tags are mutable by default, except those matching the exclusion filters
IMMUTABLE_WITH_EXCLUSION: Tags are immutable by default, except those matching the exclusion filters

Use ImageTagMutabilityExclusionFilter.wildcard() to create filters with wildcard patterns:

// Make all tags immutable except for those starting with 'dev-' or 'test-'
new ecr.Repository(this, 'Repo', {
  imageTagMutability: ecr.TagMutability.IMMUTABLE_WITH_EXCLUSION,
  imageTagMutabilityExclusionFilters: [
    ecr.ImageTagMutabilityExclusionFilter.wildcard('dev-*'),
    ecr.ImageTagMutabilityExclusionFilter.wildcard('test-*'),
  ],
});

Example not in your language?

// Make all tags mutable except for production releases
new ecr.Repository(this, 'Repo', {
  imageTagMutability: ecr.TagMutability.MUTABLE_WITH_EXCLUSION,
  imageTagMutabilityExclusionFilters: [
    ecr.ImageTagMutabilityExclusionFilter.wildcard('prod-*'),
    ecr.ImageTagMutabilityExclusionFilter.wildcard('release-v*'),
  ],
});

Example not in your language?

Exclusion filter pattern rules

Patterns can contain alphanumeric characters, dots (.), underscores (_), hyphens (-), and asterisks (*) as wildcards
Maximum pattern length is 128 characters
You can specify up to 5 exclusion filters per repository

Encryption

By default, Amazon ECR uses server-side encryption with Amazon S3-managed encryption keys which encrypts your data at rest using an AES-256 encryption algorithm. For more control over the encryption for your Amazon ECR repositories, you can use server-side encryption with KMS keys stored in AWS Key Management Service (AWS KMS). Read more about this feature in the ECR Developer Guide.

When you use AWS KMS to encrypt your data, you can either use the default AWS managed key, which is managed by Amazon ECR, by specifying RepositoryEncryption.KMS in the encryption property. Or specify your own customer managed KMS key, by specifying the encryptionKey property.

When encryptionKey is set, the encryption property must be KMS or empty.

In the case encryption is set to KMS but no encryptionKey is set, an AWS managed KMS key is used.

new ecr.Repository(this, 'Repo', {
  encryption: ecr.RepositoryEncryption.KMS
});

Example not in your language?

Otherwise, a customer-managed KMS key is used if encryptionKey was set and encryption was optionally set to KMS.

import * as kms from 'aws-cdk-lib/aws-kms';

new ecr.Repository(this, 'Repo', {
  encryptionKey: new kms.Key(this, 'Key'),
});

Example not in your language?

Automatically clean up repositories

You can set life cycle rules to automatically clean up old images from your repository. The first life cycle rule that matches an image will be applied against that image. For example, the following deletes images older than 30 days, while keeping all images tagged with prod (note that the order is important here):

declare const repository: ecr.Repository;
repository.addLifecycleRule({ tagPrefixList: ['prod'], maxImageCount: 9999 });
repository.addLifecycleRule({ maxImageAge: Duration.days(30) });

Example not in your language?

When using tagPatternList, an image is successfully matched if it matches the wildcard filter.

declare const repository: ecr.Repository;
repository.addLifecycleRule({ tagPatternList: ['prod*'], maxImageCount: 9999 });

Example not in your language?

Repository deletion

When a repository is removed from a stack (or the stack is deleted), the ECR repository will be removed according to its removal policy (which by default will simply orphan the repository and leave it in your AWS account). If the removal policy is set to RemovalPolicy.DESTROY, the repository will be deleted as long as it does not contain any images.

To override this and force all images to get deleted during repository deletion, enable the emptyOnDelete option as well as setting the removal policy to RemovalPolicy.DESTROY.

const repository = new ecr.Repository(this, 'MyTempRepo', {
      removalPolicy: RemovalPolicy.DESTROY,
      emptyOnDelete: true,
});

Example not in your language?

Managing the Resource Policy

You can add statements to the resource policy of the repository using the addToResourcePolicy method. However, be advised that you must not include a resources section in the PolicyStatement.

declare const repository: ecr.Repository;
repository.addToResourcePolicy(new iam.PolicyStatement({
  actions: ['ecr:GetDownloadUrlForLayer'],
  // resources: ['*'], // not currently allowed!
  principals: [new iam.AnyPrincipal()],
}));

Example not in your language?

import existing repository

You can import an existing repository into your CDK app using the Repository.fromRepositoryArn, Repository.fromRepositoryName or Repository.fromLookup method. These methods take the ARN or the name of the repository and returns an IRepository object.

// import using repository name
const repositoryFromName = ecr.Repository.fromRepositoryName(this, 'ImportedRepoByName', 'my-repo-name');

// import using repository ARN
const repositoryFromArn = ecr.Repository.fromRepositoryArn(this, 'ImportedRepoByArn', 'arn:aws:ecr:us-east-1:123456789012:repository/my-repo-name');

// import using repository lookup
// You have to provide either `repositoryArn` or `repositoryName` to lookup the repository
const repositoryFromLookup = ecr.Repository.fromLookup(this, 'ImportedRepoByLookup', {
  repositoryArn: 'arn:aws:ecr:us-east-1:123456789012:repository/my-repo-name',
  repositoryName: 'my-repo-name',
});

Example not in your language?

CloudWatch event rules

You can publish repository events to a CloudWatch event rule with onEvent:

import * as lambda from 'aws-cdk-lib/aws-lambda';
import { LambdaFunction } from 'aws-cdk-lib/aws-events-targets';

const repo = new ecr.Repository(this, 'Repo');
const lambdaHandler = new lambda.Function(this, 'LambdaFunction', {
  runtime: lambda.Runtime.PYTHON_3_12,
  code: lambda.Code.fromInline('# dummy func'),
  handler: 'index.handler',
});

repo.onEvent('OnEventTargetLambda', {
  target: new LambdaFunction(lambdaHandler),
});

Example not in your language?