Amazon ECR

(1)

Amazon ECR

User Guide

API Version 2015-09-21

(2)

Amazon ECR: User Guide

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

What is Amazon Elastic Container Registry?

Amazon Elastic Container Registry (Amazon ECR) is an AWS managed container image registry service that is secure, scalable, and reliable. Amazon ECR supports private repositories with resource-based permissions using AWS IAM. This is so that speciﬁed users or Amazon EC2 instances can access your container repositories and images. You can use your preferred CLI to push, pull, and manage Docker images, Open Container Initiative (OCI) images, and OCI compatible artifacts.

NoteAmazon ECR supports public container image repositories as well. For more information, see What is Amazon ECR Public in the Amazon ECR Public User Guide.

The AWS container services team maintains a public roadmap on GitHub. It contains information about what the teams are working on and allows all AWS customers the ability to give direct feedback. For more information, see AWS Containers Roadmap.

Components of Amazon ECR

Amazon ECR contains the following components:

Registry

An Amazon ECR private registry is provided to each AWS account; you can create one or more repositories in your registry and store images in them. For more information, see Amazon ECR private registry (p. 14).

Authorization token

Your client must authenticate to Amazon ECR registries as an AWS user before it can push and pull images. For more information, see Private registry authentication (p. 14).

Repository

An Amazon ECR repository contains your Docker images, Open Container Initiative (OCI) images, and OCI compatible artifacts. For more information, see Amazon ECR private repositories (p. 22).

Repository policy

You can control access to your repositories and the images within them with repository policies. For more information, see Private repository policies (p. 25).

Image

You can push and pull container images to your repositories. You can use these images locally on your development system, or you can use them in Amazon ECS task deﬁnitions and Amazon EKS pod speciﬁcations. For more information, see Using Amazon ECR images with Amazon ECS (p. 76) and Using Amazon ECR Images with Amazon EKS (p. 77).

Features of Amazon ECR

Amazon ECR provides the following features:

(7)

How to get started with Amazon ECR

• Lifecycle policies help with managing the lifecycle of the images in your repositories. You deﬁne rules that result in the cleaning up of unused images. You can test rules before applying them to your repository. For more information, see Lifecycle policies (p. 52).

• Image scanning helps in identifying software vulnerabilities in your container images. Each repository can be conﬁgured to scan on push. This ensures that each new image pushed to the repository is scanned. You can then retrieve the results of the image scan. For more information, see Image scanning (p. 65).

• Cross-Region and cross-account replication makes it easier for you to have your images where you need them. This is conﬁgured as a registry setting and is on a per-Region basis. For more information, see Private registry settings (p. 16).

• Pull through cache rules provide a way to cache repositories in remote public registries in your private Amazon ECR registry. Using a pull through cache rule, Amazon ECR will periodically reach out to the remote registry to ensure the cached image in your Amazon ECR private registry is up to date. For more information, see Using pull through cache rules (p. 40).

How to get started with Amazon ECR

To use Amazon ECR, you must be set up to install the AWS Command Line Interface and Docker. For more information, see Setting up with Amazon ECR (p. 3) and Using Amazon ECR with the AWS CLI (p. 8).

Pricing for Amazon ECR

With Amazon ECR, you only pay for the amount of data you store in your repositories and for the data transfer from your image pushes and pulls. For more information, see Amazon ECR pricing.

(8)

Sign up for AWS

Setting up with Amazon ECR

If you've signed up for AWS and have been using Amazon Elastic Container Service (Amazon ECS) or Amazon Elastic Kubernetes Service (Amazon EKS), you are close to being able to use Amazon ECR. The setup process for those two services is similar, as Amazon ECR is an extension of both services. When using the AWS CLI with Amazon ECR, we recommend that you use a version of the AWS CLI that supports the latest Amazon ECR features. If you do not see support for an Amazon ECR feature in the AWS CLI, you should upgrade to the latest version. For more information, see http://aws.amazon.com/cli/.

Complete the following tasks to get set up to push a container image to Amazon ECR for the ﬁrst time. If you have already completed any of these steps, you may skip them and move on to the next step.

Sign up for AWS

When you sign up for AWS, your AWS account is automatically signed up for all services, including Amazon ECR. You are charged only for the services that you use.

If you have an AWS account already, skip to the next task. If you don't have an AWS account, use the following procedure to create one.

To create an AWS account

1. Open https://portal.aws.amazon.com/billing/signup.

2. Follow the online instructions.

Part of the sign-up procedure involves receiving a phone call and entering a veriﬁcation code on the phone keypad.

Note your AWS account number, because you'll need it for the next task.

Create an IAM user

Services in AWS, such as Amazon ECR, require that you provide credentials when you access them, so that the service can determine whether you have permission to access its resources. The console requires your password. You can create access keys for your AWS account to access the command line interface or API. However, we don't recommend that you access AWS using the credentials for your AWS account;

we recommend that you use AWS Identity and Access Management (IAM) instead. Create an IAM user, and then add the user to an IAM group with administrative permissions or grant this user administrative permissions. You can then access AWS using a special URL and the credentials for the IAM user.

If you signed up for AWS but have not created an IAM user for yourself, you can create one using the IAM console.

To create an administrator user for yourself and add the user to an administrators group (console)

1. Sign in to the IAM console as the account owner by choosing Root user and entering your AWS account email address. On the next page, enter your password.

(9)

Create an IAM user

