Using Amazon ECR Images with Amazon EKS - Amazon ECR
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Using Amazon ECR Images with Amazon EKS

You can use your Amazon ECR images with Amazon EKS, but you need to satisfy the following prerequisites.

  • For Amazon EKS workloads hosted on managed or self-managed nodes, the Amazon EKS worker node IAM role (NodeInstanceRole) is required. The Amazon EKS worker node IAM role must contain the following IAM policy permissions for Amazon ECR.

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ecr:BatchCheckLayerAvailability", "ecr:BatchGetImage", "ecr:GetDownloadUrlForLayer", "ecr:GetAuthorizationToken" ], "Resource": "*" } ] }

    If you used eksctl or the Amazon CloudFormation templates in Getting Started with Amazon EKS to create your cluster and worker node groups, these IAM permissions are applied to your worker node IAM role by default.

  • For Amazon EKS workloads hosted on Amazon Fargate, you must use the Fargate pod execution role, which provides your pods permission to pull images from private Amazon ECR repositories. For more information, see Create a Fargate pod execution role.

  • When referencing an image from Amazon ECR, you must use the full registry/repository:tag naming for the image. For example,

Installing a Helm chart hosted on Amazon ECR with Amazon EKS

Your Helm charts hosted in Amazon ECR can be installed on your Amazon EKS clusters. The following steps demonstrate this.


Before you begin, ensure the following steps have been completed.

  • Install the latest version of the Helm client. These steps were written using Helm version 3.7.0. For more information, see Installing Helm.

  • You have pushed a Helm chart to your Amazon ECR repository. For more information, see Pushing a Helm chart.

  • You have configured kubectl to work with Amazon EKS. For more information, see Create a kubeconfig for Amazon EKS in the Amazon EKS User Guide. If the following commands succeeds for your cluster, you're properly configured.

    kubectl get svc

Install an Amazon ECR hosted Helm chart to an Amazon EKS cluster

  1. Currently, OCI support is considered experimental. In order to use the commands in these steps, you must enable OCI support in the Helm client.

  2. Authenticate your Helm client to the Amazon ECR registry that your Helm chart is hosted. Authentication tokens must be obtained for each registry used, and the tokens are valid for 12 hours. For more information, see Private registry authentication.

    aws ecr get-login-password \ --region us-west-2 | helm registry login \ --username AWS \ --password-stdin
  3. Pull your Helm chart to your local cache.

    helm pull oci:// --version 0.1.0
  4. Install the chart.

    helm install ecr-chart-demo ./helm-test-chart

    The output should look similar to this:

    NAME: ecr-chart-demo
    LAST DEPLOYED: Thu Sep 23 16:41:53 2021
    NAMESPACE: default
    STATUS: deployed
    TEST SUITE: None
  5. Verify the chart installation. The output will be a YAML representation of the Kubernetes resources deployed by the chart.

    helm get manifest ecr-chart-demo
  6. (Optional) See the installed Helm chart configmap.

    kubectl get configmap helm-test-chart-configmap
  7. When you are finished, you can remove the chart release from your cluster.

    helm uninstall ecr-chart-demo