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');

repository = ecr.Repository(self, "Repository")

Repository repository = new Repository(this, "Repository");

var repository = new Repository(this, "Repository");

repository := ecr.NewRepository(this, jsii.String("Repository"))

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,
});

repository = ecr.Repository(self, "Repo",
    image_scan_on_push=True
)

Repository repository = Repository.Builder.create(this, "Repo")
        .imageScanOnPush(true)
        .build();

var repository = new Repository(this, "Repo", new RepositoryProps {
    ImageScanOnPush = true
});

repository := ecr.NewRepository(this, jsii.String("Repo"), &RepositoryProps{
	ImageScanOnPush: jsii.Boolean(true),
})

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);

# repository: ecr.Repository
# target: SomeTarget


repository.on_image_scan_completed("ImageScanComplete").add_target(target)

Repository repository;
SomeTarget target;


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

Repository repository;
SomeTarget target;


repository.OnImageScanCompleted("ImageScanComplete").AddTarget(target);

var repository Repository
var target someTarget


repository.OnImageScanCompleted(jsii.String("ImageScanComplete")).AddTarget(target)

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 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);

user = iam.User(self, "User")
ecr.AuthorizationToken.grant_read(user)

User user = new User(this, "User");
AuthorizationToken.grantRead(user);

var user = new User(this, "User");
AuthorizationToken.GrantRead(user);

user := iam.NewUser(this, jsii.String("User"))
ecr.AuthorizationToken_GrantRead(user)

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);

user = iam.User(self, "User")
ecr.PublicGalleryAuthorizationToken.grant_read(user)

User user = new User(this, "User");
PublicGalleryAuthorizationToken.grantRead(user);

var user = new User(this, "User");
PublicGalleryAuthorizationToken.GrantRead(user);

user := iam.NewUser(this, jsii.String("User"))
ecr.PublicGalleryAuthorizationToken_GrantRead(user)

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);

# repository: ecr.Repository


role = iam.Role(self, "Role",
    assumed_by=iam.ServicePrincipal("codebuild.amazonaws.com")
)
repository.grant_push(role)

Repository repository;


Role role = Role.Builder.create(this, "Role")
        .assumedBy(new ServicePrincipal("codebuild.amazonaws.com"))
        .build();
repository.grantPush(role);

Repository repository;


var role = new Role(this, "Role", new RoleProps {
    AssumedBy = new ServicePrincipal("codebuild.amazonaws.com")
});
repository.GrantPush(role);

var repository Repository


role := iam.NewRole(this, jsii.String("Role"), &RoleProps{
	AssumedBy: iam.NewServicePrincipal(jsii.String("codebuild.amazonaws.com")),
})
repository.GrantPush(role)

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);

# repository: ecr.Repository


role = iam.Role(self, "Role",
    assumed_by=iam.ServicePrincipal("codebuild.amazonaws.com")
)
repository.grant_pull(role)

Repository repository;


Role role = Role.Builder.create(this, "Role")
        .assumedBy(new ServicePrincipal("codebuild.amazonaws.com"))
        .build();
repository.grantPull(role);

Repository repository;


var role = new Role(this, "Role", new RoleProps {
    AssumedBy = new ServicePrincipal("codebuild.amazonaws.com")
});
repository.GrantPull(role);

var repository Repository


role := iam.NewRole(this, jsii.String("Role"), &RoleProps{
	AssumedBy: iam.NewServicePrincipal(jsii.String("codebuild.amazonaws.com")),
})
repository.GrantPull(role)

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);

# repository: ecr.Repository


role = iam.Role(self, "Role",
    assumed_by=iam.ServicePrincipal("codebuild.amazonaws.com")
)
repository.grant_pull_push(role)

Repository repository;


Role role = Role.Builder.create(this, "Role")
        .assumedBy(new ServicePrincipal("codebuild.amazonaws.com"))
        .build();
repository.grantPullPush(role);

Repository repository;


var role = new Role(this, "Role", new RoleProps {
    AssumedBy = new ServicePrincipal("codebuild.amazonaws.com")
});
repository.GrantPullPush(role);

