Namespace Amazon.CDK.AWS.ECR
Amazon ECR Construct Library
---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 the Migrating to AWS CDK v2 guide.
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 verions of a single container image.
var repository = new Repository(this, "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
var repository = new Repository(this, "Repo", new RepositoryProps {
ImageScanOnPush = true
});
To create an onImageScanCompleted
event rule and trigger the event target
Repository repository;
SomeTarget target;
repository.OnImageScanCompleted("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 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.
var user = new User(this, "User");
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 <code>Pricing</code> in https://aws.amazon.com/blogs/aws/amazon-ecr-public-a-new-public-container-registry/ and <a href="https://docs.aws.amazon.com/AmazonECR/latest/public/public-service-quotas.html">Service quotas</a>.
The following code snippet grants an IAM user access to retrieve an authorization token for the public gallery.
var user = new User(this, "User");
PublicGalleryAuthorizationToken.GrantRead(user);
This user can then proceed to login to the registry using one of the authentication methods.
Image tag immutability
You can set tag immutability on images in our repository using the imageTagMutability
construct prop.
new Repository(this, "Repo", new RepositoryProps { ImageTagMutability = TagMutability.IMMUTABLE });
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 Repository(this, "Repo", new RepositoryProps {
Encryption = RepositoryEncryption.KMS
});
Otherwise, a customer-managed KMS key is used if encryptionKey
was set and encryption
was optionally set to KMS
.
using Amazon.CDK.AWS.KMS;
new Repository(this, "Repo", new RepositoryProps {
EncryptionKey = new Key(this, "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):
Repository repository;
repository.AddLifecycleRule(new LifecycleRule { TagPrefixList = new [] { "prod" }, MaxImageCount = 9999 });
repository.AddLifecycleRule(new LifecycleRule { MaxImageAge = Duration.Days(30) });
Classes
AuthorizationToken | Authorization token to access private ECR repositories in the current environment via Docker CLI. |
CfnPublicRepository | A CloudFormation |
CfnPublicRepository.RepositoryCatalogDataProperty | |
CfnPublicRepositoryProps | Properties for defining a |
CfnPullThroughCacheRule | A CloudFormation |
CfnPullThroughCacheRuleProps | Properties for defining a |
CfnRegistryPolicy | A CloudFormation |
CfnRegistryPolicyProps | Properties for defining a |
CfnReplicationConfiguration | A CloudFormation |
CfnReplicationConfiguration.ReplicationConfigurationProperty | The replication configuration for a registry. |
CfnReplicationConfiguration.ReplicationDestinationProperty | An array of objects representing the destination for a replication rule. |
CfnReplicationConfiguration.ReplicationRuleProperty | An array of objects representing the replication destinations and repository filters for a replication configuration. |
CfnReplicationConfiguration.RepositoryFilterProperty | The filter settings used with image replication. |
CfnReplicationConfigurationProps | Properties for defining a |
CfnRepository | A CloudFormation |
CfnRepository.EncryptionConfigurationProperty | The encryption configuration for the repository. This determines how the contents of your repository are encrypted at rest. |
CfnRepository.ImageScanningConfigurationProperty | The image scanning configuration for a repository. |
CfnRepository.LifecyclePolicyProperty | The |
CfnRepositoryProps | Properties for defining a |
LifecycleRule | An ECR life cycle rule. |
OnCloudTrailImagePushedOptions | Options for the onCloudTrailImagePushed method. |
OnImageScanCompletedOptions | Options for the OnImageScanCompleted method. |
PublicGalleryAuthorizationToken | Authorization token to access the global public ECR Gallery via Docker CLI. |
Repository | Define an ECR repository. |
RepositoryAttributes | |
RepositoryBase | Base class for ECR repository. |
RepositoryEncryption | 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). |
RepositoryProps | |
TagMutability | The tag mutability setting for your repository. |
TagStatus | Select images based on tags. |
Interfaces
CfnPublicRepository.IRepositoryCatalogDataProperty | |
CfnReplicationConfiguration.IReplicationConfigurationProperty | The replication configuration for a registry. |
CfnReplicationConfiguration.IReplicationDestinationProperty | An array of objects representing the destination for a replication rule. |
CfnReplicationConfiguration.IReplicationRuleProperty | An array of objects representing the replication destinations and repository filters for a replication configuration. |
CfnReplicationConfiguration.IRepositoryFilterProperty | The filter settings used with image replication. |
CfnRepository.IEncryptionConfigurationProperty | The encryption configuration for the repository. This determines how the contents of your repository are encrypted at rest. |
CfnRepository.IImageScanningConfigurationProperty | The image scanning configuration for a repository. |
CfnRepository.ILifecyclePolicyProperty | The |
ICfnPublicRepositoryProps | Properties for defining a |
ICfnPullThroughCacheRuleProps | Properties for defining a |
ICfnRegistryPolicyProps | Properties for defining a |
ICfnReplicationConfigurationProps | Properties for defining a |
ICfnRepositoryProps | Properties for defining a |
ILifecycleRule | An ECR life cycle rule. |
IOnCloudTrailImagePushedOptions | Options for the onCloudTrailImagePushed method. |
IOnImageScanCompletedOptions | Options for the OnImageScanCompleted method. |
IRepository | Represents an ECR repository. |
IRepositoryAttributes | |
IRepositoryProps |