Amazon EC2 Container Registry (ECR) with Kubernetes

For information about how to pull from other private registries, see the following topics:

If you choose ECR as your private registry, we recommend that you run your cluster on AWS. The following information documents only this scenario.

Note:If you create your cluster by using the Quick Start for Kubernetes by Heptio, the appropriate policies and roles are created as part of the cluster. Solutions such as Kubernetes Operations (kops), kube-aws, and others also configure the necessary policies and roles automatically. You provide the following information manually only if you create a custom Kubernetes solution.

ECR with AWS managed IAM policy

The simplest approach is to use the managed IAM policy that AWS provides: AmazonEC2ContainerRegistryReadOnly.

First, find the IAM role for each node in your cluster. Your nodes can share a single role, or you can assign different roles to different nodes or sets of nodes.

Warning:Make sure to attach the appropriate role to each instance before you start the instance. You cannot attach a role to a running instance. You can, however, modify a role that is already attached to an instance.

Then run the following command for each role:


aws iam attach-role-policy \
  --role-name "$ROLENAME" \
  --policy-arn "arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly"

ECR roles and policies defined in Kubernetes configuration

Or you can create the IAM policy, attach the policy to the appropriate role, and attach the role to the node instances in your Kubernetes configuration file.

Here’s how to define the role in a CloudFormation template written in YAML:

# IAM role for nodes
  Type: AWS::IAM::Role
      Version: '2012-10-17'
      - Effect: Allow
        - sts:AssumeRole
    Path: "/"
    # IAM policy for nodes that allows specific AWS resource listing and creation
    - PolicyName: node
        Version: '2012-10-17'
        - Effect: Allow
          # we do need all the following permissions for the registry
          - ecr:GetAuthorizationToken
          - ecr:BatchCheckLayerAvailability
          - ecr:GetDownloadUrlForLayer
          - ecr:GetRepositoryPolicy
          - ecr:DescribeRepositories
          - ecr:ListImages
          - ecr:BatchGetImage
          Resource: "*"

After the IAM role is attached to the node, the kubelet on the node takes care of fetching and refreshing ECR credentials.