var repository Repository


role := iam.NewRole(this, jsii.String("Role"), &RoleProps{
	AssumedBy: iam.NewServicePrincipal(jsii.String("codebuild.amazonaws.com")),
})
repository.GrantPullPush(role)

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 });

ecr.Repository(self, "Repo", image_tag_mutability=ecr.TagMutability.IMMUTABLE)

Repository.Builder.create(this, "Repo").imageTagMutability(TagMutability.IMMUTABLE).build();

new Repository(this, "Repo", new RepositoryProps { ImageTagMutability = TagMutability.IMMUTABLE });

ecr.NewRepository(this, jsii.String("Repo"), &RepositoryProps{
	ImageTagMutability: ecr.TagMutability_IMMUTABLE,
})

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-*'),
  ],
});

# Make all tags immutable except for those starting with 'dev-' or 'test-'
ecr.Repository(self, "Repo",
    image_tag_mutability=ecr.TagMutability.IMMUTABLE_WITH_EXCLUSION,
    image_tag_mutability_exclusion_filters=[
        ecr.ImageTagMutabilityExclusionFilter.wildcard("dev-*"),
        ecr.ImageTagMutabilityExclusionFilter.wildcard("test-*")
    ]
)

// Make all tags immutable except for those starting with 'dev-' or 'test-'
// Make all tags immutable except for those starting with 'dev-' or 'test-'
Repository.Builder.create(this, "Repo")
        .imageTagMutability(TagMutability.IMMUTABLE_WITH_EXCLUSION)
        .imageTagMutabilityExclusionFilters(List.of(ImageTagMutabilityExclusionFilter.wildcard("dev-*"), ImageTagMutabilityExclusionFilter.wildcard("test-*")))
        .build();

// Make all tags immutable except for those starting with 'dev-' or 'test-'
// Make all tags immutable except for those starting with 'dev-' or 'test-'
new Repository(this, "Repo", new RepositoryProps {
    ImageTagMutability = TagMutability.IMMUTABLE_WITH_EXCLUSION,
    ImageTagMutabilityExclusionFilters = new [] { ImageTagMutabilityExclusionFilter.Wildcard("dev-*"), ImageTagMutabilityExclusionFilter.Wildcard("test-*") }
});

// Make all tags immutable except for those starting with 'dev-' or 'test-'
// Make all tags immutable except for those starting with 'dev-' or 'test-'
ecr.NewRepository(this, jsii.String("Repo"), &RepositoryProps{
	ImageTagMutability: ecr.TagMutability_IMMUTABLE_WITH_EXCLUSION,
	ImageTagMutabilityExclusionFilters: []ImageTagMutabilityExclusionFilter{
		ecr.ImageTagMutabilityExclusionFilter_Wildcard(jsii.String("dev-*")),
		ecr.ImageTagMutabilityExclusionFilter_*Wildcard(jsii.String("test-*")),
	},
})

// 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*'),
  ],
});

# Make all tags mutable except for production releases
ecr.Repository(self, "Repo",
    image_tag_mutability=ecr.TagMutability.MUTABLE_WITH_EXCLUSION,
    image_tag_mutability_exclusion_filters=[
        ecr.ImageTagMutabilityExclusionFilter.wildcard("prod-*"),
        ecr.ImageTagMutabilityExclusionFilter.wildcard("release-v*")
    ]
)

// Make all tags mutable except for production releases
// Make all tags mutable except for production releases
Repository.Builder.create(this, "Repo")
        .imageTagMutability(TagMutability.MUTABLE_WITH_EXCLUSION)
        .imageTagMutabilityExclusionFilters(List.of(ImageTagMutabilityExclusionFilter.wildcard("prod-*"), ImageTagMutabilityExclusionFilter.wildcard("release-v*")))
        .build();

// Make all tags mutable except for production releases
// Make all tags mutable except for production releases
new Repository(this, "Repo", new RepositoryProps {
    ImageTagMutability = TagMutability.MUTABLE_WITH_EXCLUSION,
    ImageTagMutabilityExclusionFilters = new [] { ImageTagMutabilityExclusionFilter.Wildcard("prod-*"), ImageTagMutabilityExclusionFilter.Wildcard("release-v*") }
});

