# Amazon ECR private registry An Amazon ECR private registry hosts your container images in a highly available and scalable architecture. You can use your private registry to manage private image repositories consisting of Docker and Open Container Initiative (OCI) images and artifacts. Each AWS account is provided with a default private Amazon ECR registry. For more information about Amazon ECR public registries, see [Public registries](https://docs.aws.amazon.com/AmazonECR/latest/public/public-registries.html) in the *Amazon Elastic Container Registry Public User Guide*. ## Private registry concepts + The URL for your default private registry is `https://``aws_account_id.dkr.ecr.region.amazonaws.com` . + By default, your account has read and write access to the repositories in your private registry. However, users require permissions to make calls to the Amazon ECR APIs and to push or pull images to and from your private repositories. Amazon ECR provides several managed policies to control user access at varying levels. For more information, see [Amazon Elastic Container Registry Identity-based policy examples](security_iam_id-based-policy-examples.md). + You must authenticate your Docker client to your private registry so that you can use the **docker push** and **docker pull** commands to push and pull images to and from the repositories in that registry. For more information, see [Private registry authentication in Amazon ECR](registry_auth.md). + Private repositories can be controlled with both user access policies and repository policies. For more information about repository policies, see [Private repository policies in Amazon ECR](repository-policies.md). + The repositories in your private registry can be replicated across AWS Regions in your own private registry and across separate accounts by configuring replication for your private registry. For more information, see [Private image replication in Amazon ECR](replication.md). # Private registry authentication in Amazon ECR You can use the AWS Management Console, the AWS CLI, or the AWS SDKs to create and manage private repositories. You can also use those methods to perform some actions on images, such as listing or deleting them. These clients use standard AWS authentication methods. Even though you can use the Amazon ECR API to push and pull images, you're more likely to use the Docker CLI or a language-specific Docker library. The Docker CLI doesn't support native IAM authentication methods. Additional steps must be taken so that Amazon ECR can authenticate and authorize Docker push and pull requests. The registry authentication methods that are detailed in the following sections are available. ## Using the Amazon ECR credential helper Amazon ECR provides a Docker credential helper which makes it easier to store and use Docker credentials when pushing and pulling images to Amazon ECR. For installation and configuration steps, see [Amazon ECR Docker Credential Helper](https://github.com/awslabs/amazon-ecr-credential-helper). **Note** The Amazon ECR Docker credential helper doesn't support multi-factor authentication (MFA) currently. ## Using an authorization token An authorization token's permission scope matches that of the IAM principal used to retrieve the authentication token. An authentication token is used to access any Amazon ECR registry that your IAM principal has access to and is valid for 12 hours. To obtain an authorization token, you must use the [GetAuthorizationToken](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/API_GetAuthorizationToken.html) API operation to retrieve a base64-encoded authorization token containing the username `AWS` and an encoded password. The AWS CLI ` get-login-password` command simplifies this by retrieving and decoding the authorization token which you can then pipe into a **docker login** command to authenticate. **To authenticate Docker to an Amazon ECR private registry with get-login** + To authenticate Docker to an Amazon ECR registry with get-login-password, run the **aws ecr get-login-password** command. When passing the authentication token to the **docker login** command, use the value `AWS` for the username and specify the Amazon ECR registry URI you want to authenticate to. If authenticating to multiple registries, you must repeat the command for each registry. **Important** If you receive an error, install or upgrade to the latest version of the AWS CLI. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) in the *AWS Command Line Interface User Guide*. + [get-login-password](https://docs.aws.amazon.com/cli/latest/reference/ecr/get-login-password.html) (AWS CLI) ``` aws ecr get-login-password --region region | docker login --username AWS --password-stdin aws_account_id.dkr.ecr.region.amazonaws.com ``` + [Get-ECRLoginCommand](https://docs.aws.amazon.com/powershell/latest/reference/items/Get-ECRLoginCommand.html) (AWS Tools for Windows PowerShell) ``` (Get-ECRLoginCommand).Password | docker login --username AWS --password-stdin aws_account_id.dkr.ecr.region.amazonaws.com ``` ## Using HTTP API authentication Amazon ECR supports the [Docker Registry HTTP API](https://docs.docker.com/registry/spec/api/). However, because Amazon ECR is a private registry, you must provide an authorization token with every HTTP request. You can add an HTTP authorization header using the `-H` option for **curl** and pass the authorization token provided by the **get-authorization-token** AWS CLI command. **To authenticate with the Amazon ECR HTTP API** 1. Retrieve an authorization token with the AWS CLI and set it to an environment variable. ``` TOKEN=$(aws ecr get-authorization-token --output text --query 'authorizationData[].authorizationToken') ``` 1. To authenticate to the API, pass the `$TOKEN` variable to the ` -H` option of **curl**. For example, the following command lists the image tags in an Amazon ECR repository. For more information, see the [Docker Registry HTTP API](https://docs.docker.com/registry/spec/api/) reference documentation. ``` curl -i -H "Authorization: Basic $TOKEN" https://aws_account_id.dkr.ecr.region.amazonaws.com/v2/amazonlinux/tags/list ``` The output is as follows: ``` HTTP/1.1 200 OK Content-Type: text/plain; charset=utf-8 Date: Thu, 04 Jan 2018 16:06:59 GMT Docker-Distribution-Api-Version: registry/2.0 Content-Length: 50 Connection: keep-alive {"name":"amazonlinux","tags":["2017.09","latest"]} ``` # Private registry settings in Amazon ECR Amazon ECR uses private registry settings to configure features at the registry level. The private registry settings are configured separately for each Region. You can use private registry settings to configure the following features. + **Registry permissions** – A registry permissions policy provides control over the replication and pull through cache permissions. For more information, see [Private registry permissions in Amazon ECR](registry-permissions.md). + **Pull through cache rules** – A pull through cache rule is used to cache images from an upstream registry in your Amazon ECR private registry. For more information, see [Sync an upstream registry with an Amazon ECR private registry](pull-through-cache.md). + **Replication configuration** – The replication configuration is used to control whether your repositories are copied across AWS Regions or AWS accounts. For more information, see [Private image replication in Amazon ECR](replication.md). + **Repository creation templates** – A repository creation template is used to define the standard settings to apply when new repositories are created by Amazon ECR on your behalf. For example, repositories created by a pull through cache action, create on push, or replication. For more information, see [Templates to control repositories created during a pull through cache, create on push, or replication action](repository-creation-templates.md). + **Scanning configuration** – By default, your registry is enabled for basic scanning. You may enable enhanced scanning which provides an automated, continuous scanning mode that scans for both operating system and programming language package vulnerabilities. For more information, see [Scan images for software vulnerabilities in Amazon ECR](image-scanning.md). + **Pull-time update exclusion** – You can configure pull-time update exclusions to prevent the last pull time from being updated for specific images when they are pulled. This is useful for images that are used for testing or CI/CD purposes where you don't want the pull time to affect lifecycle policy decisions. For more information, see [Pull-time update exclusions](pull-time-update-exclusions.md). + **Blob mounting configuration** – The blob mounting configuration is used to control if the repositories within your registry share common layers rather than store duplicate layers. For more information, see [Blob mounting in Amazon ECR](blob-mounting.md). # Blob mounting in Amazon ECR Amazon ECR supports a capability called blob mounting to share common image layers across repositories within a registry. When enabled, repositories within a single registry can reference layers from other repositories within the same registry instead of storing duplicate copies. When registry blob mounting is enabled, Amazon ECR checks for existing layers in your registry during push operations when mounting parameters are included. If a layer already exists in another repository within the same registry, Amazon ECR will mount the existing layer instead of uploading a duplicate. **Note** OCI clients automatically include mounting parameters if they detect a blob may already exist in a different repository. Amazon ECR attempts mounting only when these parameters are present in the client's POST request. ## Blob mounting concepts + Blob mounting only works within the same registry (same account and region). + Repositories must use identical encryption type and keys. + Blob mounting is not supported for images created via pull through cache. + If you decide to disable blob mounting, existing images that were pushed with blob mounting configured will continue to work and layers will remain mounted. ## Blob mounting configuration You can use the AWS Management Console or AWS CLI to configure blob mounting for your registry. **Note** Users need `ecr:GetDownloadUrlForLayer` IAM permission on a repository to mount layers from it. ------ #### [ AWS Management Console ] Use the following steps to update your registry's blob mounting configuration using the AWS Management Console. **Turn on the blob mounting configuration for your private registry** 1. Open the Amazon ECR console at [ https://console.aws.amazon.com/ecr/private-registry/repositories](https://console.aws.amazon.com/ecr/private-registry/repositories) 1. From the navigation bar, choose the Region. 1. In the navigation pane, choose **Private registry**, **Feature & Settings**, and then choose **Blob mounting**. 1. On the **Blob mounting** page, choose **Enable**. A banner displays indicating that the blob mounting configuration has been updated to be enabled. ------ #### [ AWS CLI ] Use the following command to update your registry's blob mounting configuration using the AWS CLI. + ``` aws ecr put-account-setting --name BLOB_MOUNTING --value ENABLED ``` ------ # Private registry permissions in Amazon ECR Amazon ECR uses a **registry policy** to grant permissions to an AWS principal at the private registry level. The scope is set by choosing the registry policy version. There are two versions with different registry policy scope: version 1 (V1) and version 2 (V2). V2 is the expanded registry policy scope that includes all ECR permissions. For the full list of API actions, see the* [Amazon ECR API Guide](https://docs.aws.amazon.com/AmazonECR/latest/APIReference/Welcome.html) *. The V2 version is the default registry policy scope. For more information about viewing or setting your registry policy scope, see [Switching to the extended registry policy scope](registry-permissions-account-settings.md). For information about general settings for your Amazon ECR private registry, see [Private registry settings in Amazon ECR](registry-settings.md). The versions are detailed as follows. + **V1 ** – For version 1, Amazon ECR only enforces the following permissions at the private registry level. + `ecr:ReplicateImage` – Grants permission to another account, referred to as the source registry, to replicate its images to your registry. This is only used for cross-account replication. + `ecr:BatchImportUpstreamImage` – Grants permission to retrieve the external image and import it to your private registry. + `ecr:CreateRepository` – Grants permission to create a repository in a private registry. This permission is required if the repository storing either the replicated or cached images doesn't already exist in the private registry. + **V2** – For version 2, Amazon ECR allows all ECR actions in the policy and enforces the registry policy in all ECR requests. You can use the console or the CLI to view or change your registry policy scope. **Note** While it is possible to add the `ecr:*` action to a private registry policy, it is considered best practice to only add the specific actions required based on the feature you're using rather than use a wildcard. **Topics** + [Private registry policy examples for Amazon ECR](registry-permissions-examples.md) + [Switching to the extended registry policy scope](registry-permissions-account-settings.md) + [Granting registry permissions for cross account replication in Amazon ECR](registry-permissions-create-replication.md) + [Granting registry permissions for pull through cache in Amazon ECR](registry-permissions-create-pullthroughcache.md) # Private registry policy examples for Amazon ECR The following examples show registry permissions policy statements that you could use to control the permissions that users have to your Amazon ECR registry. **Note** In each example, if the `ecr:CreateRepository` action is removed from your registry policy, replication can still occur. However, for successful replication, you need to create repositories with the same name within your account. ## Example: Allow all IAM principals in a source account to replicate all repositories The following registry permissions policy allows all IAM principals (users and roles) in a source account to replicate all repositories. Note the following: + **Important:** When you specify an AWS account ID as a principal in a policy, you grant access to all IAM users and roles within that account, not just the root user. This provides broad access across the entire account. + **Security Consideration:** Account-level permissions grant access to all IAM entities in the specified account. For more restrictive access, specify individual IAM users, roles, or use condition statements to limit access further. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"ReplicationAccessCrossAccount", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::111122223333:root" }, "Action":[ "ecr:CreateRepository", "ecr:ReplicateImage" ], "Resource": [ "arn:aws:ecr:us-west-2:444455556666:repository/*" ] } ] } ``` ------ ## Example: Allow IAM principals from multiple accounts The following registry permissions policy has two statements. Each statement allows all IAM principals (users and roles) in a source account to replicate all repositories. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"ReplicationAccessCrossAccount1", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::111122223333:root" }, "Action":[ "ecr:CreateRepository", "ecr:ReplicateImage" ], "Resource": [ "arn:aws:ecr:us-west-2:123456789012:repository/*" ] }, { "Sid":"ReplicationAccessCrossAccount2", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::444455556666:root" }, "Action":[ "ecr:CreateRepository", "ecr:ReplicateImage" ], "Resource": [ "arn:aws:ecr:us-west-2:123456789012:repository/*" ] } ] } ``` ------ ## Example: Allow all IAM principals in a source account to replicate all repositories with prefix `prod-`. The following registry permissions policy allows all IAM principals (users and roles) in a source account to replicate all repositories that start with ` prod-`. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"ReplicationAccessCrossAccount", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::111122223333:root" }, "Action":[ "ecr:CreateRepository", "ecr:ReplicateImage" ], "Resource": [ "arn:aws:ecr:us-west-2:444455556666:repository/prod-*" ] } ] } ``` ------ # Switching to the extended registry policy scope **Important** For new users, your registries are automatically configured to use the ` V2` registry policy upon creation. There is no action for you to take. Amazon ECR doesn't recommend reverting to the previous registry policy `V1` . You can use the console or the CLI to view or change your registry policy scope. ------ #### [ AWS Management Console ] Use the following steps to view your account settings. To view or update the registry policy scope, see the CLI procedure on this page. **Turn on the enhanced registry policy for your private registry** 1. Open the Amazon ECR console at [ https://console.aws.amazon.com/ecr/private-registry/repositories](https://console.aws.amazon.com/ecr/private-registry/repositories) 1. From the navigation bar, choose the Region. 1. In the navigation pane, choose **Private registry**, **Feature & Settings**, and then choose **Permissions** . 1. On the **Permissions** page, for **Registry policy** view your policy JSON. If you have the V1 policy, a banner displays with instructions to update to V2. Choose **Enable**. A banner displays indicating that the registry policy scope has been updated to V2. 1. You can also optionally configure permissions with the CLI. For more information, see [Private registry settings in Amazon ECR](registry-settings.md). **Note** To view or update the registry policy scope, see the CLI procedure on this page. ------ #### [ AWS CLI ] Amazon ECR generates the V2 registry policy. Use the following steps to view or update the registry policy scope. You cannot view or change the registry policy scope in the console + To retrieve the registry policy you are currently using. ``` aws ecr get-account-setting --name REGISTRY_POLICY_SCOPE ``` The parameter name is a required field. If you don't provide the name you will receive the following error: ``` aws: error: the following arguments are required: --name ``` View the output for your registry policy command. In the following example output, the registry policy version is V1. ``` { "name": "REGISTRY_POLICY_SCOPE", "value": "V1" } ``` You can change your registry policy version from `V1` to `V2`. V1 is not the recommended registry policy scope. ``` aws ecr put-account-setting --name REGISTRY_POLICY_SCOPE --value value ``` For example, use the following command to update to V2. ``` aws ecr put-account-setting --name REGISTRY_POLICY_SCOPE --value V2 ``` View the output for your registry policy command. In the following example output, the registry policy version was updated to V2. ``` { "name": "REGISTRY_POLICY_SCOPE", "value": "V2" } ``` ------ # Granting registry permissions for cross account replication in Amazon ECR The cross account policy type is used to grant permissions to an AWS principal, allowing the replication of the repositories from a source registry to your registry. By default, you have permission to configure cross-Region replication within your own registry. You only need to configure the registry policy if you're granting another account permission to replicate contents to your registry. A registry policy must grant permission for the `ecr:ReplicateImage` API action. This API is an internal Amazon ECR API that can replicate images between Regions or accounts. You can also grant permission for the ` ecr:CreateRepository` permission, which allows Amazon ECR to create repositories in your registry if they don't exist already. If the `ecr:CreateRepository` permission isn't provided, a repository with the same name as the source repository must be created manually in your registry. If neither is done, replication fails. Any failed `CreateRepository` or `ReplicateImage` API actions show up in CloudTrail. ## To configure a permissions policy for replication (AWS Management Console) 1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/). 1. From the navigation bar, choose the Region to configure your registry policy in. 1. In the navigation pane, choose **Private registry**, choose **Features & Settings**, and then choose **Permissions** . 1. On the **Registry permissions** page, choose **Generate statement**. 1. Complete the following steps to define your policy statement using the policy generator. 1. For **Policy type**, choose **Replication - cross account**. 1. For **Statement id**, enter a unique statement ID. This field is used as the `Sid` on the registry policy. 1. For **Accounts**, enter the account IDs for each account you want to grant permissions to. When specifying multiple account IDs, separate them with a comma. 1. Choose **Save**. ## To configure a permissions policy for replication (AWS CLI) 1. Create a file named `registry_policy.json` and populate it with a registry policy. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement":[ { "Sid":"ReplicationAccessCrossAccount", "Effect":"Allow", "Principal":{ "AWS":"arn:aws:iam::111122223333:root" }, "Action":[ "ecr:CreateRepository", "ecr:ReplicateImage" ], "Resource": [ "arn:aws:ecr:us-west-2:444455556666:repository/*" ] } ] } ``` ------ 1. Create the registry policy using the policy file. ``` aws ecr put-registry-policy \ --policy-text file://registry_policy.json \ --region us-west-2 ``` 1. Retrieve the policy for your registry to confirm. ``` aws ecr get-registry-policy \ --region us-west-2 ``` # Granting registry permissions for pull through cache in Amazon ECR Amazon ECR private registry permissions may be used to scope the permissions of individual IAM entities to use pull through cache. If an IAM entity has more permissions granted by an IAM policy than the registry permissions policy is granting, the IAM policy takes precedence. **To create a private registry permissions policy (AWS Management Console)** 1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/). 1. From the navigation bar, choose the Region to configure your private registry permissions statement in. 1. In the navigation pane, choose **Private registry**, choose **Features & Settings**, and then choose ** Permissions**. 1. On the **Registry permissions** page, choose **Generate statement**. 1. For each pull through cache permissions policy statement you want to create, do the following. 1. For **Policy type**, choose **Pull through cache policy**. 1. For **Statement id**, provide a name for the pull through cache statement policy. 1. For **IAM entities**, specify the users, groups, or roles to include in the policy. 1. For **Cache namespace**, select the pull through cache rule to associate the policy with. 1. For **Repository names**, specify the repository base name to apply the rule for. For example, if you want to specify the Amazon Linux repository on Amazon ECR Public, the repository name would be ` amazonlinux`.