Using VPC endpoint policies to control Amazon ECR access

In January 2019, AWS announced support for AWS PrivateLink on Amazon ECR. AWS PrivateLink is a networking technology designed to keep all network traffic within the AWS network. When you enable AWS PrivateLink for Amazon ECR, VPC endpoints appear as elastic network interfaces with a private IP address inside your VPC. For more details on how AWS PrivateLink works on Amazon ECR, please visit this blog post.

Since we released AWS PrivateLink support for Amazon ECR, our customers have told us that they would like the ability to control access to their Amazon ECR registries through the VPC endpoints using IAM resource policies. AWS recently announced VPC endpoint policy support for Amazon ECR to enable you to do exactly that.

Amazon ECR VPC endpoints

Before I discuss how to use policies on Amazon ECR VPC endpoints, it’s useful to understand a bit more about the specific VPC endpoints needed for Amazon ECR.

Amazon ECR needs three VPC endpoints to function correctly, as follows:

com.amazonaws.<region>.ecr.api – this VPC endpoint is used for calls to the AWS API for Amazon ECR – calls such as DescribeImages, CreateRepositories, and so on.
com.amazonaws.<region>.ecr.dkr – this VPC endpoint is used for the Docker Registry APIs. Docker client commands such as pull and push use this VPC endpoint.
com.amazonaws.<region>.s3 – because Amazon ECR uses Amazon S3 to store image layers, an S3 endpoint is required in order to download the actual container images.

Now that we understand what we need to access Amazon ECR privately from a VPC, where do VPC endpoint policies come in? With a policy in place, you have the ability to control access to the service in question through the VPC endpoint using standard IAM resource policies. For example, I might choose to allow only specific IAM roles to push or pull images to Amazon ECR through the endpoint.

Let’s look at some examples of how VPC endpoint policies can be used to solve specific issues.

Ensuring access to approved Amazon ECR registries in your AWS account

In this example, an AWS customer has a VPC where they want to run some containers, along with an Amazon ECR registry in their production AWS account. The Amazon ECR registry contains three repositories (named image1, image2, and image3). The customer also has a test AWS account with a separate Amazon ECR registry. The administrators have provisioned VPC endpoints for Amazon ECR to ensure that all connectivity happens privately, rather than via the internet. The customer’s setup is shown in the figure below:

In the above scenario, the Amazon ECR registry in the test AWS account contains images that should not be used in a production environment. The administrators would therefore like to prevent the EC2 instances in the production AWS account from being able to push and pull container images to the Amazon ECR registry in the test AWS account, as shown in the following diagram:

In the above example, no VPC endpoint policies are in place within VPC A, therefore the VPC endpoints allow access to any Amazon ECR registries – even those in other AWS accounts.

So how do VPC endpoint policies help? In this scenario, the customer can implement a policy on the Amazon ECR endpoints to prevent hosts within the customer VPC accessing an Amazon ECR registry other than ones they approve. With private registries, GetAuthorizationToken API call must be called in order to authenticate a Docker client. Currently, the GetAuthorizationToken action does not support resource-level permissions and you must specify all resources (see service authorization reference here) for ECR IAM Policy statement. Here’s how that would look:

For simplicity, it is recommended to apply the same policy to both the com.amazonaws.<region>.ecr.dkr and the com.amazonaws.<region>.ecr.api endpoints – this can be applied directly under the VPC endpoint configuration as shown here:

The policy that the customer has applied to the VPC endpoint states that only an Amazon ECR registry within the account 123456789123 can be accessed through the VPC endpoint. Attempts to access Amazon ECR registries in any other AWS accounts through the endpoint are denied, which means developers will be unsuccessful in pushing or pulling images to the test ECR registry:

denied: User: arn:aws:sts::123456789123:assumed-role/Admin-Access/i-04c4c603bb7b33708 is not authorized to perform: ecr:InitiateLayerUpload on resource: arn:aws:ecr:us-west-2:987654321987:repository/image1

Let’s look at another example of how Amazon ECR VPC endpoint policies can be used.

Use of IAM condition keys on Amazon ECR VPC endpoint policies

In this example, our AWS customer has added AWS Organizations to their environment. The customer has again set up a VPC containing some Amazon EC2 instances running Docker, as well as an Amazon ECR registry to store container images. This time, the administrators would like to ensure that the Amazon ECR registry can be accessed (e.g. pushing and pulling of container images) through the VPC endpoint only by accounts in their AWS Organization. AWS Organizations are used to centrally manage billing as well as control access, compliance, and security across AWS accounts.

In order to achieve this, the customer can implement a policy on the VPC endpoint that uses the aws:PrincipalOrgId IAM condition key, as shown in the following diagram:

The policy shown in the above illustration is once again applied to both the com.amazonaws.<region>.ecr.dkr and the com.amazonaws.<region>.ecr.api VPC endpoints. The aws:PrincipalOrgId condition key in IAM is used here to build a policy stating that requests passing through the Amazon ECR VPC endpoint will be allowed only if they come from an account residing within an AWS Organization with an ID of o-21ej9awi6a. Any requests that come from an account outside of the AWS Organization will be denied access. You can find the ID of your AWS Organization from the AWS CLI using aws organizations describe-organization.

Preventing Amazon ECR repositories from being deleted

So far, we have seen how policies can be applied to VPC endpoints for Amazon ECR to provide greater control of access to the Docker registry APIs. But what if the customer wanted to also control access to the AWS APIs for Amazon ECR? Let’s look at an example where a customer wants to prevent users from deleting a specific repository when accessing the Amazon ECR registry through the VPC endpoint:

In this scenario, the customer would like to prevent the deletion of the image3 repository (shown in red) by anyone accessing Amazon ECR through the VPC endpoint. To achieve this, the customer can use a final VPC endpoint policy as follows:

{
    "Statement": [
        {
            "Action": "",
            "Resource": "arn:aws:ecr:us-west-2:123456789123:repository/*",
            "Effect": "Allow",
            "Principal": "",
            "Condition": {
                "StringEquals": {
                    "aws:PrincipalOrgID": [
                        "o-21ej9awi6a"
                    ]
                }
            }
        },
        {
            "Action": "ecr:DeleteRepository",
            "Effect": "Deny",
            "Principal": "",
            "Resource": "arn:aws:ecr:us-west-2:123456789123:repository/base-image3"
        }
    ]
}

The above policy builds upon the examples shown in the previous sections. It continues to allow calls to the Amazon ECR registry as long as those calls come from the AWS Organization with an ID of o-21ej9awi6a. The second half of the policy adds to this by stating that ecr:DeleteRepository calls to the specific Amazon ECR repository arn:aws:ecr:us-west-2:123456789123:repository/base-image3 will be denied.

Again, this policy is applied to both the com.amazonaws.<region>.ecr.dkr and the com.amazonaws.<region>.ecr.api VPC endpoints. By doing so, it is possible to maintain a single policy for both Docker registry APIs (push images, pull images, etc) as well as AWS APIs (create and delete repositories, etc).

Conclusion

In this post, I showed how VPC endpoint policies can be used to control access to Amazon ECR registries. VPC endpoint policies can be used to control access to both the Docker APIs (e.g. Docker push & pull) as well as AWS APIs (create repository and delete repository).

As always, AWS welcomes feedback. Please submit comments or questions below.

Containers