NoteWe strongly recommend that you adhere to the best practice of using the Administrator IAM user that follows and securely lock away the root user credentials. Sign in as the root user only to perform a few account and service management tasks.

2. In the navigation pane, choose Users and then choose Add user.

3. For User name, enter Administrator.

4. Select the check box next to AWS Management Console access. Then select Custom password, and then enter your new password in the text box.

5. (Optional) By default, AWS requires the new user to create a new password when ﬁrst signing in. You can clear the check box next to User must create a new password at next sign-in to allow the new user to reset their password after they sign in.

6. Choose Next: Permissions.

7. Under Set permissions, choose Add user to group.

8. Choose Create group.

9. In the Create group dialog box, for Group name enter Administrators.

10. Choose Filter policies, and then select AWS managed - job function to ﬁlter the table contents.

11. In the policy list, select the check box for AdministratorAccess. Then choose Create group.

NoteYou must activate IAM user and role access to Billing before you can use the

AdministratorAccess permissions to access the AWS Billing and Cost Management console. To do this, follow the instructions in step 1 of the tutorial about delegating access to the billing console.

12. Back in the list of groups, select the check box for your new group. Choose Refresh if necessary to see the group in the list.

13. Choose Next: Tags.

14. (Optional) Add metadata to the user by attaching tags as key-value pairs. For more information about using tags in IAM, see Tagging IAM entities in the IAM User Guide.

15. Choose Next: Review to see the list of group memberships to be added to the new user. When you are ready to proceed, choose Create user.

You can use this same process to create more groups and users and to give your users access to your AWS account resources. To learn about using policies that restrict user permissions to speciﬁc AWS resources, see Access management and Example policies.

To sign in as this new IAM user, sign out of the AWS console, then use the following URL, where your_aws_account_id is your AWS account number without the hyphens (for example, if your AWS account number is 1234-5678-9012, your AWS account ID is 123456789012):

https://your_aws_account_id.signin.aws.amazon.com/console/

Enter the IAM user name and password that you just created. When you're signed in, the navigation bar displays "your_user_name @ your_aws_account_id".

If you don't want the URL for your sign-in page to contain your AWS account ID, you can create an account alias. From the IAM dashboard, choose Customize and enter an Account Alias, such as your company name. For more information, see Your AWS account ID and its alias in the IAM User Guide.

To sign in after you create an account alias, use the following URL:

https://your_account_alias.signin.aws.amazon.com/console/

(10)

Create an IAM user

To verify the sign-in link for IAM users for your account, open the IAM console and check under IAM users sign-in link on the dashboard.

For more information about IAM, see the AWS Identity and Access Management User Guide.

(11)

Getting started with Amazon ECR

using the AWS Management Console

Get started with Amazon ECR by creating a repository in the Amazon ECR console. The Amazon ECR console guides you through the process to get started creating your ﬁrst repository.

Before you begin, be sure that you've completed the steps in Setting up with Amazon ECR (p. 3).

To create an image repository

A repository is where you store your Docker or Open Container Initiative (OCI) images in Amazon ECR.

Each time you push or pull an image from Amazon ECR, you specify the repository and the registry location which informs where to push the image to or where to pull it from.

1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

2. Choose Get Started.

3. For Visibility settings, choose Private.

4. For Repository name, specify a name for the repository.

5. For Tag immutability, choose the tag mutability setting for the repository. Repositories conﬁgured with immutable tags will prevent image tags from being overwritten. For more information, see Image tag mutability (p. 64).

6. For Scan on push, choose the image scanning setting for the repository. Repositories conﬁgured to scan on push will start an image scan whenever an image is pushed, otherwise image scans need to be started manually.

Important

Conﬁguring image scanning at the repository level has been deprecated in favor of conﬁguring it at the registry level. For more information, see Image scanning (p. 65).

7. For KMS encryption, choose whether to enable server-side encryption using AWS KMS keys stored in the AWS Key Management Service service. For more information about this feature, see Encryption at rest (p. 102).

8. Choose Create repository.

Build, tag, and push a Docker image

In this section of the wizard, you use the Docker CLI to tag an existing local image (that you have built from a Dockerﬁle or pulled from another registry, such as Docker Hub) and then push the tagged image to your Amazon ECR registry. For more detailed steps on using the Docker CLI, see Using Amazon ECR with the AWS CLI (p. 8).

1. Select the repository you created and choose View push commands to view the steps to push an image to your new repository.

2. Run the login command that authenticates your Docker client to your registry by using the command from the console in a terminal window. This command provides an authorization token that is valid for 12 hours.

3. (Optional) If you have a Dockerﬁle for the image to push, build the image and tag it for your new repository. Using the docker build command from the console in a terminal window. Make sure that you are in the same directory as your Dockerﬁle.

4. Tag the image with your Amazon ECR registry URI and your new repository by pasting the docker tag command from the console into a terminal window. The console command assumes that your

(12)

image was built from a Dockerfile in the previous step. If you did not build your image from a Dockerfile, replace the first instance of repository:latest with the image ID or image name of your local image to push.

5. Push the newly tagged image to your repository by using the docker push command in a terminal window.

6. Choose Close.

(13)

Prerequisites

Using Amazon ECR with the AWS CLI

The following steps walk you through the steps needed to push a container image to a private Amazon ECR repository for the ﬁrst time using the Docker CLI and the AWS CLI.

For more information on the other tools available for managing your AWS resources, including the diﬀerent AWS SDKs, IDE toolkits, and the Windows PowerShell command line tools, see http://

aws.amazon.com/tools/.

Prerequisites

Before you begin, be sure that you have completed the steps in Setting up with Amazon ECR (p. 3).

If you do not already have the latest AWS CLI and Docker installed and ready to use, use the following steps to install both of these tools.

Install the AWS CLI

You can use the AWS command line tools to issue commands at your system's command line to perform Amazon ECR and other AWS tasks. This can be faster and more convenient than using the console. The command line tools are also useful for building scripts that perform AWS tasks.

To use the AWS CLI with Amazon ECR, install the latest AWS CLI version (Amazon ECR functionality is available in the AWS CLI starting with version 1.9.15). You can check your AWS CLI version with the aws --version command. For information about installing the AWS CLI or upgrading it to the latest version, see Installing the AWS Command Line Interface in the AWS Command Line Interface User Guide.

Install Docker

Docker is available on many diﬀerent operating systems, including most modern Linux distributions, like Ubuntu, and even macOS and Windows. For more information about how to install Docker on your particular operating system, go to the Docker installation guide.

You don't need a local development system to use Docker. If you are using Amazon EC2 already, you can launch an Amazon Linux 2 instance and install Docker to get started.

If you already have Docker installed, skip to Step 1: Create a Docker image (p. 9).

To install Docker on an Amazon EC2 instance

1. Launch an instance with the Amazon Linux 2 AMI. For more information, see Launching an Instance in the Amazon EC2 User Guide for Linux Instances.

2. Connect to your instance. For more information, see Connect to Your Linux Instance in the Amazon EC2 User Guide for Linux Instances.

3. Update the installed packages and package cache on your instance.

sudo yum update -y

4. Install the most recent Docker Community Edition package.

sudo amazon-linux-extras install docker

(14)

Step 1: Create a Docker image

5. Start the Docker service.

sudo service docker start

6. Add the ec2-user to the docker group so you can execute Docker commands without using sudo.

sudo usermod -a -G docker ec2-user

7. Log out and log back in again to pick up the new docker group permissions. You can accomplish this by closing your current SSH terminal window and reconnecting to your instance in a new one.

Your new SSH session will have the appropriate docker group permissions.

8. Verify that the ec2-user can run Docker commands without sudo.

docker info

NoteIn some cases, you may need to reboot your instance to provide permissions for the ec2- user to access the Docker daemon. Try rebooting your instance if you see the following error:

Cannot connect to the Docker daemon. Is the docker daemon running on this host?

Step 1: Create a Docker image

In this section, you create a Docker image of a simple web application, and test it on your local system or EC2 instance, and then push the image to a container registry (such as Amazon ECR or Docker Hub) so you can use it in an ECS task deﬁnition.

To create a Docker image of a simple web application

1. Create a file called Dockerfile. A Dockerfile is a manifest that describes the base image to use for your Docker image and what you want installed and running on it. For more information about Dockerfiles, go to the Dockerfile Reference.

touch Dockerfile

2. Edit the Dockerfile you just created and add the following content.

FROM ubuntu:18.04

# Install dependencies RUN apt-get update && \ apt-get -y install apache2

# Install apache and write hello world message RUN echo 'Hello World!' > /var/www/html/index.html

# Configure apache

RUN echo '. /etc/apache2/envvars' > /root/run_apache.sh && \ echo 'mkdir -p /var/run/apache2' >> /root/run_apache.sh && \ echo 'mkdir -p /var/lock/apache2' >> /root/run_apache.sh && \ echo '/usr/sbin/apache2 -D FOREGROUND' >> /root/run_apache.sh && \ chmod 755 /root/run_apache.sh

EXPOSE 80

(15)

Step 2: Authenticate to your default registry

CMD /root/run_apache.sh

This Dockerﬁle uses the Ubuntu 18.04 image. The RUN instructions update the package caches, install some software packages for the web server, and then write the "Hello World!" content to the web server's document root. The EXPOSE instruction exposes port 80 on the container, and the CMD instruction starts the web server.

3. Build the Docker image from your Dockerﬁle.

Note

Some versions of Docker may require the full path to your Dockerﬁle in the following command, instead of the relative path shown below.

docker build -t hello-world .

4. Run docker images to verify that the image was created correctly.

docker images --filter reference=hello-world

Output:

REPOSITORY TAG IMAGE ID CREATED SIZE hello-world latest e9ffedc8c286 4 minutes ago 241MB 5. Run the newly built image. The -p 80:80 option maps the exposed port 80 on the container to

port 80 on the host system. For more information about docker run, go to the Docker run reference.

docker run -t -i -p 80:80 hello-world

NoteOutput from the Apache web server is displayed in the terminal window. You can ignore the "Could not reliably determine the server's fully qualified domain name" message.

6. Open a browser and point to the server that is running Docker and hosting your container.

• If you are using an EC2 instance, this is the Public DNS value for the server, which is the same address you use to connect to the instance with SSH. Make sure that the security group for your instance allows inbound traﬃc on port 80.

• If you are running Docker locally, point your browser to http://localhost/.

• If you are using docker-machine on a Windows or macOS computer, ﬁnd the IP address of the VirtualBox VM that is hosting Docker with the docker-machine ip command, substituting machine-name with the name of the docker machine you are using.

docker-machine ip machine-name

You should see a web page with your "Hello World!" statement.

7. Stop the Docker container by typing Ctrl + c.

Step 2: Authenticate to your default registry

