Amazon ECR User Guide - AWS Documentation

Amazon ECR User Guide - AWS Documentation
Amazon ECR
User Guide
API Version 2015-09-21
Amazon ECR User Guide
Amazon ECR: User Guide
Copyright © 2016 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
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 affiliated with, connected to, or sponsored by
Amazon.
Amazon ECR User Guide
Table of Contents
What Is Amazon EC2 Container Registry? ......................................................................................... 1
Components of Amazon ECR .................................................................................................. 1
How to Get Started with Amazon ECR ...................................................................................... 1
Setting Up .................................................................................................................................... 3
Sign Up for AWS ................................................................................................................... 3
Create an IAM User ............................................................................................................... 4
Install the AWS CLI ................................................................................................................ 5
Install Docker ........................................................................................................................ 5
Docker Basics ............................................................................................................................... 6
Installing Docker .................................................................................................................... 6
Create a Docker Image ........................................................................................................... 7
Next Steps ......................................................................................................................... 10
Getting Started ............................................................................................................................ 11
Registries ................................................................................................................................... 13
Registry Concepts ............................................................................................................... 13
Registry Authentication ......................................................................................................... 13
Repositories ............................................................................................................................... 15
Repository Concepts ............................................................................................................ 15
Creating a Repository ........................................................................................................... 15
Deleting a Repository ........................................................................................................... 16
Repository Policies .............................................................................................................. 17
Setting a Repository Policy Statement ............................................................................. 17
Deleting a Repository Policy Statement ........................................................................... 19
Repository Policy Examples .......................................................................................... 19
Images ...................................................................................................................................... 23
Pushing an Image ................................................................................................................ 23
Pulling an Image .................................................................................................................. 24
Using Amazon ECR Images with Amazon ECS ......................................................................... 25
Deleting an Image ............................................................................................................... 26
IAM Policies and Roles ................................................................................................................. 28
Policy Structure ................................................................................................................... 29
Policy Syntax .............................................................................................................. 29
Actions for Amazon ECR ............................................................................................... 30
Amazon Resource Names for Amazon ECR ..................................................................... 30
Condition Keys for Amazon ECR .................................................................................... 31
Testing Permissions ..................................................................................................... 31
Amazon ECR Managed Policies ............................................................................................. 32
AmazonEC2ContainerRegistryFullAccess ........................................................................ 32
AmazonEC2ContainerRegistryPowerUser ........................................................................ 33
AmazonEC2ContainerRegistryReadOnly ......................................................................... 33
Supported Resource-Level Permissions .................................................................................. 34
Creating IAM Policies ........................................................................................................... 35
Using the AWS CLI ...................................................................................................................... 36
Step 1: Authenticate Docker to your Default Registry .................................................................. 36
Step 3: Get a Docker Image ................................................................................................... 37
Step 4: Create a Repository ................................................................................................... 37
Step 5: Push an Image to Amazon ECR ................................................................................... 38
Step 6: Pull an Image from Amazon ECR ................................................................................. 39
Step 8: Delete an Image ....................................................................................................... 39
Step 9: Delete a Repository ................................................................................................... 39
Service Limits ............................................................................................................................. 41
CloudTrail Logging ....................................................................................................................... 42
Amazon ECR Information in CloudTrail .................................................................................... 42
Understanding Amazon ECR Log File Entries ........................................................................... 43
Document History ........................................................................................................................ 44
API Version 2015-09-21
iii
Amazon ECR User Guide
AWS Glossary ............................................................................................................................. 45
API Version 2015-09-21
iv
Amazon ECR User Guide
Components of Amazon ECR
What Is Amazon EC2 Container
Registry?
Amazon EC2 Container Registry (Amazon ECR) is a managed AWS Docker registry service that is secure,
scalable, and reliable . Amazon ECR supports private Docker repositories with resource-based permissions
using AWS IAM so that specific users or Amazon EC2 instances can access repositories and images.
Developers can use the Docker CLI to push, pull, and manage images.
Components of Amazon ECR
Amazon ECR contains the following components:
Registry
An Amazon ECR registry is provided to each AWS account; you can create image repositories in
your registry and store images in them. For more information, see Amazon ECR Registries (p. 13).
Authorization token
Your Docker client needs to authenticate to Amazon ECR registries as an AWS user before it can
push and pull images. The AWS CLI get-login command provides you with authentication credentials
to pass to Docker. For more information, see Registry Authentication (p. 13).
Repository
An Amazon ECR image repository contains your Docker images. For more information, see Amazon
ECR Repositories (p. 15).
Repository policy
You can control access to your repositories and the images within them with repository policies. For
more information, see Amazon ECR Repository Policies (p. 17).
Image
You can push and pull Docker images to your repositories. You can use these images locally on your
development system, or you can use them in Amazon ECS task definitions. For more information,
see Using Amazon ECR Images with Amazon ECS (p. 25).
How to Get Started with Amazon ECR
To use Amazon ECR, you need to be set up to install the AWS Command Line Interface and Docker.
For more information, see Setting Up with Amazon ECR (p. 3) and Docker Basics (p. 6).
API Version 2015-09-21
1
Amazon ECR User Guide
How to Get Started with Amazon ECR
After you are set up, you are ready to complete the Getting Started with Amazon ECR (p. 11) tutorial.
API Version 2015-09-21
2
Amazon ECR User Guide
Sign Up for AWS
Setting Up with Amazon ECR
If you've already signed up for Amazon Web Services (AWS) and have been using Amazon EC2 Container
Service (Amazon ECS), you are close to being able to use Amazon ECR. The set up process for the two
services is very similar, as Amazon ECR is an extension to Amazon ECS. To use the AWS CLI with
Amazon ECR , you must 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 for Amazon ECR. If you have already completed any of these
steps, you may skip them and move on to installing the custom AWS CLI.
1. Sign Up for AWS (p. 3)
2. Create an IAM User (p. 4)
3. Install the AWS CLI (p. 5)
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.
2.
Open http://aws.amazon.com/, and then choose Create an AWS Account.
Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a PIN using the phone
keypad.
Note your AWS account number, because you'll need it for the next task.
API Version 2015-09-21
3
Amazon ECR User Guide
Create an IAM User
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 and 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 a group for administrators
1.
Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
2.
3.
In the navigation pane, choose Groups, and then choose Create New Group.
For Group Name, type a name for your group, such as Administrators, and then choose Next
Step.
In the list of policies, select the check box next to the AdministratorAccess policy. You can use the
Filter menu and the Search box to filter the list of policies.
Choose Next Step, and then choose Create Group.
4.
5.
Your new group is listed under Group Name.
To create an IAM user for yourself, add the user to the administrators group, and create
a password for the user
1.
2.
3.
4.
5.
6.
In the navigation pane, choose Users, and then choose Create New Users.
In box 1, type a user name.
Clear the check box next to Generate an access key for each user.
Choose Create.
In the list of users, choose the name (not the check box) of the user you just created. You can use
the Search box to search for the user name.
Choose the Groups tab and then choose Add User to Groups.
7.
8.
Select the check box next to the administrators group. Then choose Add to Groups.
Choose the Security Credentials tab. Under Sign-In Credentials, choose Manage Password.
9.
Select Assign a custom password. Then type a password in the Password and Confirm Password
boxes. When you are finished, choose Apply.
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".
API Version 2015-09-21
4
Amazon ECR User Guide
Install the AWS CLI
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 Create Account Alias and enter an alias, such as your company
name. To sign in after you create an account alias, use the following URL:
https://your_account_alias.signin.aws.amazon.com/console/
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.
Install the AWS CLI
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
To use the Docker CLI with Amazon ECR, you must first install Docker on your system. For information
about installing Docker and getting familiar with the tools, see Docker Basics (p. 6).
API Version 2015-09-21
5
Amazon ECR User Guide
Installing Docker
Docker Basics
Docker is a technology that allows you to build, run, test, and deploy distributed applications that are
based on Linux containers. For more information, see Docker Containers on AWS. Amazon ECR is a
managed AWS Docker registry service. Customers can use the familiar Docker CLI to push, pull, and
manage images. For Amazon ECR product details, featured customer case studies, and FAQs, see the
Amazon EC2 Container Registry product detail pages.
The documentation in this guide assumes that readers possess a basic understanding of what Docker
is and how it works. For more information about Docker, see What is Docker? and the Docker User Guide.
If you'd like to try out Docker before you install it, go to the interactive tutorial on the Docker website.
Topics
• Installing Docker (p. 6)
• Create a Docker Image (p. 7)
• Next Steps (p. 10)
Installing Docker
Docker is available on many different operating systems, including most modern Linux distributions, like
Ubuntu, and even Mac OSX and Windows (by using boot2docker). For more information about how to
install Docker on your particular operating system, go to the Docker installation guide.
You don't even need a local development system to use Docker. If you are using Amazon EC2 already,
you can launch an Amazon Linux instance and install Docker to get started.
To install Docker on an Amazon Linux instance
1.
Launch an instance with the Amazon Linux 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.
Update the installed packages and package cache on your instance.
3.
[ec2-user ~]$ sudo yum update -y
API Version 2015-09-21
6
Amazon ECR User Guide
Create a Docker Image
4.
Install Docker. Amazon ECR requires a minimum Docker version of 1.7 (version 1.9.1 is
recommended), and the default Docker versions in many system package managers, such as yum
or apt-get do not meet this minimum requirement. For information about installing the latest Docker
version on your particular Linux distribution, go to https://docs.docker.com/installation/.
[ec2-user ~]$ sudo yum install -y docker
5.
Start the Docker service.
[ec2-user ~]$ sudo service docker start
Starting cgconfig service:
Starting docker:
6.
[
OK
[
]
OK
]
Add the ec2-user to the docker group so you can execute Docker commands without using sudo.
[ec2-user ~]$ sudo usermod -a -G docker ec2-user
7.
Log out and log back in again to pick up the new docker group permissions.
8.
Verify that the ec2-user can run Docker commands without sudo.
[ec2-user ~]$ docker info
Containers: 2
Images: 24
Storage Driver: devicemapper
Pool Name: docker-202:1-263460-pool
Pool Blocksize: 65.54 kB
Data file: /var/lib/docker/devicemapper/devicemapper/data
Metadata file: /var/lib/docker/devicemapper/devicemapper/metadata
Data Space Used: 702.3 MB
Data Space Total: 107.4 GB
Metadata Space Used: 1.864 MB
Metadata Space Total: 2.147 GB
Library Version: 1.02.89-RHEL6 (2014-09-01)
Execution Driver: native-0.2
Kernel Version: 3.14.27-25.47.amzn1.x86_64
Operating System: Amazon Linux AMI 2014.09
Create a Docker Image
In this section, you create a Docker image of a simple PHP web application, and test it on your local
system or EC2 instance.
To create a Docker image of a PHP web application
1.
Install git and use it to clone the simple PHP application from your GitHub repository onto your
system.
a.
Install git.
[ec2-user ~]$ sudo yum install -y git
API Version 2015-09-21
7
Amazon ECR User Guide
Create a Docker Image
b.
Clone the simple PHP application onto your system.
[ec2-user ~]$ git clone https://github.com/awslabs/ecs-demo-php-simpleapp
2.
Change directories to the ecs-demo-php-simple-app folder.
[ec2-user ~]$ cd ecs-demo-php-simple-app
3.
Examine the Dockerfile in this folder. 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.
[ec2-user ecs-demo-php-simple-app]$ cat Dockerfile
FROM ubuntu:12.04
# Install dependencies
RUN apt-get update -y
RUN apt-get install -y git curl apache2 php5 libapache2-mod-php5 php5-mcrypt
php5-mysql
# Install app
RUN rm -rf /var/www/*
ADD src /var/www
# Configure apache
RUN a2enmod rewrite
RUN chown -R www-data:www-data /var/www
ENV APACHE_RUN_USER www-data
ENV APACHE_RUN_GROUP www-data
ENV APACHE_LOG_DIR /var/log/apache2
EXPOSE 80
CMD ["/usr/sbin/apache2", "-D",
"FOREGROUND"]
This Dockerfile uses the Ubuntu 12.04 image. The RUN instructions update the package caches,
install some software packages for the web server and PHP support, and then add your PHP
application to the web server's document root. The EXPOSE instruction exposes port 80 on the
container, and the CMD instruction starts the web server.
4.
Build the Docker image from your Dockerfile and tag it as amazon-ecs-sample in your default
Amazon ECR registry. Substitute aws_account_id with your AWS account ID.
[ec2-user ecs-demo-php-simple-app]$ docker build -t aws_account_id.dkr.ecr.useast-1.amazonaws.com/amazon-ecs-sample .
5.
Run docker images to verify that the image was created correctly and that the image name contains
a repository that you can push to (in this example, your Amazon ECR registry).
[ec2-user ecs-demo-php-simple-app]$ docker images
REPOSITORY
API Version 2015-09-21
8
TAG
Amazon ECR User Guide
Create a Docker Image
IMAGE ID
CREATED
VIRTUAL SIZE
aws_account_id.dkr.ecr.us-east-1.amazonaws.com/amazon-ecs-sample
8df953fe88f7
27 minutes ago
260.8 MB
ubuntu
2a7a952931ec
3 weeks ago
136.1 MB
6.
latest
12.04
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.
[ec2-user ecs-demo-php-simple-app]$ docker run -p 80:80 aws_ac
count_id.dkr.ecr.us-east-1.amazonaws.com/amazon-ecs-sample
apache2: Could not reliably determine the server's fully qualified domain
name, using 172.17.0.2 for ServerName
Note
Output 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.
7.
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 traffic on port 80.
•
If you are running Docker locally on a Linux computer, point your browser to http://localhost/.
•
If you are using boot2docker on a Windows or Mac computer, find the IP address of the
VirtualBox VM that is hosting Docker with the boot2docker ip command.
$ boot2docker ip
192.168.59.103
You should see a web page running the simple PHP app.
8.
Stop the Docker container by typing Ctrl+c.
API Version 2015-09-21
9
Amazon ECR User Guide
Next Steps
Next Steps
Now that you have created and tested your image, you can follow the procedures in Getting Started with
Amazon ECR (p. 11) or Using the AWS CLI with Amazon ECR (p. 36) to push the image to your Amazon
ECR registry.
API Version 2015-09-21
10
Amazon ECR User Guide
Getting Started with Amazon ECR
Get started with Amazon EC2 Container Registry (Amazon ECR) by creating a repository in the Amazon
ECS console. The Amazon ECR first run wizard guides you through the process to get started with
Amazon ECR.
Important
Before you begin, be sure that you've completed the steps in Setting Up with Amazon ECR (p. 3).
Configure repository
A repository is a place that you store Docker images in Amazon ECR. Every time you push or pull an
image from Amazon ECR, you specify the registry and repository location to tell Docker where to push
the image to or where to pull it from.
1.
2.
Open the Amazon ECS console repositories page at https://console.aws.amazon.com/ecs/
home?region=us-east-1#/repositories.
For Repository name, enter a unique name for your repository and choose Next step.
Build, tag, and push 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 Dockerfile or pulled from another registry, such as Docker Hub) and then push the tagged image
to your Amazon ECR registry.
1.
Retrieve the docker login command that you can use to authenticate your Docker client to your
registry by pasting the aws ecr get-login command from the console into a terminal window.
Note
The get-login command is available in the AWS CLI starting with version 1.9.15. You can
check your AWS CLI version with the aws --version command.
2.
Run the docker login command that was returned in the previous step. This command provides an
authorization token that is valid for 12 hours.
Important
When you execute this docker login command, the command string can be visible by other
users on your system in a process list (ps -e) display. Because the docker login command
contains authentication credentials, there is a risk that other users on your system could
view them this way and use them to gain push and pull access to your repositories. If you
are not on a secure system, you should consider this risk and log in interactively by omitting
the -p password option, and then entering the password when prompted.
API Version 2015-09-21
11
Amazon ECR User Guide
3.
4.
5.
6.
(Optional) If you have a Dockerfile for the image you want to push, build the image and tag it for your
new repository by pasting the docker build command from the console into a terminal window (make
sure you are in the same directory as your Dockerfile).
Tag the image for your Amazon ECR registry 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 that you want to push.
Push the newly tagged image to your Amazon ECR repository by pasting the docker push command
into a terminal window.
Choose Done to finish.
API Version 2015-09-21
12
Amazon ECR User Guide
Registry Concepts
Amazon ECR Registries
You can use Amazon ECR registries to host your images in a highly available and scalable architecture,
allowing you to deploy containers reliably for your applications. You can use your registry to manage
image repositories and Docker images. Each AWS account is provided with a single (default) Amazon
ECR registry.
Registry Concepts
• The URL for your default registry is
https://aws_account_id.dkr.ecr.us-east-1.amazonaws.com.
• By default, you have read and write access to the repositories and images you create in your default
registry.
• You can authenticate your Docker client to a registry so that you can use the docker push and docker
pull command to push and pull images to and from the repositories in that registry. For more information,
see Registry Authentication (p. 13).
• Repositories can be controlled with both IAM user access policies and repository policies.
Registry Authentication
You can use the AWS Management Console, the AWS CLI, or the AWS SDKs to create and manage
repositories, and to perform some actions on images, such as listing or deleting them. These clients use
standard AWS authentication methods. Although technically you can use the Amazon ECR API to push
and pull images, you are much more likely to use Docker CLI (or a language-specific Docker library) for
these purposes.
Because the Docker CLI does not support the standard AWS authentication methods, you must authenticate
your Docker client another way so that Amazon ECR knows who is requesting to push or pull an image.
If you are using the Docker CLI, then use the docker login command to authenticate to an Amazon ECR
registry with an authorization token that is provided by Amazon ECR and is valid for 12 hours. The
GetAuthorizationToken API operation provides a base64-encoded authorization token that contains a
user name (AWS) and a password that you can decode and use in a docker login command. However,
a much simpler get-login command (which retrieves the token, decodes it, and converts it to a docker
login command for you) is available in the AWS CLI.
API Version 2015-09-21
13
Amazon ECR User Guide
Registry Authentication
To authenticate Docker to an Amazon ECR registry with get-login
Note
The get-login command is available in the AWS CLI starting with version 1.9.15. You can check
your AWS CLI version with the aws --version command.
1.
Run the aws ecr get-login command. The example below is for the default registry associated with
the account making the request. To access other account registries, use the --registry-ids
aws_account_id option. For more information, see get-login in the AWS Command Line Interface
Reference.
$ aws ecr get-login
docker login -u AWS -p password -e none https://aws_account_id.dkr.ecr.useast-1.amazonaws.com
2.
The resulting output is a docker login command that you use to authenticate your Docker client to
your Amazon ECR registry.
Copy and paste the docker login command into a terminal to authenticate your Docker CLI to the
registry. This command provides an authorization token that is valid for the specified registry for 12
hours.
Important
When you execute this docker login command, the command string can be visible by other
users on your system in a process list (ps -e) display. Because the docker login command
contains authentication credentials, there is a risk that other users on your system could
view them this way and use them to gain push and pull access to your repositories. If you
are not on a secure system, you should consider this risk and log in interactively by omitting
the -p password option, and then entering the password when prompted.
API Version 2015-09-21
14
Amazon ECR User Guide
Repository Concepts
Amazon ECR Repositories
Amazon ECR provides API operations to create, monitor, and delete repositories and set repository
permissions that control who can access them. You can perform the same actions in the Repositories
section of the Amazon ECS console. Amazon ECR also integrates with the Docker CLI allowing you to
push and pull images from your development environments to your repositories.
Topics
• Repository Concepts (p. 15)
• Creating a Repository (p. 15)
• Deleting a Repository (p. 16)
• Amazon ECR Repository Policies (p. 17)
Repository Concepts
• By default, you have read and write access to the repositories you create in your default registry
(aws_account_id.dkr.ecr.us-east-1.amazonaws.com).
• 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 could use the team-a namespace
while Team B uses the team-b namespace. Each team could have their own image called web-app,
but because they are each prefaced with the team namespace, the two images can be used
simultaneously without interference. Team A's image would be called team-a/web-app, while Team
B's image would be called team-b/web-app.
• Repositories can be controlled with both IAM user access policies and repository policies.
Creating a Repository
Before you can push your Docker images to Amazon ECR, you need to create a repository to store them
in. You can create Amazon ECR repositories with the AWS Management Console, or with the AWS CLI
and AWS SDKs.
To create a repository
1.
2.
Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
From the navigation bar, choose the region to create your repository in.
API Version 2015-09-21
15
Amazon ECR User Guide
Deleting a Repository
Note
Amazon ECR is available in the following regions:
Region Name
Region
US East (N. Virginia) us-east-1
US West (Oregon)
us-west-2
3.
4.
In the navigation pane, choose Repositories.
On the Repositories page, choose Create repository.
5.
6.
For Repository name, enter a unique name for your repository and choose Next step.
(Optional) On the Build, tag, and push Docker image page, complete the following steps to push
an image to your new repository. If you do not want to push an image at this time, you can choose
Done to finish.
a.
Retrieve the docker login command that you can use to authenticate your Docker client to your
registry by pasting the aws ecr get-login command from the console into a terminal window.
Note
The get-login command is available in the AWS CLI starting with version 1.9.15. You
can check your AWS CLI version with the aws --version command.
b.
Run the docker login command that was returned in the previous step. This command provides
an authorization token that is valid for 12 hours.
Important
When you execute this docker login command, the command string can be visible by
other users on your system in a process list (ps -e) display. Because the docker login
command contains authentication credentials, there is a risk that other users on your
system could view them this way and use them to gain push and pull access to your
repositories. If you are not on a secure system, you should consider this risk and log
in interactively by omitting the -p password option, and then entering the password
when prompted.
c.
d.
e.
f.
(Optional) If you have a Dockerfile for the image you want to push, build the image and tag it
for your new repository by pasting the docker build command from the console into a terminal
window (make sure you are in the same directory as your Dockerfile).
Tag the image for your Amazon ECR registry 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 that you want to push.
Push the newly tagged image to your Amazon ECR repository by pasting the docker push
command into a terminal window.
Choose Done to finish.
Deleting a Repository
If you are done 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.
API Version 2015-09-21
16
Amazon ECR User Guide
Repository Policies
To delete a repository
1.
Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
2.
From the navigation bar, choose the region that contains the repository to delete.
Note
Amazon ECR is available in the following regions:
Region Name
Region
US East (N. Virginia) us-east-1
US West (Oregon)
us-west-2
3.
In the navigation pane, choose Repositories.
4.
On the Repositories page, select the box to the left of the repositories to delete and choose Delete
repository.
In the Delete repository window, verify that the selected repositories should be deleted and choose
Delete.
5.
Important
Any images in the selected repositories is also deleted.
Amazon ECR Repository Policies
Amazon ECR uses resource-based permissions to control access. Resource-based permissions let you
specify who has access to a repository and what actions they can perform on it. By default, only the
repository owner has access to a repository.You can apply a policy document that allows others to access
your repository.
Important
Amazon ECR users require permissions to call ecr:GetAuthorizationToken before they
can authenticate to a registry and push or pull any images from any Amazon ECR repository.
Amazon ECR provides several managed policies to control user access at varying levels; for
more information, see Amazon ECR Managed Policies (p. 32).
Topics
• Setting a Repository Policy Statement (p. 17)
• Deleting a Repository Policy Statement (p. 19)
• Amazon ECR Repository Policy Examples (p. 19)
Setting a Repository Policy Statement
You can create and set an access policy statement for your repositories in the AWS Management Console
by following the steps below. You can create multiple policy statements per repository.
Important
Amazon ECR users require permissions to call ecr:GetAuthorizationToken before they
can authenticate to a registry and push or pull any images from any Amazon ECR repository.
Amazon ECR provides several managed policies to control user access at varying levels; for
more information, see Amazon ECR Managed Policies (p. 32).
API Version 2015-09-21
17
Amazon ECR User Guide
Setting a Repository Policy Statement
To set a repository policy statement
1.
Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
2.
From the navigation bar, choose the region that contains the repository to set a policy statement on.
Note
Amazon ECR is available in the following regions:
Region Name
Region
US East (N. Virginia) us-east-1
US West (Oregon)
us-west-2
3.
In the navigation pane, choose Repositories.
4.
5.
On the Repositories page, choose the repository to set a policy statement on.
On the All repositories: repository_name page, choose Permissions, Add.
6.
7.
8.
For Sid, enter a description for what your policy statement does.
For Effect, choose whether the policy statement should allow access or deny it.
For Principal, choose the scope of users to apply the policy statement to.
• You can apply the statement to all authenticated AWS users by selecting the Everybody check
box.
• You can apply the statement to all users under specific AWS accounts by listing those accounts
in the AWS account number(s) field.
• You can apply the statement to roles or users under your AWS account by checking the roles or
users under the All IAM entities list and choosing >> Add to move them to the Selected IAM
entities list.
Note
For more complicated repository policies that are not currently supported in the AWS
Management Console, such as IAM users from another account, you can apply the policy
with the set-repository-policy AWS CLI command.
9.
For Action, choose the scope of the Amazon ECR API operations that the policy statement should
apply to. You can choose individual API operations, or you can choose from the preset task-based
options.
• All actions sets the scope to all Amazon ECR API operations.
• Push/Pull actions sets the scope to Amazon ECR API operations required to push or pull images
in this repository with the Docker CLI.
• Pull only actions sets the scope to Amazon ECR API operations required only to pull images
from this repository with the Docker CLI.
10. When you are finished, choose Save to set the policy.
Important
Amazon ECR users require permissions to call ecr:GetAuthorizationToken before
they can authenticate to a registry and push or pull any images from any Amazon ECR
repository. Amazon ECR provides several managed policies to control user access at varying
levels; for more information, see Amazon ECR Managed Policies (p. 32).
API Version 2015-09-21
18
Amazon ECR User Guide
Deleting a Repository Policy Statement
Deleting a 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
1.
2.
Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
From the navigation bar, choose the region that contains the repository to delete a policy statement
from.
Note
Amazon ECR is available in the following regions:
Region Name
Region
US East (N. Virginia) us-east-1
US West (Oregon)
us-west-2
3.
4.
5.
In the navigation pane, choose Repositories.
On the Repositories page, choose the repository to delete a policy statement from.
On the All repositories : repository_name page, choose the Permissions tab.
6.
In the Permission statements list, expand the policy statement to delete and choose Remove at
the bottom of the expanded statement.
Amazon ECR Repository Policy Examples
The following examples show policy statements that you could use to control the permissions that users
have to Amazon ECR repositories.
Important
Amazon ECR users require permissions to call ecr:GetAuthorizationToken before they
can authenticate to a registry and push or pull any images from any Amazon ECR repository.
Amazon ECR provides several managed policies to control user access at varying levels; for
more information, see Amazon ECR Managed Policies (p. 32).
Topics
• Example: Allow IAM Users Within Your Account (p. 19)
• Example: Allow Other Accounts (p. 20)
• Example: Deny All (p. 21)
Example: Allow IAM Users Within Your Account
The following repository policy allows IAM users within your account to push and pull images.
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "AllowPushPull",
"Effect": "Allow",
"Principal": {
API Version 2015-09-21
19
Amazon ECR User Guide
Repository Policy Examples
"AWS": [
"arn:aws:iam::aws_account_id:user/push-pull-user-1",
"arn:aws:iam::aws_account_id:user/push-pull-user-2"
]
},
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability",
"ecr:PutImage",
"ecr:InitiateLayerUpload",
"ecr:UploadLayerPart",
"ecr:CompleteLayerUpload"
]
}
]
}
Example: Allow Other Accounts
The following repository policy allows a specific account to push images.
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "AllowCrossAccountPush",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::aws_account_id:root"
},
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:PutImage",
"ecr:InitiateLayerUpload",
"ecr:UploadLayerPart",
"ecr:CompleteLayerUpload"
]
}
]
}
The following repository policy allows all AWS accounts to pull images.
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "AllowPull",
"Effect": "Allow",
"Principal": "*",
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
API Version 2015-09-21
20
Amazon ECR User Guide
Repository Policy Examples
]
}
]
}
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).
Note
For more complicated repository policies that are not currently supported in the AWS Management
Console, such as IAM users from another account, you can apply the policy with the
set-repository-policy AWS CLI command.
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "AllowPull",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::aws_account_id:user/pull-user-1",
"arn:aws:iam::aws_account_id:user/pull-user-2"
]
},
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
]
},
{
"Sid": "AllowAll",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::aws_account_id:user/admin-user"
},
"Action": [
"ecr:*"
]
}
]
}
Example: Deny All
The following repository policy denies all users the ability to pull images.
{
"Version": "2008-10-17",
"Statement": [
{
"Sid": "DenyPull",
"Effect": "Deny",
"Principal": "*",
"Action": [
API Version 2015-09-21
21
Amazon ECR User Guide
Repository Policy Examples
"ecr:GetDownloadUrlForLayer",
"ecr:BatchGetImage",
"ecr:BatchCheckLayerAvailability"
]
}
]
}
API Version 2015-09-21
22
Amazon ECR User Guide
Pushing an Image
Images
Amazon ECR stores Docker images in image repositories. You can use the Docker CLI to push and pull
images from your repositories.
Important
Amazon ECR users require permissions to call ecr:GetAuthorizationToken before they
can authenticate to a registry and push or pull any images from any Amazon ECR repository.
Amazon ECR provides several managed policies to control user access at varying levels; for
more information, see Amazon ECR Managed Policies (p. 32).
Topics
• Pushing an Image (p. 23)
• Pulling an Image (p. 24)
• Using Amazon ECR Images with Amazon ECS (p. 25)
• Deleting an Image (p. 26)
Pushing an Image
If you have a Docker image available in your development environment, you can push it to an Amazon
ECR repository with the docker push command.
Important
Amazon ECR users require permissions to call ecr:GetAuthorizationToken before they
can authenticate to a registry and push or pull any images from any Amazon ECR repository.
Amazon ECR provides several managed policies to control user access at varying levels; for
more information, see Amazon ECR Managed Policies (p. 32).
To push a Docker image to an Amazon ECR repository
1.
Authenticate your Docker client to the Amazon ECR registry you intend to push your image to.
Authentication tokens must be obtained for each registry used, and the tokens are valid for 12 hours.
For more information, see Registry Authentication (p. 13).
2.
If your image repository does not exist in the registry to intend to push to yet, create it. For more
information, see Creating a Repository (p. 15).
3.
Identify the image to push. Run the docker images command to list the images on your system.
API Version 2015-09-21
23
Amazon ECR User Guide
Pulling an Image
$ docker images
4.
You can identify an image with the repository:tag or the image ID in the resulting command
output.
Tag your image with the Amazon ECR registry, repository, and optional image tag name combination
to use. The registry format is aws_account_id.dkr.ecr.us-east-1.amazonaws.com. The
repository name should match the repository that you created for your image. If you omit the image
tag, we assume the tag is latest.
The following example tags an image with the ID e9ae3c220b23 as
aws_account_id.dkr.ecr.us-east-1.amazonaws.com/my-web-app.
$ docker tag e9ae3c220b23 aws_account_id.dkr.ecr.us-east-1.amazonaws.com/myweb-app
5.
Push the image using the docker push command.
$ docker push aws_account_id.dkr.ecr.us-east-1.amazonaws.com/my-web-app
The push refers to a repository [aws_account_id.dkr.ecr.us-east-1.amazon
aws.com/my-web-app] (len: 1)
e9ae3c220b23: Pushed
a6785352b25c: Pushed
0998bf8fb9e9: Pushed
0a85502c06c9: Pushed
latest: digest:
sha256:01f58d96d1fa90e3eb0dd0ac3d893bcaf00d736f2bc82539d3531170e707648c
size: 6778
Pulling an Image
If you have a Docker image available in Amazon ECR, you can pull it to your local environment with the
docker pull command.
Important
Amazon ECR users require permissions to call ecr:GetAuthorizationToken before they
can authenticate to a registry and push or pull any images from any Amazon ECR repository.
Amazon ECR provides several managed policies to control user access at varying levels; for
more information, see Amazon ECR Managed Policies (p. 32).
To pull a Docker image from an Amazon ECR repository
1.
2.
Authenticate your Docker client to the Amazon ECR registry you intend to pull your image from.
Authentication tokens must be obtained for each registry used, and the tokens are valid for 12 hours.
For more information, see Registry Authentication (p. 13).
(Optional) Identify the image to pull.
•
You can list the repositories in a registry with the aws ecr describe-repositories command.
$ aws ecr describe-repositories
{
"repositories": [
{
API Version 2015-09-21
24
Amazon ECR User Guide
Using Amazon ECR Images with Amazon ECS
"registryId": "aws_account_id",
"repositoryName": "my-web-app",
"repositoryArn": "arn:aws:ecr:us-east-1:aws_account_id:repos
itory/my-web-app"
}
]
}
The example registry above has a repository called my-web-app.
•
You can list the images within a repository with the aws ecr list-images command.
$ aws ecr list-images --repository-name my-web-app
{
"imageIds": [
{
"imageTag": "latest",
"imageDigest":
"sha256:01f58d96d1fa90e3eb0dd0ac3d893bcaf00d736f2bc82539d3531170e707648c"
}
]
}
The example repository above has an image tagged as latest.
3.
Pull the image using the docker pull command. The image name format should be
registry/repository[:tag].
$$ docker pull aws_account_id.dkr.ecr.us-east-1.amazonaws.com/my-webapp:latest
latest: Pulling from my-web-app
0a85502c06c9: Pull complete
0998bf8fb9e9: Pull complete
a6785352b25c: Pull complete
e9ae3c220b23: Pull complete
Digest:
sha256:01f58d96d1fa90e3eb0dd0ac3d893bcaf00d736f2bc82539d3531170e707648c
Status: Downloaded newer image for aws_account_id.dkr.ecr.us-east-1.amazon
aws.com/my-web-app:latest
Using Amazon ECR Images with Amazon ECS
You can use your Amazon ECR images with Amazon ECS, but you need to satisfy some prerequisites:
• Your container instances must be using at least version 1.7.0 of the Amazon ECS container agent.
The latest version of the Amazon ECS-optimized AMI supports Amazon ECR images in task definitions.
For more information, including the latest Amazon ECS-optimized AMI IDs, see Amazon ECS Container
Agent Versions in the Amazon EC2 Container Service Developer Guide.
• The Amazon ECS container instance role (ecsInstanceRole) that you use with your container
instances must possess the following IAM policy permissions for Amazon ECR.
API Version 2015-09-21
25
Amazon ECR User Guide
Deleting an Image
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:BatchCheckLayerAvailability",
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"ecr:GetAuthorizationToken"
],
"Resource": "*"
}
]
}
If you use the AmazonEC2ContainerServiceforEC2Role managed policy for your container
instances, then your role has the proper permissions. To check that your role supports Amazon ECR,
see Amazon ECS Container Instance IAM Role in the Amazon EC2 Container Service Developer
Guide.
• In your Amazon ECS task definitions, make sure that you are using the full registry/repository:tag
naming for your Amazon ECR images. For example,
aws_account_id.dkr.ecr.us-east-1.amazonaws.com/my-web-app:latest.
Deleting an Image
If you are done using an image, you can delete it from your repository. You can delete an image using
the AWS Management Console, or the AWS CLI.
Note
If you are done with a repository, you can delete the entire repository and all of the images within
it. For more information, see Deleting a Repository (p. 16).
To delete an image with the AWS Management Console
1.
2.
Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.
From the navigation bar, choose the region that contains the image to delete.
Note
Amazon ECR is available in the following regions:
Region Name
Region
US East (N. Virginia) us-east-1
US West (Oregon)
us-west-2
3.
In the navigation pane, choose Repositories.
4.
5.
On the Repositories page, choose the repository that contains the image to delete.
On the All repositories: repository_name page, select the box to the left of the images to delete
and choose Delete.
In the Delete image(s) dialog box, verify that the selected images should be deleted and choose
Delete.
6.
API Version 2015-09-21
26
Amazon ECR User Guide
Deleting an Image
To delete an image with the AWS CLI
1.
List the images in your repository so that you can identify them by image tag.
$ aws ecr list-images --repository-name my-repo
{
"imageIds": [
{
"imageTag": "latest",
"imageDigest":
"sha256:4f70ef7a4d29e8c0c302b13e25962d8f7a0bd304c7c2c1a9d6fa3e9de6bf552d"
}
]
}
2.
Delete the image by specifying the tag of the image you want to delete.
$ aws ecr batch-delete-image --repository-name my-repo --image-ids imageT
ag=latest
{
"failures": [],
"imageIds": [
{
"imageTag": "latest",
"imageDigest":
"sha256:4f70ef7a4d29e8c0c302b13e25962d8f7a0bd304c7c2c1a9d6fa3e9de6bf552d"
}
]
}
API Version 2015-09-21
27
Amazon ECR User Guide
Amazon ECR IAM Policies and
Roles
By default, IAM users don't have permission to create or modify Amazon ECR resources, or perform
tasks using the Amazon ECR API. (This means that they also can't do so using the Amazon ECR console
or the AWS CLI.) To allow IAM users to create or modify resources and perform tasks, you must create
IAM policies that grant IAM users permission to use the specific resources and API operations they'll
need, and then attach those policies to the IAM users or groups that require those permissions.
When you attach a policy to a user or group of users, it allows or denies the users permission to perform
the specified tasks on the specified resources. For more information, see Permissions and Policies and
Managing IAM Policies in the IAM User Guide.
Likewise, Amazon ECS container instances make calls to the Amazon ECR APIs on your behalf (to pull
Docker images that are used in Amazon ECS task definitions), so they need to authenticate with your
credentials. This authentication is accomplished by creating an IAM role for your container instances and
associating that role with your container instances when you launch them. For more information, see
Amazon ECS Container Instance IAM Role in the Amazon EC2 Container Service Developer Guide. For
more information about IAM roles, see IAM Roles in the IAM User Guide.
Getting Started
An IAM policy must grant or deny permission to use one or more Amazon ECR operations. It must also
specify the resources that can be used with the operation, which can be all resources, or in some cases,
specific resources. The policy can also include conditions that you apply to the resource.
Amazon ECR partially supports resource-level permissions. This means that for some Amazon ECS API
operations, you cannot specify which resource a user is allowed to work with for that operation; instead,
you have to allow users to work with all resources for that operation.
Topics
• Policy Structure (p. 29)
• Amazon ECR Managed Policies (p. 32)
• Supported Resource-Level Permissions for Amazon ECR API Actions (p. 34)
• Creating Amazon ECR IAM Policies (p. 35)
API Version 2015-09-21
28
Amazon ECR User Guide
Policy Structure
Policy Structure
The following topics explain the structure of an IAM policy.
Topics
• Policy Syntax (p. 29)
• Actions for Amazon ECR (p. 30)
• Amazon Resource Names for Amazon ECR (p. 30)
• Condition Keys for Amazon ECR (p. 31)
• Checking that Users Have the Required Permissions (p. 31)
Policy Syntax
An IAM policy is a JSON document that consists of one or more statements. Each statement is structured
as follows:
{
"Statement":[{
"Effect":"effect",
"Action":"action",
"Resource":"arn",
"Condition":{
"condition":{
"key":"value"
}
}
}
]
}
There are various elements that make up a statement:
• Effect: The effect can be Allow or Deny. By default, IAM users don't have permission to use resources
and API operations, so all requests are denied. An explicit allow overrides the default. An explicit deny
overrides any allows.
• Action: The action is the specific API operation for which you are granting or denying permission. To
learn about specifying action, see Actions for Amazon ECR (p. 30).
• Resource: The resource that's affected by the action. Some Amazon ECR API operations allow you
to include specific resources in your policy that can be created or modified by the operation. To specify
a resource in the statement, you need to use its Amazon Resource Name (ARN). For more information
about specifying the arn value, see Amazon Resource Names for Amazon ECR (p. 30). For more
information about which API operations support which ARNs, see Supported Resource-Level Permissions
for Amazon ECR API Actions (p. 34). If the API operation does not support ARNs, use the * (asterisk)
wildcard to specify that all resources can be affected by the operation.
• Condition: Conditions are optional and can control when your policy will be in effect. For more
information about specifying conditions for Amazon ECR, see Condition Keys for Amazon ECR (p. 31).
API Version 2015-09-21
29
Amazon ECR User Guide
Actions for Amazon ECR
Actions for Amazon ECR
In an IAM policy statement, you can specify any API operation from any service that supports IAM. For
Amazon ECR, use the following prefix with the name of the API operation: ecr:. For example:
ecr:CreateRepository and ecs:DeleteRepository.
To specify multiple operations in a single statement, separate them with commas as follows:
"Action": ["ecr:action1", "ecr:action2"]
You can also specify multiple operations using wildcards. For example, you can specify all operations
whose name begins with the word "Delete" as follows:
"Action": "ecr:Delete*"
To specify all Amazon ECR API operations, use the * (asterisk) wildcard as follows:
"Action": "ecr:*"
For a list of Amazon ECR operations, see Actions in the Amazon EC2 Container Registry API Reference.
Amazon Resource Names for Amazon ECR
Each IAM policy statement applies to the resources that you specify using their ARNs.
Important
Currently, not all API actions support individual ARNs; we'll add support for additional API actions
and ARNs for additional Amazon ECR resources later. For information about which ARNs you
can use with which Amazon ECR API operations, see Supported Resource-Level Permissions
for Amazon ECR API Actions (p. 34).
An ARN has the following general syntax:
arn:aws:[service]:[region]:[account]:resourceType/resourcePath
service
The service (for example, ecr).
region
The region for the resource (for example, us-east-1).
account
The AWS account ID, with no hyphens (for example, 123456789012).
resourceType
The type of resource (for example, instance).
resourcePath
A path that identifies the resource. You can use the * (asterisk) wildcard in your paths.
For example, you can indicate a specific repository (my-repo) in your statement using its ARN as follows:
"Resource": "arn:aws:ecr:us-east-1:123456789012:repository/my-repo"
You can also specify all repositories that belong to a specific account by using the * wildcard as follows:
API Version 2015-09-21
30
Amazon ECR User Guide
Condition Keys for Amazon ECR
"Resource": "arn:aws:ecs:us-east-1:123456789012:repository/*"
To specify all resources, or if a specific API operation does not support ARNs, use the * wildcard in the
Resource element as follows:
"Resource": "*"
The following table describes the ARNs for each type of resource used by the Amazon ECR API operations.
Resource Type
ARN
All Amazon ECR resources
arn:aws:ecr:*
All Amazon ECR resources
owned by the specified account
in the specified region
arn:aws:ecr:region:account:*
Repository
arn:aws:ecr:region:account:repository/repository-name
Many Amazon ECR API operations accept multiple resources. To specify multiple resources in a single
statement, separate their ARNs with commas, as follows:
"Resource": ["arn1", "arn2"]
For more information, see Amazon Resource Names (ARN) and AWS Service Namespaces in the Amazon
Web Services General Reference.
Condition Keys for Amazon ECR
In a policy statement, you can optionally specify conditions that control when it is in effect. Each condition
contains one or more key-value pairs. Condition keys are not case-sensitive. We've defined AWS-wide
condition keys, plus additional service-specific condition keys.
If you specify multiple conditions, or multiple keys in a single condition, we evaluate them using a logical
AND operation. If you specify a single condition with multiple values for one key, we evaluate the condition
using a logical OR operation. For permission to be granted, all conditions must be met.
You can also use placeholders when you specify conditions. For more information, see Policy Variables
in the IAM User Guide.
Amazon ECR implements the AWS-wide condition keys (see Available Keys),.
For example repository policy statements for Amazon ECR, see Amazon ECR Repository Policies (p. 17).
Checking that Users Have the Required
Permissions
After you've created an IAM policy, we recommend that you check whether it grants users the permissions
to use the particular API operations and resources they need before you put the policy into production.
First, create an IAM user for testing purposes, and then attach the IAM policy that you created to the test
user. Then, make a request as the test user. You can make test requests in the console or with the AWS
CLI.
API Version 2015-09-21
31
Amazon ECR User Guide
Amazon ECR Managed Policies
Note
You can also test your policies with the IAM Policy Simulator. For more information about the
policy simulator, see Working with the IAM Policy Simulator in the IAM User Guide.
If the action that you are testing creates or modifies a resource, you should make the request using the
DryRun parameter (or run the AWS CLI command with the --dry-run option). In this case, the call
completes the authorization check, but does not complete the operation. For example, you can check
whether the user can terminate a particular instance without actually terminating it. If the test user has
the required permissions, the request returns DryRunOperation; otherwise, it returns
UnauthorizedOperation.
If the policy doesn't grant the user the permissions that you expected, or is overly permissive, you can
adjust the policy as needed and retest until you get the desired results.
Important
It can take several minutes for policy changes to propagate before they take effect. Therefore,
we recommend that you allow five minutes to pass before you test your policy updates.
If an authorization check fails, the request returns an encoded message with diagnostic information. You
can decode the message using the DecodeAuthorizationMessage action. For more information, see
DecodeAuthorizationMessage in the AWS Security Token Service API Reference, and
decode-authorization-message in the AWS Command Line Interface Reference.
Amazon ECR Managed Policies
Amazon ECR provides several managed policies that you can attach to IAM users or EC2 instances that
allow differing levels of control over Amazon ECR resources and API operations. You can apply these
policies directly, or you can use them as starting points for creating your own polices. For more information
about each API operation mentioned in these policies, see Actions in the Amazon EC2 Container Registry
API Reference.
Topics
• AmazonEC2ContainerRegistryFullAccess (p. 32)
• AmazonEC2ContainerRegistryPowerUser (p. 33)
• AmazonEC2ContainerRegistryReadOnly (p. 33)
AmazonEC2ContainerRegistryFullAccess
This policy allows full administrator access to Amazon ECR.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:*"
],
"Resource": "*"
}
]
}
API Version 2015-09-21
32
Amazon ECR User Guide
AmazonEC2ContainerRegistryPowerUser
AmazonEC2ContainerRegistryPowerUser
This policy allows power user access to Amazon ECR, which allows read and write access to repositories,
but does not allow users to delete repositories or change the policy documents applied to them.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:GetAuthorizationToken",
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:GetRepositoryPolicy",
"ecr:DescribeRepositories",
"ecr:ListImages",
"ecr:BatchGetImage",
"ecr:InitiateLayerUpload",
"ecr:UploadLayerPart",
"ecr:CompleteLayerUpload",
"ecr:PutImage"
],
"Resource": "*"
}
]
}
AmazonEC2ContainerRegistryReadOnly
This policy allows read-only access to Amazon ECR, such as the ability to list repositories and the images
within the repositories, and also to pull images from Amazon ECR with the Docker CLI.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"ecr:GetAuthorizationToken",
"ecr:BatchCheckLayerAvailability",
"ecr:GetDownloadUrlForLayer",
"ecr:GetRepositoryPolicy",
"ecr:DescribeRepositories",
"ecr:ListImages",
"ecr:BatchGetImage"
],
"Resource": "*"
}
]
}
API Version 2015-09-21
33
Amazon ECR User Guide
Supported Resource-Level Permissions
Supported Resource-Level Permissions for
Amazon ECR API Actions
Resource-level permissions refers to the ability to specify which resources users are allowed to perform
actions on. Amazon ECR has partial support for resource-level permissions. This means that for certain
Amazon ECR operations, you can control when users are allowed to use those operations based on
conditions that have to be fulfilled, or specific resources that users are allowed to use.
The following table describes the Amazon ECR API operations that currently support resource-level
permissions, as well as the supported resources and resource ARNs for each.
Important
If an Amazon ECR API operation is not listed in this table, then it does not support resource-level
permissions. If an API operation does not support resource-level permissions, you can grant
users permission to use the operation, but you have to specify the * (asterisk) wildcard for the
resource element of your policy statement.
API action
Resource
BatchCheckLayerAvailability
Repository
arn:aws:ecr:region:account:repository/my-repo
BatchDeleteImage
Repository
arn:aws:ecr:region:account:repository/my-repo
BatchGetImage
Repository
arn:aws:ecr:region:account:repository/my-repo
CompleteLayerUpload
Repository
arn:aws:ecr:region:account:repository/my-repo
DeleteRepository
Repository
arn:aws:ecr:region:account:repository/my-repo
DeleteRepositoryPolicy
Repository
arn:aws:ecr:region:account:repository/my-repo
DescribeRepositories
Repository
arn:aws:ecr:region:account:repository/my-repo
GetDownloadUrlForLayer
Repository
arn:aws:ecr:region:account:repository/my-repo
GetRepositoryPolicy
Repository
arn:aws:ecr:region:account:repository/my-repo
InitiateLayerUpload
Repository
arn:aws:ecr:region:account:repository/my-repo
API Version 2015-09-21
34
Amazon ECR User Guide
Creating IAM Policies
API action
Resource
ListImages
Repository
arn:aws:ecr:region:account:repository/my-repo
PutImage
Repository
arn:aws:ecr:region:account:repository/my-repo
SetRepositoryPolicy
Repository
arn:aws:ecr:region:account:repository/my-repo
UploadLayerPart
Repository
arn:aws:ecr:region:account:repository/my-repo
Creating Amazon ECR IAM Policies
You can create specific IAM policies to restrict the calls and resources that users in your account have
access to, and then attach those policies to IAM users.
When you attach a policy to a user or group of users, it allows or denies the users permission to perform
the specified tasks on the specified resources. For more general information about IAM policies, see
Permissions and Policies in the IAM User Guide. For more information about managing and creating
custom IAM policies, see Managing IAM Policies.
To create an IAM policy for a user
1.
2.
3.
4.
Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Policies, Create Policy.
In the Create Policy section, choose Select next to Create Your Own Policy.
For Policy Name, type your own unique name, such as AmazonECRUserPolicy.
5.
For Policy Document, paste the policy to apply to the user. Examples are provided in the sections
below.
Choose Create Policy to finish.
6.
To attach an IAM policy to a user
1.
2.
Open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Users and then choose the user to attach the policy to.
3.
4.
In the Permissions tab, choose Attach Policy.
In the Attach Policy section, select the custom policy you created in the previous procedure and
then choose Attach Policy.
API Version 2015-09-21
35
Amazon ECR User Guide
Step 1: Authenticate Docker to your Default Registry
Using the AWS CLI with Amazon
ECR
The following steps will help you install the AWS CLI and then log in to Amazon ECR, create an image
repository, push an image to that repository, and perform other common scenarios in Amazon ECR with
the AWS CLI.
The AWS Command Line Interface (CLI) is a unified tool to manage your AWS services. With just one
tool to download and configure, you can control multiple AWS services from the command line and
automate them through scripts. For more information on the AWS CLI, see http://aws.amazon.com/cli/.
For more information on the other tools available for managing your AWS resources, including the different
AWS SDKs, IDE toolkits, and the Windows PowerShell command line tools, see http://aws.amazon.com/
tools/.
Topics
• Step 1: Authenticate Docker to your Default Registry (p. 36)
• Step 3: Get a Docker Image (p. 37)
• Step 4: Create a Repository (p. 37)
• Step 5: Push an Image to Amazon ECR (p. 38)
• Step 6: Pull an Image from Amazon ECR (p. 39)
• Step 8: Delete an Image (p. 39)
• Step 9: Delete a Repository (p. 39)
Step 1: Authenticate Docker to your Default
Registry
After you have installed and configured the AWS CLI, you can authenticate the Docker CLI to your default
registry so that the docker command can push and pull images with Amazon ECR. The AWS CLI provides
a get-login command to simplify the authentication process.
API Version 2015-09-21
36
Amazon ECR User Guide
Step 3: Get a Docker Image
To authenticate Docker to an Amazon ECR registry with get-login
Note
The get-login command is available in the AWS CLI starting with version 1.9.15. You can check
your AWS CLI version with the aws --version command.
1.
Run the aws ecr get-login command. The example below is for the default registry associated with
the account making the request. To access other account registries, use the --registry-ids
aws_account_id option. For more information, see get-login in the AWS Command Line Interface
Reference.
$ aws ecr get-login
docker login -u AWS -p password -e none https://aws_account_id.dkr.ecr.useast-1.amazonaws.com
2.
The resulting output is a docker login command that you use to authenticate your Docker client to
your Amazon ECR registry.
Copy and paste the docker login command into a terminal to authenticate your Docker CLI to the
registry. This command provides an authorization token that is valid for the specified registry for 12
hours.
Important
When you execute this docker login command, the command string can be visible by other
users on your system in a process list (ps -e) display. Because the docker login command
contains authentication credentials, there is a risk that other users on your system could
view them this way and use them to gain push and pull access to your repositories. If you
are not on a secure system, you should consider this risk and log in interactively by omitting
the -p password option, and then entering the password when prompted.
Step 3: Get a Docker Image
Before you can push an image to Amazon ECR, you need to have one to push. If you do not already
have an image to use, you can create one by following the steps in Docker Basics (p. 6), or you can
simply pull an image from Docker Hub that you would like to have in your Amazon ECR registry. To pull
the ubuntu:trusty image from Docker hub to your local system, run the following command:
$ docker pull ubuntu:trusty
trusty: Pulling from library/ubuntu
0a85502c06c9: Pull complete
0998bf8fb9e9: Pull complete
a6785352b25c: Pull complete
e9ae3c220b23: Pull complete
Digest: sha256:3cb273da02362a6e667b54f6cf907edd5255c706f9de279c97cfccc7c6988124
Status: Downloaded newer image for ubuntu:trusty
Step 4: Create a Repository
Now that you have an image to push to Amazon ECR, you need to create a repository to hold it. In this
example, you create a repository called ubuntu to which you later push the ubuntu:trusty image. To
create a repository, run the following command:
API Version 2015-09-21
37
Amazon ECR User Guide
Step 5: Push an Image to Amazon ECR
$ aws ecr create-repository --repository-name ubuntu
{
"repository": {
"registryId": "111122223333",
"repositoryName": "ubuntu",
"repositoryArn": "arn:aws:ecr:us-east-1:111122223333:repository/ubuntu"
}
}
Step 5: 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 satisfied for this to
work properly:
• The minimum version of docker is installed: 1.7
• The Amazon ECR authorization token has been configured 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
REPOSITORY
VIRTUAL SIZE
ubuntu
187.9 MB
2.
TAG
IMAGE ID
CREATED
trusty
e9ae3c220b23
3 weeks ago
Tag the image to push to your repository.
$ docker tag ubuntu:trusty aws_account_id.dkr.ecr.us-east-1.amazon
aws.com/ubuntu:trusty
3.
Push the image.
$ docker push aws_account_id.dkr.ecr.us-east-1.amazonaws.com/ubuntu:trusty
The push refers to a repository [aws_account_id.dkr.ecr.us-east-1.amazon
aws.com/ubuntu] (len: 1)
e9ae3c220b23: Pushed
a6785352b25c: Pushed
0998bf8fb9e9: Pushed
0a85502c06c9: Pushed
trusty: digest:
sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b
size: 6774
API Version 2015-09-21
38
Amazon ECR User Guide
Step 6: Pull an Image from Amazon ECR
Step 6: Pull an Image from Amazon ECR
After your image has been pushed to your Amazon ECR repository, you can pull it from other locations.
We will use the docker CLI to pull images, but there are a few prerequisites that must be satisfied for
this to work properly:
• The minimum version of docker is installed: 1.7
• The Amazon ECR authorization token has been configured 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.us-east-1.amazonaws.com/ubuntu:trusty
trusty: Pulling from ubuntu
0a85502c06c9: Pull complete
0998bf8fb9e9: Pull complete
a6785352b25c: Pull complete
e9ae3c220b23: Pull complete
Digest: sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b
Status: Downloaded newer image for aws_account_id.dkr.ecr.us-east-1.amazon
aws.com/ubuntu:trusty
Step 8: 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
ubuntu repository with the image tag trusty.
$ aws ecr batch-delete-image --repository-name ubuntu --image-ids imageTag=trusty
{
"failures": [],
"imageIds": [
{
"imageTag": "trusty",
"imageDigest":
"sha256:215d7e4121b30157d8839e81c4e0912606fca105775bb0636b95aed25f52c89b"
}
]
}
Step 9: 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 flag allows this.
To delete a repository that contains images (and all the images within it), run the following command:
API Version 2015-09-21
39
Amazon ECR User Guide
Step 9: Delete a Repository
$ aws ecr delete-repository --repository-name ubuntu --force
{
"repository": {
"registryId": "aws_account_id",
"repositoryName": "ubuntu",
"repositoryArn": "arn:aws:ecr:us-east-1:aws_account_id:repository/ubuntu"
}
}
API Version 2015-09-21
40
Amazon ECR User Guide
Amazon ECR Service Limits
The following table provides the default limits for Amazon ECR for an AWS account which can be changed.
For more information, see AWS Service Limitsin the Amazon Web Services General Reference.
Resource
Default Limit
Maximum number of repositories per account
1,000
Maximum number of images per repository
500
The following table provides other limitations for Amazon ECR and Docker images that cannot be changed.
Resource
Default Limit
Maximum number of layers per image
127 (this is the current Docker limit)
Maximum layer part size
10 MiB
Minimum layer part size
5 MiB (except the final layer part in an upload)
Maximum number of layer parts
1,000
API Version 2015-09-21
41
Amazon ECR User Guide
Amazon ECR Information in CloudTrail
Logging Amazon ECR API Calls By
Using AWS CloudTrail
Amazon ECR is integrated with CloudTrail, a service that captures all of the API calls made by or on
behalf of Amazon ECR in your AWS account and delivers the log files to an Amazon S3 bucket that you
specify. CloudTrail captures API calls from the Amazon ECR console or from the Amazon ECR API.
Using the information collected by CloudTrail, you can determine what request was made to Amazon
ECR, the source IP address from which the request was made, who made the request, when it was made,
and so on. To learn more about CloudTrail, including how to configure and enable it, see the AWS
CloudTrail User Guide.
Amazon ECR Information in CloudTrail
When CloudTrail logging is enabled in your AWS account, API calls made to Amazon ECR actions are
tracked in log files. Amazon ECR records are written together with other AWS service records in a log
file. CloudTrail determines when to create and write to a new file based on a time period and file size.
All of the Amazon ECR actions are logged by CloudTrail and are documented in the Amazon EC2 Container
Registry API Reference. For example, calls to the GetAuthorizationToken, CreateRepository and
SetRepositoryPolicy operations generate entries in the CloudTrail log files.
Every log entry contains information about who generated the request. The user identity information in
the log helps you determine whether the request was made with root or IAM user credentials, with
temporary security credentials for a role or federated user, or by another AWS service. For more
information, see the userIdentity field in the CloudTrail Event Reference.
You can store your log files in your bucket for as long as you want, but you can also define Amazon S3
lifecycle rules to archive or delete log files automatically. By default, your log files are encrypted by using
Amazon S3 server-side encryption (SSE).
You can choose to have CloudTrail publish Amazon SNS notifications when new log files are delivered
if you want to take quick action upon log file delivery. For more information, see Configuring Amazon
SNS Notifications.
You can also aggregate Amazon ECR log files from multiple AWS regions and multiple AWS accounts
into a single S3 bucket. For more information, see Aggregating CloudTrail Log Files to a Single Amazon
S3 Bucket.
API Version 2015-09-21
42
Amazon ECR User Guide
Understanding Amazon ECR Log File Entries
Understanding Amazon ECR Log File Entries
CloudTrail log files can contain one or more log entries where each entry is made up of multiple
JSON-formatted events. A log entry represents a single request from any source and includes information
about the requested action, any parameters, the date and time of the action, and so on. The log entries
are not guaranteed to be in any particular order. That is, they are not an ordered stack trace of the public
API calls.
API Version 2015-09-21
43
Amazon ECR User Guide
Document History for Amazon ECR
The following table describes the documentation for this release of Amazon ECR.
• API version: 2015-09-21
Change
Description
Date
Initial public release
Initial public release of Amazon
ECR
December 21, 2015
API Version 2015-09-21
44
Amazon ECR User Guide
AWS Glossary
For the latest AWS terminology, see the AWS Glossary in the AWS General Reference.
API Version 2015-09-21
45
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement