Amazon ECR
User Guide (API Version 2015-09-21)

The AWS Documentation website is getting a new look!
Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.

Amazon ECR Interface VPC Endpoints (AWS PrivateLink)

You can improve the security posture of your VPC by configuring Amazon ECR to use an interface VPC endpoint. VPC endpoints are powered by AWS PrivateLink, a technology that enables you to privately access Amazon ECR APIs through private IP addresses. AWS PrivateLink restricts all network traffic between your VPC and Amazon ECR to the Amazon network. Also, you don't need an internet gateway, a NAT device, or a virtual private gateway. For Amazon ECS tasks using the Fargate launch type, the VPC endpoint enables the task to pull private images from Amazon ECR without assigning a public IP address to the task.

For more information about AWS PrivateLink and VPC endpoints, see Accessing AWS Services Through AWS PrivateLink.

Considerations for Amazon ECR VPC Endpoints

Before you configure VPC endpoints for Amazon ECR, be aware of the following considerations:

  • To allow your Amazon ECS tasks that use the EC2 launch type to pull private images from Amazon ECR, ensure that you also create the interface VPC endpoints for Amazon ECS. For more information, see Interface VPC Endpoints (AWS PrivateLink) in the Amazon Elastic Container Service Developer Guide.

    Important

    Amazon ECS tasks that use the Fargate launch type don't require the Amazon ECS interface VPC endpoints.

  • Tasks using the Fargate launch type only require the com.amazonaws.region.ecr.dkr Amazon ECR VPC endpoint and the Amazon S3 gateway endpoint to take advantage of this feature.

  • Tasks using the Fargate launch type that pull container images from Amazon ECR can restrict access to the specific VPC their tasks use and to the VPC endpoint the service uses by adding condition keys to their task execution role. For more information, see Amazon ECS Task Execution IAM Role in the Amazon Elastic Container Service Developer Guide.

  • VPC endpoints currently don't support cross-Region requests. Ensure that you create your endpoint in the same Region where you plan to issue your API calls to Amazon ECR.

  • VPC endpoints only support Amazon provided DNS through Amazon Route 53. If you want to use your own DNS, you can use conditional DNS forwarding. For more information, see DHCP Options Sets in the Amazon VPC User Guide.

  • The security group attached to the VPC endpoint must allow incoming connections on port 443 from the private subnet of the VPC.

  • If your containers have existing connections to Amazon S3, their connections might be briefly interrupted when you add the Amazon S3 gateway endpoint. If you want to avoid this interruption, create a new VPC that uses the Amazon S3 gateway endpoint and then migrate your Amazon ECS cluster and its containers into the new VPC.

Create the VPC Endpoint for Amazon ECR

To create the VPC endpoints for the Amazon ECR service, use the Creating an Interface Endpoint procedure in the Amazon VPC User Guide.

If your Amazon ECS tasks use the EC2 launch type, both of the following endpoints are required. The order that the endpoints are created in doesn't matter. If your tasks are using the Fargate launch type, only the com.amazonaws.region.ecr.dkr endpoint is required.

com.amazonaws.region.ecr.api

Note

The specified region represents the Region identifier for an AWS Region supported by Amazon ECR, such as us-east-2 for the US East (Ohio) Region.

This endpoint is used for calls to the Amazon ECR API. API actions such as DescribeImages and CreateRepositories go to this endpoint.

When the com.amazonaws.region.ecr.api endpoint is created, you have the option to enable a private DNS hostname. Enable this hostname by selecting Enable Private DNS Name in the VPC console when you create the VPC endpoint. If you enable a private DNS hostname for the VPC endpoint, update your SDK or AWS CLI to the latest version so that specifying an endpoint URL when using the SDK or AWS CLI isn't necessary.

If you enable a private DNS hostname and are using an SDK or AWS CLI version released before January 24, 2019, you must use the --endpoint-url parameter to specify the interface endpoints. The following example CLI command shows the format of the endpoint URL.

aws ecr create-repository --repository-name name --endpoint-url https://api.ecr.region.amazonaws.com

If you don't enable a private DNS hostname for the VPC endpoint, you must use the --endpoint-url parameter specifying the VPC endpoint ID for the interface endpoint. Following is the format for the endpoint URL.