After you have installed and conﬁgured the AWS CLI, authenticate the Docker CLI to your default registry. That way, the docker command can push and pull images with Amazon ECR. The AWS CLI provides a get-login-password command to simplify the authentication process.

(16)

Step 3: Create a repository

The get-login-password is the preferred method for authenticating to an Amazon ECR private registry when using the AWS CLI. Ensure that you have conﬁgured your AWS CLI to interact with AWS.

For more information, see AWS CLI conﬁguration basics in the AWS Command Line Interface User Guide.

When passing the Amazon ECR authorization 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 in the AWS Command Line Interface User Guide.

• get-login-password (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 (AWS Tools for Windows PowerShell)

(Get-ECRLoginCommand).Password | docker login --username AWS --password- stdin aws_account_id.dkr.ecr.region.amazonaws.com

Step 3: Create a repository

Now that you have an image to push to Amazon ECR, you must create a repository to hold it. In this example, you create a repository called hello-world to which you later push the hello- world:latest image. To create a repository, run the following command:

aws ecr create-repository \

--repository-name hello-world \

--image-scanning-configuration scanOnPush=true \ --region region

Step 4: Push an image to Amazon ECR

Now you can push your image to the Amazon ECR repository you created in the previous section. You use the docker CLI to push images, but there are a few prerequisites that must be satisﬁed for this to work properly:

• The minimum version of docker is installed: 1.7

• The Amazon ECR authorization token has been conﬁgured with docker login.

• The Amazon ECR repository exists and the user has access to push to the repository.

After those prerequisites are met, you can push your image to your newly created repository in the default registry for your account.

To tag and push an image to Amazon ECR

1. List the images you have stored locally to identify the image to tag and push.

docker images

(17)

Step 5: Pull an image from Amazon ECR

Output:

REPOSITORY TAG IMAGE ID CREATED VIRTUAL SIZE

hello-world latest e9ffedc8c286 4 minutes ago 241MB 2. Tag the image to push to your repository.

docker tag hello-world:latest aws_account_id.dkr.ecr.region.amazonaws.com/hello- world:latest

3. Push the image.

docker push aws_account_id.dkr.ecr.region.amazonaws.com/hello-world:latest

Output:

The push refers to a repository [aws_account_id.dkr.ecr.region.amazonaws.com/hello- world] (len: 1)

e9ae3c220b23: Pushed a6785352b25c: Pushed 0998bf8fb9e9: Pushed 0a85502c06c9: Pushed

latest: digest: sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b size: 6774

Step 5: Pull an image from Amazon ECR

After your image has been pushed to your Amazon ECR repository, you can pull it from other locations.

Use the docker CLI to pull images, but there are a few prerequisites that must be satisﬁed for this to work properly:

• The minimum version of docker is installed: 1.7

• The Amazon ECR authorization token has been conﬁgured with docker login.

• The Amazon ECR repository exists and the user has access to pull from the repository.

After those prerequisites are met, you can pull your image. To pull your example image from Amazon ECR, run the following command:

docker pull aws_account_id.dkr.ecr.region.amazonaws.com/hello-world:latest

Output:

latest: Pulling from hello-world 0a85502c06c9: Pull complete 0998bf8fb9e9: Pull complete a6785352b25c: Pull complete e9ae3c220b23: Pull complete

Digest: sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b Status: Downloaded newer image for aws_account_id.dkr.region.amazonaws.com/hello- world:latest

(18)

Step 6: Delete an image

If you decide that you no longer need or want an image in one of your repositories, you can delete it with the batch-delete-image command. To delete an image, you must specify the repository that it is in and either a imageTag or imageDigest value for the image. The example below deletes an image in the hello-world repository with the image tag latest.

aws ecr batch-delete-image \

--repository-name hello-world \ --image-ids imageTag=latest \ --region region

Output:

{

"failures": [], "imageIds": [ {

"imageTag": "latest", "imageDigest":

"sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b"

} ] }

Step 7: Delete a repository

If you decide that you no longer need or want an entire repository of images, you can delete the repository. By default, you cannot delete a repository that contains images; however, the --force ﬂag allows this. To delete a repository that contains images (and all the images within it), run the following command.

aws ecr delete-repository \

--repository-name hello-world \ --force \

--region region

(19)

Registry concepts

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 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, IAM 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 (p. 96).

• 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 (p. 14).

• Private repositories can be controlled with both IAM user access policies and repository policies. For more information about repository policies, see Private repository policies (p. 25).

• The repositories in your private registry can be replicated across Regions in your own private registry and across separate accounts by conﬁguring replication for your private registry. For more information, see Private image replication (p. 47).

Private registry authentication

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-speciﬁc 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 conﬁguration steps, see Amazon ECR Docker Credential Helper.

NoteThe Amazon ECR Docker credential helper doesn't support multi-factor authentication (MFA) currently.

(20)

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 API operation to retrieve a base64-encoded authorization token containing the username AWS and an encoded password. The AWS CLI get-login-password command simpliﬁes 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-password

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 in the AWS Command Line Interface User Guide.

• get-login-password (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 (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. 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')

2. 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 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:

(21)

Registry settings

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

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—You can use your registry permissions policy to grant permissions to an AWS principal to the replication and pull through cache features. For more information, see Private registry permissions (p. 16).

• Pull through cache rules—You can create pull through cache rules to cache images from an external public registry in your Amazon ECR private registry. For more information, see Using pull through cache rules (p. 40).

• Replication—You can conﬁgure repositories for either cross-Region or cross-account replication. For more information, see Private image replication (p. 47)

• Scanning conﬁguration—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 programing language package vulnerabilities. For more information, see Image scanning (p. 65).

Private registry permissions

Amazon ECR uses a registry policy to grant permissions to an AWS principal at the private registry level.

These permissions are used to scope access to the replication and pull through cache features.

Amazon ECR only enforces the following permissions at the private registry level. If any additional actions are added to the registry policy, an error will occur.

• 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.

NoteWhile it is possible to add the ecr:* action to a private registry permissions policy, it is considered best practice to only add the speciﬁc actions required based on the feature you're using rather than use a wildcard.

Topics

• Setting a private registry permission statement (p. 17)

(22)

Setting a registry permission statement

• Deleting a private registry permission statement (p. 19)

• Private registry policy examples (p. 19)

Setting a private registry permission statement

You can add or update the permissions policy for your registry by using the following steps. You can add multiple policy statements per registry. For example policies, see Private registry policy examples (p. 19).

Topics

• Private registry permissions for replication (p. 17)

• Private registry permissions for pull through cache (p. 18)

Private registry permissions for replication

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 conﬁgure cross-Region replication within your own registry. You only need to conﬁgure 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 conﬁgure a permissions policy for replication (AWS Management Console)

To conﬁgure a replication permissions policy for a private registry (AWS Management Console)

1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

2. From the navigation bar, choose the Region to conﬁgure your registry policy in.

3. In the navigation pane, choose Private registry, Registry permissions.

4. On the Registry permissions page, choose Generate statement.

5. Complete the following steps to deﬁne your policy statement using the policy generator.

a. For Policy type, choose Cross account policy.

b. For Statement ID, enter a unique statement ID. This ﬁeld is used as the Sid on the registry policy.

c. 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.

6. Expand the Preview policy statement section to review the registry permissions policy statement.

7. After the policy statement is conﬁrmed, choose Add to policy to save the policy to your registry.

To conﬁgure a permissions policy for replication (AWS CLI)

To conﬁgure a permissions policy for a private registry (AWS CLI)

1. Create a ﬁle named registry_policy.json and populate it with a registry policy.

(23)

Setting a registry permission statement

{ "Version":"2012-10-17", "Statement":[

{

"Sid":"ReplicationAccessCrossAccount", "Effect":"Allow",

"Principal":{

"AWS":"arn:aws:iam::source_account_id:root"

},

"Action":[

"ecr:CreateRepository", "ecr:ReplicateImage"

],

"Resource": [

"arn:aws:ecr:us-west-2:your_account_id:repository/*"

] } ] }

2. Create the registry policy using the policy ﬁle.

aws ecr put-registry-policy \

--policy-text file://registry_policy.json \ --region us-west-2

3. Retrieve the policy for your registry to conﬁrm.

aws ecr get-registry-policy \ --region us-west-2

Private registry permissions for pull through cache

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/.

2. From the navigation bar, choose the Region to conﬁgure your private registry permissions statement in.

3. In the navigation pane, choose Private registry, Registry permissions.

4. On the Registry permissions page, choose Generate statement.

5. For each pull through cache permissions policy statement you want to create, do the following.

a. For Policy type, choose Pull through cache policy.

b. For Statement id, provide a name for the pull through cache statement policy.

c. For IAM entities, specify the IAM users, groups, or roles to include in the policy.

d. For Repository namespace, select the pull through cache rule to associate the policy with.

e. 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.

(24)

Deleting a registry permission statement

Deleting a private registry permission statement

You can delete all permissions policy statements for your registry by using the following steps.

To delete a permissions policy for a private registry (AWS Management Console) 1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

2. From the navigation bar, choose the Region to conﬁgure your registry permissions policy in.

3. In the navigation pane, choose Registries.

4. On the Registries page, select your Private registry and choose Permissions.

5. On the Private registry permissions page, choose Delete.

6. On the Delete registry policy conﬁrmation screen, choose Delete policy.

To delete a permissions policy for a private registry (AWS CLI) 1. Delete the registry policy.

aws ecr delete-registry-policy \ --region us-west-2

2. Retrieve the policy for your registry to conﬁrm.

aws ecr get-registry-policy \ --region us-west-2

Private registry policy examples

The following examples show registry permissions policy statements that you could use to control the permissions that users have to your Amazon ECR registry.

NoteIn each example, if the ecr:CreateRepository action is removed from your registry

permission statement, replication can still occur. However, for successful replication, you need to create repositories with the same name within your account.

Example: Allow the root user of a source account to replicate all repositories

{

"Version":"2012-10-17", "Statement":[

{

"Principal":{

},

"Action":[

],

"Resource": [

]

(25)

Registry policy examples

} ] }

Example: Allow multiple accounts

{

"Principal":{

},

"Action":[

],

"Resource": [

] }, {

"Principal":{

},

"Action":[

],

"Resource": [

] } ] }

Example: Allow the root user of a source account to replicate all repositories with preﬁx prod-.

{

"Principal":{

},

"Action":[

],

"Resource": [

"arn:aws:ecr:us-west-2:your_account_id:repository/prod-*"

] } ]