// Make all tags mutable except for production releases
// Make all tags mutable except for production releases
ecr.NewRepository(this, jsii.String("Repo"), &RepositoryProps{
	ImageTagMutability: ecr.TagMutability_MUTABLE_WITH_EXCLUSION,
	ImageTagMutabilityExclusionFilters: []ImageTagMutabilityExclusionFilter{
		ecr.ImageTagMutabilityExclusionFilter_Wildcard(jsii.String("prod-*")),
		ecr.ImageTagMutabilityExclusionFilter_*Wildcard(jsii.String("release-v*")),
	},
})

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
});

ecr.Repository(self, "Repo",
    encryption=ecr.RepositoryEncryption.KMS
)

Repository.Builder.create(this, "Repo")
        .encryption(RepositoryEncryption.KMS)
        .build();

new Repository(this, "Repo", new RepositoryProps {
    Encryption = RepositoryEncryption.KMS
});

ecr.NewRepository(this, jsii.String("Repo"), &RepositoryProps{
	Encryption: ecr.RepositoryEncryption_KMS(),
})

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'),
});

import aws_cdk.aws_kms as kms


ecr.Repository(self, "Repo",
    encryption_key=kms.Key(self, "Key")
)

import software.amazon.awscdk.services.kms.*;


Repository.Builder.create(this, "Repo")
        .encryptionKey(new Key(this, "Key"))
        .build();

using Amazon.CDK.AWS.KMS;


new Repository(this, "Repo", new RepositoryProps {
    EncryptionKey = new Key(this, "Key")
});

import kms "github.com/aws/aws-cdk-go/awscdk"


ecr.NewRepository(this, jsii.String("Repo"), &RepositoryProps{
	EncryptionKey: kms.NewKey(this, jsii.String("Key")),
})

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) });

# repository: ecr.Repository

repository.add_lifecycle_rule(tag_prefix_list=["prod"], max_image_count=9999)
repository.add_lifecycle_rule(max_image_age=Duration.days(30))

Repository repository;

repository.addLifecycleRule(LifecycleRule.builder().tagPrefixList(List.of("prod")).maxImageCount(9999).build());
repository.addLifecycleRule(LifecycleRule.builder().maxImageAge(Duration.days(30)).build());

Repository repository;

repository.AddLifecycleRule(new LifecycleRule { TagPrefixList = new [] { "prod" }, MaxImageCount = 9999 });
repository.AddLifecycleRule(new LifecycleRule { MaxImageAge = Duration.Days(30) });

var repository Repository

repository.AddLifecycleRule(&LifecycleRule{
	TagPrefixList: []*string{
		jsii.String("prod"),
	},
	MaxImageCount: jsii.Number(9999),
})
repository.AddLifecycleRule(&LifecycleRule{
	MaxImageAge: awscdk.Duration_Days(jsii.Number(30)),
})

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 });

# repository: ecr.Repository

repository.add_lifecycle_rule(tag_pattern_list=["prod*"], max_image_count=9999)

Repository repository;

repository.addLifecycleRule(LifecycleRule.builder().tagPatternList(List.of("prod*")).maxImageCount(9999).build());

Repository repository;

repository.AddLifecycleRule(new LifecycleRule { TagPatternList = new [] { "prod*" }, MaxImageCount = 9999 });

var repository Repository

repository.AddLifecycleRule(&LifecycleRule{
	TagPatternList: []*string{
		jsii.String("prod*"),
	},
	MaxImageCount: jsii.Number(9999),
})

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,
});

repository = ecr.Repository(self, "MyTempRepo",
    removal_policy=RemovalPolicy.DESTROY,
    empty_on_delete=True
)

Repository repository = Repository.Builder.create(this, "MyTempRepo")
        .removalPolicy(RemovalPolicy.DESTROY)
        .emptyOnDelete(true)
        .build();

