Network Pipe Manufacturer

    TypeScript icon, indicating that this package has built-in type declarations

    1.169.0 • Public • Published

    Amazon ECR Construct Library

    cfn-resources: Stable

    cdk-constructs: Stable

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


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

    const repository = new ecr.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

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

    To create an onImageScanCompleted event rule and trigger the event target

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

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

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

    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 ecr.Repository(this, 'Repo', { imageTagMutability: ecr.TagMutability.IMMUTABLE });


    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

    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/aws-kms';
    new ecr.Repository(this, 'Repo', {
      encryptionKey: new kms.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):

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


    npm i @aws-cdk/aws-ecr

    DownloadsWeekly Downloads






    Unpacked Size

    666 kB

    Total Files


    Last publish


    • romainmuller
    • amzn-oss
    • rix0rrr
    • aws-cdk-team