(26)

Registry policy examples

}

(27)

Repository concepts

Amazon ECR private repositories

Amazon Elastic Container Registry (Amazon ECR) provides API operations to create, monitor, and delete image repositories and set permissions that control who can access them. You can perform the same actions in the Repositories section of the Amazon ECR console. Amazon ECR also integrates with the Docker CLI, so that you push and pull images from your development environments to your repositories.

Topics

• Private repository concepts (p. 22)

• Creating a private repository (p. 22)

• Viewing private repository details (p. 23)

• Editing a private repository (p. 24)

• Deleting a private repository (p. 25)

• Private repository policies (p. 25)

• Tagging a private repository (p. 30)

Private repository concepts

• By default, your account has read and write access to the repositories in your default registry

(aws_account_id.dkr.ecr.region.amazonaws.com). However, IAM users require permissions to make calls to the Amazon ECR APIs and to push or pull images to and from your 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 (p. 96).

• Repositories can be controlled with both IAM user access policies and individual repository policies. For more information, see Private repository policies (p. 25).

• Repository names can support namespaces, which you can use to group similar repositories. For example, if there are several teams using the same registry, Team A can use the team-a namespace, and Team B can use the team-b namespace. By doing this, each team has their own image called web- app with each image prefaced with the team namespace. This conﬁguration allows these images on each team to be used simultaneously without interference. Team A's image is team-a/web-app, and Team B's image is team-b/web-app.