var repository = new Repository(this, "MyTempRepo", new RepositoryProps {
    RemovalPolicy = RemovalPolicy.DESTROY,
    EmptyOnDelete = true
});

repository := ecr.NewRepository(this, jsii.String("MyTempRepo"), &RepositoryProps{
	RemovalPolicy: awscdk.RemovalPolicy_DESTROY,
	EmptyOnDelete: jsii.Boolean(true),
})

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()],
}));

# repository: ecr.Repository

repository.add_to_resource_policy(iam.PolicyStatement(
    actions=["ecr:GetDownloadUrlForLayer"],
    # resources: ['*'], // not currently allowed!
    principals=[iam.AnyPrincipal()]
))

Repository repository;

repository.addToResourcePolicy(PolicyStatement.Builder.create()
        .actions(List.of("ecr:GetDownloadUrlForLayer"))
        // resources: ['*'], // not currently allowed!
        .principals(List.of(new AnyPrincipal()))
        .build());

Repository repository;

repository.AddToResourcePolicy(new PolicyStatement(new PolicyStatementProps {
    Actions = new [] { "ecr:GetDownloadUrlForLayer" },
    // resources: ['*'], // not currently allowed!
    Principals = new [] { new AnyPrincipal() }
}));

var repository Repository

repository.AddToResourcePolicy(iam.NewPolicyStatement(&PolicyStatementProps{
	Actions: []*string{
		jsii.String("ecr:GetDownloadUrlForLayer"),
	},
	// resources: ['*'], // not currently allowed!
	Principals: []IPrincipal{
		iam.NewAnyPrincipal(),
	},
}))

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',
});

# import using repository name
repository_from_name = ecr.Repository.from_repository_name(self, "ImportedRepoByName", "my-repo-name")

# import using repository ARN
repository_from_arn = ecr.Repository.from_repository_arn(self, "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
repository_from_lookup = ecr.Repository.from_lookup(self, "ImportedRepoByLookup",
    repository_arn="arn:aws:ecr:us-east-1:123456789012:repository/my-repo-name",
    repository_name="my-repo-name"
)

// import using repository name
IRepository repositoryFromName = Repository.fromRepositoryName(this, "ImportedRepoByName", "my-repo-name");

// import using repository ARN
IRepository repositoryFromArn = 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
IRepository repositoryFromLookup = Repository.fromLookup(this, "ImportedRepoByLookup", RepositoryLookupOptions.builder()
        .repositoryArn("arn:aws:ecr:us-east-1:123456789012:repository/my-repo-name")
        .repositoryName("my-repo-name")
        .build());

// import using repository name
var repositoryFromName = Repository.FromRepositoryName(this, "ImportedRepoByName", "my-repo-name");

// import using repository ARN
var repositoryFromArn = 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
var repositoryFromLookup = Repository.FromLookup(this, "ImportedRepoByLookup", new RepositoryLookupOptions {
    RepositoryArn = "arn:aws:ecr:us-east-1:123456789012:repository/my-repo-name",
    RepositoryName = "my-repo-name"
});

// import using repository name
repositoryFromName := ecr.Repository_FromRepositoryName(this, jsii.String("ImportedRepoByName"), jsii.String("my-repo-name"))

// import using repository ARN
repositoryFromArn := ecr.Repository_FromRepositoryArn(this, jsii.String("ImportedRepoByArn"), jsii.String("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
repositoryFromLookup := ecr.Repository_FromLookup(this, jsii.String("ImportedRepoByLookup"), &RepositoryLookupOptions{
	RepositoryArn: jsii.String("arn:aws:ecr:us-east-1:123456789012:repository/my-repo-name"),
	RepositoryName: jsii.String("my-repo-name"),
})

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),
});

import aws_cdk.aws_lambda as lambda_
from aws_cdk.aws_events_targets import LambdaFunction


repo = ecr.Repository(self, "Repo")
lambda_handler = lambda_.Function(self, "LambdaFunction",
    runtime=lambda_.Runtime.PYTHON_3_12,
    code=lambda_.Code.from_inline("# dummy func"),
    handler="index.handler"
)

