Using VPC endpoint policies to control HAQM ECR access

In January 2019, AWS announced support for AWS PrivateLink on HAQM ECR. AWS PrivateLink is a networking technology designed to keep all network traffic within the AWS network. When you enable AWS PrivateLink for HAQM 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 HAQM ECR, please visit this blog post.

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

HAQM ECR VPC endpoints

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

HAQM 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 HAQM 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 HAQM ECR uses HAQM 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 HAQM 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 HAQM 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 HAQM 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 HAQM ECR registry in their production AWS account. The HAQM ECR registry contains three repositories (named image1, image2, and image3). The customer also has a test AWS account with a separate HAQM ECR registry. The administrators have provisioned VPC endpoints for HAQM 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 HAQM 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 HAQM 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 HAQM 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 HAQM ECR endpoints to prevent hosts within the customer VPC accessing an HAQM 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 HAQM ECR registry within the account 123456789123 can be accessed through the VPC endpoint. Attempts to access HAQM 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 HAQM ECR VPC endpoint policies can be used.

Use of IAM condition keys on HAQM 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 HAQM EC2 instances running Docker, as well as an HAQM ECR registry to store container images. This time, the administrators would like to ensure that the HAQM 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 HAQM 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 HAQM ECR repositories from being deleted

So far, we have seen how policies can be applied to VPC endpoints for HAQM 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 HAQM ECR? Let’s look at an example where a customer wants to prevent users from deleting a specific repository when accessing the HAQM 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 HAQM 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 HAQM 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 HAQM 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 HAQM 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.