• Your images can be replicated to other repositories across Regions in your own registry and across accounts. You can do this by specifying a replication conﬁguration in your registry settings. For more information, see Private registry settings (p. 16).

Creating a private repository

Your container images are stored in Amazon ECR repositories. Use the following steps to create a private repository using the AWS Management Console. For steps to create a repository using the AWS CLI, see Step 3: Create a repository (p. 11).

To create a repository (AWS Management Console)

1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/repositories.

2. From the navigation bar, choose the Region to create your repository in.

(28)

Viewing repository details

3. In the navigation pane, choose Repositories.

4. On the Repositories page, choose the Private tab, and then choose Create repository.

5. For Visibility settings, verify that Private is selected.

6. For Repository name, enter a unique name for your repository. The repository name can be speciﬁed on its own (for example nginx-web-app). Alternatively, it can be prepended with a namespace to group the repository into a category (for example project-a/nginx-web-app).

NoteThe name must start with a letter and can only contain lowercase letters, numbers, hyphens (-), underscores (_), and forward slashes (/).

7. For Tag immutability, choose the tag mutability setting for the repository. Repositories conﬁgured with immutable tags prevent image tags from being overwritten. For more information, see Image tag mutability (p. 64).

8. For Scan on push, while you can specify the scan settings at the repository level for basic scanning, it is best practice to specify the scan configuration at the private registry level. Specify the scanning settings at the private registry allow you to enable either enhanced scanning or basic scanning as well as define filters to specify which repositories are scanned. For more information, see Image scanning (p. 65).

9. For KMS encryption, choose whether to enable encryption of the images in the repository using AWS Key Management Service. By default, when KMS encryption is enabled, Amazon ECR uses an AWS managed key (KMS key) with the alias aws/ecr. This key is created in your account the ﬁrst time that you create a repository with KMS encryption enabled. For more information, see Encryption at rest (p. 102).

10. When KMS encryption is enabled, select Customer encryption settings (advanced) to choose your own KMS key. The KMS key must be in the same Region as the cluster. Choose Create an AWS KMS key to navigate to the AWS KMS console to create your own key.

11. Choose Create repository.

12. (Optional) Select the repository that you created and choose View push commands to view the steps to push an image to your new repository.

a. Run the login command that authenticates your Docker client to your registry by using the command from the console in a terminal window. This command provides an authorization token that is valid for 12 hours.

b. (Optional) If you have a Dockerﬁle for the image to push, build the image and tag it for your new repository. Using the docker build command from the console in a terminal window. Make sure that you are in the same directory as your Dockerﬁle.

c. Tag the image with your Amazon ECR registry URI and your new repository by pasting the docker tag command from the console into a terminal window. The console command assumes that your image was built from a Dockerfile in the previous step. If you did not build your image from a Dockerfile, replace the first instance of repository:latest with the image ID or image name of your local image to push.

d. Push the newly tagged image to your repository by using the docker push command in a terminal window.

e. Choose Close.

Viewing private repository details

After you created a repository, you can view details about the repository in the AWS Management Console:

• Which images are stored in a repository

• Details about each image stored in the repository, including the size and SHA digest for each image

(29)

Editing a repository

• The scan frequency speciﬁed for the contents of the repository

• Whether the repository has an active pull through cache rule associated with it

• The encryption setting for the repository

NoteStarting with Docker version 1.9, the Docker client compresses image layers before pushing them to a V2 Docker registry. The output of the docker images command shows the

uncompressed image size. Therefore, keep in mind that Docker might return a larger image than the image shown in the AWS Management Console.

To view repository information (AWS Management Console)

2. From the navigation bar, choose the Region that contains the repository to view.

4. On the Repositories page, choose the Private tab and then the repository to view.

5. On the repository detail page, the console defaults to the Images view. Use the navigation menu to view other information about the repository.

• Choose Summary to view the repository details and pull count data for the repository.

• Choose Images to view information about the image tags in the repository. To view more information about the image, select the image tag. For more information, see Viewing image details (p. 39).

If there are untagged images that you want to delete, you can select the box to the left of the repositories to delete and choose Delete. For more information, see Deleting an image (p. 45).

• Choose Permissions to view the repository policies that are applied to the repository. For more information, see Private repository policies (p. 25).

• Choose Lifecycle Policy to view the lifecycle policy rules that are applied to the repository.

