AWS Elastic Container Registry (ECR)

Amazon Elastic Container Registry

Amazon Elastic Container Registry (Amazon ECR) is a container image registry service provided by AWS that offers security, scalability, and reliability. It allows for the creation of private repositories with resource-based permissions through AWS IAM, ensuring that only authorized users or Amazon EC2 instances can access your container repositories and images. Users can utilize their preferred CLI tools to push, pull, and manage Docker images, Open Container Initiative (OCI) images, and artifacts compatible with OCI.

Note: Amazon ECR also supports public container image repositories, allowing broader access and distribution of images. For more detailed information, refer to the Amazon ECR Public User Guide.

ECR Components

Registry: Every AWS account is allocated an Amazon ECR private registry where you can create multiple repositories to store Docker images, Open Container Initiative (OCI) images, and OCI-compatible artifacts

Authorization Token: To push and pull images from an Amazon ECR private registry, your client needs to authenticate as an AWS user.

Repository: Repositories in Amazon ECR hold your Docker images, Open Container Initiative (OCI) images, and OCI-compatible artifacts

Repository Policy: Access to your repositories and their contents can be managed through repository policies.

Image: Container images can be pushed to and pulled from your repositories. These images can then be utilized locally on your development systems or within Amazon ECS task definitions and Amazon EKS pod specifications

ECR Features

Amazon ECR offers a variety of features, including:

Lifecycle Policies: These policies assist in managing your repository images’ lifecycle by defining rules for automatic cleanup of unused images. Rules can be tested prior to implementation.

Image Scanning: This feature identifies software vulnerabilities within your container images. Repositories can be set to automatically scan each new image upon push, with scan results readily accessible. By default, your registry is set up for basic scanning. However, you have the option to activate enhanced scanning, offering an automated, continuous scanning feature. This enhanced mode scans for vulnerabilities not only in the operating system but also in programming language packages.

Cross-Region and Cross-Account Replication: Facilitates the replication of your images across different regions and accounts, enhancing accessibility and redundancy. This feature is adjustable at the registry level for each region.

Pull Through Cache Rules: These rules allow for the caching of images from an upstream registry within your private Amazon ECR registry. Amazon ECR automatically checks with the upstream registry to update the cached image, ensuring it remains up to date.

Namespace: Repository names in Amazon ECR can include namespaces, allowing for the organization of similar repositories. This feature is especially useful in scenarios where multiple teams share the same registry. For instance, Team A could utilize the namespace “team-a” for their repositories, while Team B could use “team-b.” Consequently, both teams can manage an image named “web-app” under their respective namespaces, such as “team-a/web-app” for Team A and “team-b/web-app” for Team B. This setup ensures that each team can use and manage their version of the “web-app” image without affecting the other’s work.

Private repository policies

Amazon ECR employs resource-based permissions to regulate access to its repositories. These permissions enable you to define which users or roles can access a repository and the actions they are allowed to perform. Initially, access to a repository is exclusive to the AWS account that created it. However, you can extend access by applying a policy document to the repository that grants additional permissions.

Repository policies vs IAM policies

Amazon ECR repository policies are specialized IAM policies designed specifically to manage access to individual Amazon ECR repositories. They are a focused subset of IAM policies tailored for precise control over repository access. Conversely, IAM policies can be applied more broadly, granting permissions across the entire Amazon ECR service or to specific resources within it.

Both types of policies—Amazon ECR repository policies and IAM policies—play a role in defining what actions a user or role can perform on a repository. If there’s a conflict where a repository policy allows an action but an IAM policy denies it (or the reverse), the action will be denied. For an action to be permitted, a user or role must be granted permission either through a repository policy or an IAM policy, but not necessarily both.

Note: It’s essential to know that Amazon ECR mandates users to have permissions to invoke the ecr:GetAuthorizationToken API via an IAM policy. This permission is a prerequisite for users to authenticate to a registry and to push or pull images from any Amazon ECR repository.

This example demonstrates an Amazon ECR repository policy designed to grant a specific user the ability to describe the repository and its contained images.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "ECRRepositoryPolicy",
            "Effect": "Allow",
            "Principal": {"AWS": "arn:aws:iam::account-id:user/username"},
            "Action": [
                "ecr:DescribeImages",
                "ecr:DescribeRepositories"
            ]
        }
    ]
}

Tagging a private repository

To facilitate the management of your Amazon ECR repositories, you have the option to attach custom metadata to each repository using AWS resource tags. You can tag new or existing Amazon ECR repositories. Importantly, if tags cannot be attached during the creation of a repository, the creation process is rolled back. This policy ensures that repositories are either successfully created with their respective tags or not created at all, avoiding the scenario where repositories remain untagged. By applying tags to repositories at the moment of their creation, you can avoid the requirement for custom scripts to tag repositories post-creation.

Tagging your resources for billing