repo.on_event("OnEventTargetLambda",
    target=LambdaFunction(lambda_handler)
)

import software.amazon.awscdk.services.lambda.*;
import software.amazon.awscdk.services.events.targets.LambdaFunction;


Repository repo = new Repository(this, "Repo");
Function lambdaHandler = Function.Builder.create(this, "LambdaFunction")
        .runtime(Runtime.PYTHON_3_12)
        .code(Code.fromInline("# dummy func"))
        .handler("index.handler")
        .build();

repo.onEvent("OnEventTargetLambda", OnEventOptions.builder()
        .target(new LambdaFunction(lambdaHandler))
        .build());

using Amazon.CDK.AWS.Lambda;
using Amazon.CDK.AWS.Events.Targets;


var repo = new Repository(this, "Repo");
var lambdaHandler = new Function(this, "LambdaFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_12,
    Code = Code.FromInline("# dummy func"),
    Handler = "index.handler"
});

repo.OnEvent("OnEventTargetLambda", new OnEventOptions {
    Target = new LambdaFunction(lambdaHandler)
});

import "github.com/aws/aws-cdk-go/awscdk"
import "github.com/aws/aws-cdk-go/awscdk"


repo := ecr.NewRepository(this, jsii.String("Repo"))
lambdaHandler := lambda.NewFunction(this, jsii.String("LambdaFunction"), &FunctionProps{
	Runtime: lambda.Runtime_PYTHON_3_12(),
	Code: lambda.Code_FromInline(jsii.String("# dummy func")),
	Handler: jsii.String("index.handler"),
})

repo.OnEvent(jsii.String("OnEventTargetLambda"), &OnEventOptions{
	Target: awscdk.NewLambdaFunction(lambdaHandler),
})

Mixins

ECR provides mixins that can be applied to L1 and L2 constructs.

RepositoryAutoDeleteImages

Automatically deletes all images from a repository when it is removed from the stack or when the stack is deleted. Requires the repository's removal policy to be set to DESTROY:

new ecr.CfnRepository(this, 'Repo')
  .with(new ecr.mixins.RepositoryAutoDeleteImages());

ecr.CfnRepository(self, "Repo").with(ecr.mixins.RepositoryAutoDeleteImages())

new CfnRepository(this, "Repo").with(new RepositoryAutoDeleteImages());

new CfnRepository(this, "Repo").With(new Mixins.RepositoryAutoDeleteImages());

ecr.NewCfnRepository(this, jsii.String("Repo")).With(mixins.NewRepositoryAutoDeleteImages())

Types