The lifecycle events history is also viewed here. For more information, see Lifecycle policies (p. 52).

• Choose Tags to view the metadata tags that are applied to the repository.

Editing a private repository

Existing repositories can be edited to change its image tag mutability and image scanning settings.

To edit a repository (AWS Management Console)

2. From the navigation bar, choose the Region that contains the repository to edit.

4. On the Repositories page, choose the Private tab and then select the repository to edit and choose Edit.

5. For Tag immutability, choose the tag mutability setting for the repository. Repositories conﬁgured with immutable tags prevent image tags from being overwritten. For more information, see Image tag mutability (p. 64).

6. For Image scan settings, while you can specify the scan settings at the repository level for basic scanning, it is best practice to specify the scan conﬁguration at the private registry level. Specify the scanning settings at the private registry allow you to enable either enhanced scanning or basic

(30)

Deleting a repository

scanning as well as deﬁne ﬁlters to specify which repositories are scanned. For more information, see Image scanning (p. 65).

7. For Encryption settings, this is a view only ﬁeld as the encryption settings for a repository can't be changed once the repository is created.

8. Choose Save to update the repository settings.

Deleting a private repository

If you're ﬁnished using a repository, you can delete it. When you delete a repository in the AWS Management Console, all of the images contained in the repository are also deleted; this cannot be undone.

To delete a repository (AWS Management Console)

2. From the navigation bar, choose the Region that contains the repository to delete.

4. On the Repositories page, choose the Private tab and then select the repository to delete and choose Delete.

5. In the Delete repository_name window, verify that the selected repositories should be deleted and choose Delete.

Important

Any images in the selected repositories are also deleted.

Private repository policies

Amazon ECR uses resource-based permissions to control access to repositories. Resource-based permissions let you specify which IAM users or roles have access to a repository and what actions they can perform on it. By default, only the AWS account that created the repository has access to a repository. You can apply a policy document that allow additional permissions to your repository.

Topics

• Repository policies vs IAM policies (p. 25)

• Setting a private repository policy statement (p. 26)

• Deleting a private repository policy statement (p. 27)

• Private repository policy examples (p. 28)

Repository policies vs IAM policies

Amazon ECR repository policies are a subset of IAM policies that are scoped for, and speciﬁcally used for, controlling access to individual Amazon ECR repositories. IAM policies are generally used to apply permissions for the entire Amazon ECR service but can also be used to control access to speciﬁc resources as well.

Both Amazon ECR repository policies and IAM policies are used when determining which actions a speciﬁc IAM user or role may perform on a repository. If a user or role is allowed to perform an action through a repository policy but is denied permission through an IAM policy (or vice versa) then the action will be denied. A user or role only needs to be allowed permission for an action through either a repository policy or an IAM policy but not both for the action to be allowed.

(31)

Setting a repository policy statement

Important

Amazon ECR requires that users have permission to make calls to the

ecr:GetAuthorizationToken API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository. Amazon ECR provides several managed IAM policies to control user access at varying levels; for more information, see Amazon Elastic Container Registry Identity-Based Policy Examples (p. 96).

You can use either of these policy types to control access to your repositories, as shown in the following examples.

This example shows an Amazon ECR repository policy, which allows for a speciﬁc IAM user to describe the repository and the images within the repository.

{ "Version": "2012-10-17", "Statement": [{

"Sid": "ECR Repository Policy", "Effect": "Allow",

"Principal": {

"AWS": "arn:aws:iam::account-id:user/username"

},

"Action": [

"ecr:DescribeImages", "ecr:DescribeRepositories"

] }]}

This example shows an IAM policy that achieves the same goal as above, by scoping the policy to a repository (speciﬁed by the full ARN of the repository) using the resource parameter. For more information about Amazon Resource Name (ARN) format, see Resources (p. 86).

{

"Version": "2012-10-17", "Statement": [{

"Sid": "ECR Repository Policy", "Effect": "Allow",

"Principal": {

"AWS": "arn:aws:iam::account-id:user/username"

},

"Action": [

"ecr:DescribeImages", "ecr:DescribeRepositories"

],

"Resource": [

"arn:aws:ecr:region:account-id:repository/repository-name"

] }]

}

Setting a private repository policy statement

You can add an access policy statement to a repository in the AWS Management Console by following the steps below. You can add multiple policy statements per repository. For example policies, see Private repository policy examples (p. 28).

Important

ecr:GetAuthorizationToken API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository. Amazon ECR provides

(32)

Deleting a repository policy statement

several managed IAM policies to control user access at varying levels; for more information, see Amazon Elastic Container Registry Identity-Based Policy Examples (p. 96).

To set a repository policy statement

2. From the navigation bar, choose the Region that contains the repository to set a policy statement on.

4. On the Repositories page, choose the repository to set a policy statement on to view the contents of the repository.

5. From the repository image list view, in the navigation pane, choose Permissions, Edit.

NoteIf you don't see the Permissions option in the navigation pane, ensure that you are in the repository image list view.

6. On the Edit permissions page, choose Add statement.

7. For Statement name, enter a name for the statement.

8. For Eﬀect, choose whether the policy statement will result in an allow or an explicit deny.

9. For Principal, choose the scope to apply the policy statement to. For more information, see AWS JSON Policy Elements: Principal in the IAM User Guide.

• You can apply the statement to all authenticated AWS users by selecting the Everyone (*) check box.

• For Service principal, specify the service principal name (for example, ecs.amazonaws.com) to apply the statement to a speciﬁc service.

• For AWS Account IDs, specify an AWS account number (for example, 111122223333) to apply the statement to all users under a speciﬁc AWS account. Multiple accounts can be speciﬁed by using a comma delimited list.

Important

The account you are granting permissions to must have the Region you are creating the repository policy in enabled, otherwise an error will occur.

• For IAM Entities, select the roles or users under your AWS account to apply the statement to.

NoteFor more complicated repository policies that are not currently supported in the AWS Management Console, you can apply the policy with the set-repository-policy AWS CLI command.

10. For Actions, choose the scope of the Amazon ECR API operations that the policy statement should apply to from the list of individual API operations.

11. When you are ﬁnished, choose Save to set the policy.

12. Repeat the previous step for each repository policy to add.

Deleting a private repository policy statement

If you no longer want an existing repository policy statement to apply to a repository, you can delete it.

To delete a repository policy statement

2. From the navigation bar, choose the Region that contains the repository to delete a policy statement from.

(33)

Repository policy examples

4. On the Repositories page, choose the repository to delete a policy statement from.

5. In the navigation pane, choose Permissions, Edit.

6. On the Edit permissions page, choose Delete.

Private repository policy examples

The following examples show policy statements that you could use to control the permissions that authenticated users have to Amazon ECR repositories.

Important

ecr:GetAuthorizationToken API through an IAM policy before they can authenticate to a registry and push or pull any images from any Amazon ECR repository. Amazon ECR provides several managed IAM policies to control user access at varying levels; for more information, see Amazon Elastic Container Registry Identity-Based Policy Examples (p. 96).

Example: Allow one or more IAM users

The following repository policy allows one or more IAM users to push and pull images to and from a repository.

{ "Version": "2012-10-17", "Statement": [

{

"Sid": "AllowPushPull", "Effect": "Allow", "Principal": { "AWS": [

"arn:aws:iam::account-id:user/push-pull-user-1", "arn:aws:iam::account-id:user/push-pull-user-2"

] },

"Action": [

"ecr:BatchGetImage",

"ecr:BatchCheckLayerAvailability", "ecr:CompleteLayerUpload",

"ecr:GetDownloadUrlForLayer", "ecr:InitiateLayerUpload", "ecr:PutImage",

"ecr:UploadLayerPart"

] } ] }

Example: Allow another account

The following repository policy allows a speciﬁc account to push images.

Important

The account you are granting permissions to must have the Region you are creating the repository policy in enabled, otherwise an error will occur.

{

(34)

Repository policy examples

"Sid": "AllowCrossAccountPush", "Effect": "Allow",

"Principal": {

"AWS": "arn:aws:iam::account-id:root"

},

"Action": [

"ecr:BatchCheckLayerAvailability", "ecr:CompleteLayerUpload",

"ecr:InitiateLayerUpload", "ecr:PutImage",

"ecr:UploadLayerPart"

] } ] }

The following repository policy allows some IAM users to pull images (pull-user-1 and pull-user-2) while providing full access to another (admin-user).

NoteFor more complicated repository policies that are not currently supported in the AWS Management Console, you can apply the policy with the set-repository-policy AWS CLI command.

{

"Sid": "AllowPull", "Effect": "Allow", "Principal": { "AWS": [

"arn:aws:iam::account-id:user/pull-user-1", "arn:aws:iam::account-id:user/pull-user-2"

] },

"Action": [

"ecr:BatchGetImage",

"ecr:GetDownloadUrlForLayer"

] }, {

"Sid": "AllowAll", "Effect": "Allow", "Principal": {

"AWS": "arn:aws:iam::account-id:user/admin-user"

},

"Action": [ "ecr:*"

] } ] }

Example: Deny all

The following repository policy denies all users in all accounts the ability to pull images.

{

Amazon ECR

Amazon ECR

User Guide

API Version 2015-09-21

Amazon ECR: User Guide

Table of Contents

What is Amazon Elastic Container Registry?

Components of Amazon ECR

Features of Amazon ECR

How to get started with Amazon ECR

Pricing for Amazon ECR

Setting up with Amazon ECR

Sign up for AWS

Create an IAM user

Getting started with Amazon ECR

using the AWS Management Console

Using Amazon ECR with the AWS CLI

Prerequisites

Install the AWS CLI

Install Docker

Step 1: Create a Docker image

Step 2: Authenticate to your default registry

Step 3: Create a repository

Step 4: Push an image to Amazon ECR

Step 5: Pull an image from Amazon ECR

Step 6: Delete an image

Step 7: Delete a repository

Amazon ECR private registry

Private registry concepts

Private registry authentication

Using the Amazon ECR credential helper

Using an authorization token

To authenticate Docker to an Amazon ECR private registry with get-login-password

Using HTTP API authentication

Private registry settings

Private registry permissions

Setting a private registry permission statement

Private registry permissions for replication

Private registry permissions for pull through cache

Deleting a private registry permission statement

Private registry policy examples

Example: Allow the root user of a source account to replicate all repositories

Example: Allow multiple accounts

Example: Allow the root user of a source account to replicate all repositories with preﬁx prod-.

Amazon ECR private repositories

Private repository concepts

Creating a private repository

Viewing private repository details

Editing a private repository

Deleting a private repository

Private repository policies

Repository policies vs IAM policies

Setting a private repository policy statement

Deleting a private repository policy statement

Private repository policy examples

Example: Allow one or more IAM users

Example: Allow another account

Example: Deny all