Tagging your resources, such as Amazon ECR repositories, plays a crucial role in cost management by assisting in the allocation of expenses once you’ve enabled tags in your Cost & Usage Report. By categorizing your billing data according to the tag key values shared across resources, you can streamline the review of your expenditure. For instance, tagging various resources with a common application name allows you to aggregate and assess the overall cost associated with that application across different services.

Signing an image

Amazon ECR can be integrated with AWS Signer, enabling you to sign your container images. This feature allows you to keep both your container images and their signatures within your private repositories, ensuring the authenticity and integrity of your images. When utilizing Amazon ECR image signing, it’s important to know that first, The signatures that are stored within your repository are included in the overall count towards the service quota for the maximum number of images allowed per repository, and second, If you’re implementing Amazon ECR lifecycle policies, be aware that any rule action set to expire or delete an OCI image index will lead Amazon ECR to remove any signatures associated with that image index within 24 hours. You can find more information about the process of signing your image here.

Private image replication

You have the ability to set up your Amazon ECR private registry to enable the replication of your repositories. Amazon ECR facilitates replication across both different regions and different accounts. For replication to a different account (cross-account replication), the receiving account must establish a registry permissions policy that permits the replication process from the source registry.

The following should be considered when using private image replication:

• Replication of Content: Only the content pushed to a repository after the replication setup will be replicated. Existing content prior to replication configuration won’t be replicated. Amazon ECR ensures synchronization between the source and destination once replication is configured.
• Repository Name Consistency: The name of the repository remains the same across regions and accounts after replication. Changing the repository name during replication is not supported.
• Cross-Region Replication Requirements: Both source and destination accounts need to opt-in to the regions involved before replication actions can occur.
• Partition Limitations: Cross-region replication cannot occur between AWS partitions (e.g., from us-west-2 to cn-north-1).
• No Delete Actions: Registry replication does not include delete actions; replicated images and repositories must be manually deleted if no longer needed.
• Policies and Settings Non-replication: Repository and lifecycle policies, along with repository settings like tag immutability, image scanning, and KMS encryption settings, are not replicated and must be configured individually at each destination.
• Handling of Tag Immutability: If tag immutability is enabled and a replicated image uses the same tag as an existing image, the new image will be replicated without the duplicated tag, possibly resulting in the image being untagged.

Lifecycle policies

Amazon ECR lifecycle policies offer enhanced control over the management of image lifecycles within a private repository. These policies consist of multiple rules, with each rule specifying an action for Amazon ECR to execute, enabling the automated deletion of container images based on specified criteria such as age or the number of images(a way to automate the image cleaning up). Images that meet the set criteria for expiration according to your lifecycle policy are expected to be marked as expired within 24 hours. Actions taken by Amazon ECR in response to lifecycle policies are recorded as events in AWS CloudTrail, providing an audit trail of the lifecycle management process.

A lifecycle policy preview offers a method to assess the effects of a lifecycle policy on an image repository before its implementation. It is recommended as a best practice to conduct a preview of the lifecycle policy prior to applying it to a repository. The following diagram shows the lifecycle policy workflow from AWS website:

Lifecycle policy template

The content of a lifecycle policy is assessed prior to its association with a repository. Below is the JSON syntax template for defining a lifecycle policy:

{
    "rules": [
        {
            "rulePriority": integer,
            "description": "string",
            "selection": {
                "tagStatus": "tagged"|"untagged"|"any",
                "tagPatternList": list<string>,
                "tagPrefixList": list<string>,
                "countType": "imageCountMoreThan"|"sinceImagePushed",
                "countUnit": "string",
                "countNumber": integer
            },
            "action": {
                "type": "expire"
            }
        }
    ]
}

The provided example illustrates the syntax for a lifecycle policy designed to expire images tagged with a prefix of “prod” and that are older than 60 days:

{
    "rules": [
        {
            "rulePriority": 1,
            "description": "Expire images older than 60 days",
            "selection": {
                "tagStatus": "tagged",
                "tagPatternList": ["prod*"],
                "countType": "sinceImagePushed",
                "countUnit": "days",
                "countNumber": 60
            },
            "action": {
                "type": "expire"
            }
        }
    ]
}

Image tag mutability

Tag immutability can be enabled for a repository to ensure image tags cannot be overwritten. Once this setting is activated, trying to push an image with a tag that already exists within the repository will result in an ImageTagAlreadyExistsException error. The immutability setting applies universally within the repository, meaning it’s not possible to have a mix of mutable and immutable tags; all tags become immutable.

Image scanning

Amazon ECR offers image scanning to detect software vulnerabilities in container images, with two types of scanning available:

• Enhanced Scanning: This integrates Amazon ECR with Amazon Inspector for automated, continuous scanning of repositories, covering both operating system and programming language package vulnerabilities. As new vulnerabilities are discovered, scan results are updated, and Amazon Inspector sends notifications via EventBridge.

• Basic Scanning: Utilizes the Common Vulnerabilities and Exposures (CVEs) database from the open-source Clair project. Repositories can be set to automatically scan images upon push, or scans can be initiated manually. Amazon ECR then provides a report of the findings.