Name	Kind	Summary
Repository	Construct (L2)	Define an ECR repository.
RepositoryBase	Construct (L2)	Base class for ECR repository.
CfnPublicRepository	Construct (L1)	The AWS::ECR::PublicRepository resource specifies an Amazon Elastic Container Registry Public (Amazon ECR Public) repository, where users can push and pull Docker images, Open Container Initiative (OCI) images, and OCI compatible artifacts.
CfnPullThroughCacheRule	Construct (L1)	The AWS::ECR::PullThroughCacheRule resource creates or updates a pull through cache rule.
CfnPullTimeUpdateExclusion	Construct (L1)	The ARN of the IAM principal to remove from the pull time update exclusion list.
CfnRegistryPolicy	Construct (L1)	The AWS::ECR::RegistryPolicy resource creates or updates the permissions policy for a private registry.
CfnRegistryScanningConfiguration	Construct (L1)	The scanning configuration for a private registry.
CfnReplicationConfiguration	Construct (L1)	The AWS::ECR::ReplicationConfiguration resource creates or updates the replication configuration for a private registry.
CfnRepository	Construct (L1)	The AWS::ECR::Repository resource specifies an Amazon Elastic Container Registry (Amazon ECR) repository, where users can push and pull Docker images, Open Container Initiative (OCI) images, and OCI compatible artifacts.
CfnRepositoryCreationTemplate	Construct (L1)	The details of the repository creation template associated with the request.
CfnSigningConfiguration	Construct (L1)	The signing configuration for a registry, which specifies rules for automatically signing images when pushed.
AuthorizationToken	Class	Authorization token to access private ECR repositories in the current environment via Docker CLI.
CfnPublicRepository.RepositoryCatalogDataProperty	Struct	The details about the repository that are publicly visible in the Amazon ECR Public Gallery.
CfnPublicRepositoryProps	Struct	Properties for defining a CfnPublicRepository.
CfnPullThroughCacheRuleProps	Struct	Properties for defining a CfnPullThroughCacheRule.
CfnPullTimeUpdateExclusionProps	Struct	Properties for defining a CfnPullTimeUpdateExclusion.
CfnRegistryPolicyProps	Struct	Properties for defining a CfnRegistryPolicy.
CfnRegistryScanningConfiguration.RepositoryFilterProperty	Struct	The filter settings used with image replication.
CfnRegistryScanningConfiguration.ScanningRuleProperty	Struct	The scanning rules associated with the registry.
CfnRegistryScanningConfigurationProps	Struct	Properties for defining a CfnRegistryScanningConfiguration.
CfnReplicationConfiguration.ReplicationConfigurationProperty	Struct	The replication configuration for a registry.
CfnReplicationConfiguration.ReplicationDestinationProperty	Struct	An array of objects representing the destination for a replication rule.
CfnReplicationConfiguration.ReplicationRuleProperty	Struct	An array of objects representing the replication destinations and repository filters for a replication configuration.
CfnReplicationConfiguration.RepositoryFilterProperty	Struct	The filter settings used with image replication.
CfnReplicationConfigurationProps	Struct	Properties for defining a CfnReplicationConfiguration.
CfnRepository.EncryptionConfigurationProperty	Struct	The encryption configuration for the repository. This determines how the contents of your repository are encrypted at rest.
CfnRepository.ImageScanningConfigurationProperty	Struct	The image scanning configuration for a repository.
CfnRepository.ImageTagMutabilityExclusionFilterProperty	Struct	A filter that specifies which image tags should be excluded from the repository's image tag mutability setting.
CfnRepository.LifecyclePolicyProperty	Struct	The LifecyclePolicy property type specifies a lifecycle policy.
CfnRepositoryCreationTemplate.EncryptionConfigurationProperty	Struct	The encryption configuration for the repository. This determines how the contents of your repository are encrypted at rest.
CfnRepositoryCreationTemplate.ImageTagMutabilityExclusionFilterProperty	Struct	A filter that specifies which image tags should be excluded from the repository's image tag mutability setting.
CfnRepositoryCreationTemplateProps	Struct	Properties for defining a CfnRepositoryCreationTemplate.
CfnRepositoryProps	Struct	Properties for defining a CfnRepository.
CfnSigningConfiguration.RepositoryFilterProperty	Struct	A repository filter used to determine which repositories have their images automatically signed on push.
CfnSigningConfiguration.RuleProperty	Struct	A signing rule that specifies a signing profile and optional repository filters.
CfnSigningConfigurationProps	Struct	Properties for defining a CfnSigningConfiguration.
ImageTagMutabilityExclusionFilter	Class	Represents an image tag mutability exclusion filter for ECR repository.
IRepository	Interface	Represents an ECR repository.
LifecycleRule	Struct	An ECR life cycle rule.
OnCloudTrailImagePushedOptions	Struct	Options for the onCloudTrailImagePushed method.
OnImageScanCompletedOptions	Struct	Options for the OnImageScanCompleted method.
PublicGalleryAuthorizationToken	Class	Authorization token to access the global public ECR Gallery via Docker CLI.
RepositoryAttributes	Struct
RepositoryEncryption	Class	Indicates whether server-side encryption is enabled for the object, and whether that encryption is from the AWS Key Management Service (AWS KMS) or from Amazon S3 managed encryption (SSE-S3).
RepositoryLookupOptions	Struct	Properties for looking up an existing Repository.
RepositoryProps	Struct
TagMutability	Enum	The tag mutability setting for your repository.
TagStatus	Enum	Select images based on tags.