aws ecr create-repository --repository-name name --endpoint-url https://VPC_endpoint_ID.api.ecr.region.vpce.amazonaws.com
com.amazonaws.region.ecr.dkr

This endpoint is used for the Docker Registry APIs. Docker client commands such as push and pull use this endpoint.

When you create the com.amazonaws.region.ecr.dkr endpoint, you must enable a private DNS hostname. To do this, ensure that the Enable Private DNS Name option is selected in the VPC console when you create the VPC endpoint.

Create the Amazon S3 Gateway Endpoint

To pull private images from Amazon ECR, you must create a gateway endpoint for Amazon S3 for all Amazon ECS tasks. The gateway endpoint is required because Amazon ECR uses Amazon S3 to store Docker image layers. When your containers download Docker images from Amazon ECR, they must access Amazon ECR to get the image manifest and Amazon S3 to download the actual image layers. The following is the Amazon Resource Name (ARN) of the Amazon S3 bucket containing the layers for each Docker image.

arn:aws:s3:::prod-region-starport-layer-bucket/*

Use the Creating a Gateway Endpoint procedure in the Amazon VPC User Guide to create the following Amazon S3 gateway endpoint for the Amazon ECR service. When you create the endpoint, be sure to select the route tables for your VPC.

com.amazonaws.region.s3

The Amazon S3 gateway endpoint uses an IAM policy document to limit access to the service. The Full Access policy can be used because any restrictions that you have put in your task IAM roles or other IAM user policies still apply on top of this policy. If you want to limit Amazon S3 bucket access to the minimum required permissions for using Amazon ECR, see Minimum Amazon S3 Bucket Permissions for Amazon ECR.

Create the CloudWatch Logs Endpoint

For tasks using the Fargate launch type, if your VPC doesn't have an internet gateway and your tasks use the awslogs log driver to send log information to CloudWatch Logs, you must create the com.amazonaws.region.logs interface VPC endpoint for CloudWatch Logs. For more information, see Using CloudWatch Logs with Interface VPC Endpoints in the Amazon CloudWatch Logs User Guide.

Create an Endpoint Policy for your Amazon ECR VPC Endpoint

A VPC endpoint policy is an IAM resource policy that you attach to an endpoint when you create or modify the endpoint. If you don't attach a policy when you create an endpoint, AWS attaches a default policy for you that allows full access to the service. An endpoint policy doesn't override or replace IAM user policies or service-specific policies. It's a separate policy for controlling access from the endpoint to the specified service. Endpoint policies must be written in JSON format. For more information, see Controlling Access to Services with VPC Endpoints in the Amazon VPC User Guide.

We recommend creating a single IAM resource policy and attaching it to both of the Amazon ECR VPC endpoints.

The following is an example of an endpoint policy for Amazon ECR. This policy enables a specific IAM role to pull images from Amazon ECR.

{ "Statement": [{ "Sid": "AllowPull", "Principal": { "AWS": "arn:aws:iam::1234567890:role/role_name" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Effect": "Allow", "Resource": "*" }] }

The following endpoint policy example prevents a specified repository from being deleted.

{ "Statement": [{ "Sid": "AllowAll", "Principal": "*", "Action": "*", "Effect": "Allow", "Resource": "*" }, { "Sid": "PreventDelete", "Principal": "*", "Action": "ecr:DeleteRepository", "Effect": "Deny", "Resource": "arn:aws:ecr:region:1234567890:repository/repository_name" } ] }

The following endpoint policy example combines the two previous examples into a single policy.

{ "Statement": [{ "Sid": "AllowAll", "Effect": "Allow", "Principal": "*", "Action": "*", "Resource": "*" }, { "Sid": "PreventDelete", "Effect": "Deny", "Principal": "*", "Action": "ecr:DeleteRepository", "Resource": "arn:aws:ecr:region:1234567890:repository/repository_name" }, { "Sid": "AllowPull", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::1234567890:role/role_name" }, "Action": [ "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer" ], "Resource": "*" } ] }

To modify the VPC endpoint policy for Amazon ECR

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, choose Endpoints.

  3. If you have not already created the VPC endpoints for Amazon ECR, see Create the VPC Endpoint for Amazon ECR.

  4. Select the Amazon ECR VPC endpoint to add a policy to, and choose the Policy tab in the lower half of the screen.

  5. Choose Edit Policy and make the changes to the policy.

  6. Choose Save to save the policy.