​
Overview

The AWS ECR add-on facilitates access to Amazon ECR for managed Kubernetes clusters.

​
Supported Providers

​
Prerequisites

  • The AWS Workload Identity add-on must be enabled for your cluster.
  • For AWS providers accessing private ECR within the same account, no additional Role ARN (Amazon Resource Name) is required.
  • For non-AWS providers or when accessing an ECR in a different account, create an AWS IAM Role with the necessary permissions to pull images from a private AWS ECR. Attach the AmazonEC2ContainerRegistryReadOnly managed policy to grant these permissions. You will need the IAM Role’s ARN for configuration.

​
How to Enable

You can enable the AWS ECR add-on for your Kubernetes cluster either during the cluster creation process or at any time afterward. The following sections outline the methods for enabling the add-on:

​
At Cluster Creation

​
AWS Providers Accessing Private ECR in the Same Account

  • Through Cluster Manifest: Add the following snippet to your cluster manifest when creating the cluster:
    YAML
    spec:
  ...
  addOns:
    awsECR: {}
  ...
  • Using the Console: If you’re creating the cluster through the console, navigate to Add-ons, find the AWS ECR add-on in the list of available add-ons, and toggle it on.

​
For NON-AWS Providers or Different AWS Account Access

  • Through Cluster Manifest: Add the following snippet to your cluster manifest when creating the cluster:
    YAML
    spec:
  ...
  addOns:
    awsECR:
      roleArn: 'arn:aws:iam::999999999999:role/mk8s-ecr-driver'
  ...
  • Using the Console: If you’re creating the cluster through the console, navigate to Add-ons, find the AWS ECR add-on in the list of available add-ons, toggle it on, and then enter the ROLE ARN required for accessing the AWS ECR repository.

​
After Cluster Creation

If the AWS ECR add-on was not enabled during the cluster creation, you can still enable it using the following methods:

​
AWS Providers Accessing Private ECR in the Same Account

Using Manifest
To enable the AWS ECR add-on after cluster creation, add the following to your cluster’s YAML manifest:
  • Direct Edit & Apply: Navigate to your cluster in the Console, and use the Edit & Apply option.
  • CLI Application: Apply the entire manifest using the cpln apply >_ command or through the cpln CLI.
    YAML
    spec:
  ...
  addOns:
    awsECR: {}
  ...
  • Using the Console: If you’re creating the cluster through the console, navigate to Add-ons of your cluster, find the AWS ECR add-on in the list of available add-ons, and toggle it on.

​
For NON-AWS Providers or Different AWS Account Access

  • Through Cluster Manifest: Add the following snippet to your cluster manifest when creating the cluster:
    YAML
    spec:
  ...
  addOns:
    awsECR:
      roleArn: 'arn:aws:iam::999999999999:role/mk8s-ecr-driver'
  ...
  • Using the Console: If you’re creating the cluster through the console, navigate to Add-ons of your cluster, find the AWS ECR add-on in the list of available add-ons, toggle it on, and then enter the ROLE ARN required for accessing the AWS ECR repository.

​
Usage Instructions

​
Accessing ECR in Same AWS Account

If you are using an AWS provider to access ECR within the same AWS account, follow these steps:

​
Step 1 - Create OIDC Identity Provider in AWS (If not already done)

Skip this step if you have already created the provider as part of the AWS Workload Identity configuration.
  1. Retrieve the cluster’s oidcProviderUrl: 
    cpln mk8s get -o json $cluster_name | jq -r '.status.oidcProviderUrl'
  2. Access the AWS console and navigate to IAM. In the left panel, under Access management, select Identity providers and then click Add provider.
  3. Select OpenID Connect, paste the Provider URL obtained in the previous step, and click Get thumbprint.
  4. In the Audience field, enter sts.amazonaws.com.

​
Step 2 - Creating Kubernetes workload

Deploy a Kubernetes workload using an image from a private ECR Registry:
YAML
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-ecr
spec:
  replicas: 1
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      terminationGracePeriodSeconds: 0
      containers:
      - image: [account-id].dkr.ecr.[region].amazonaws.com/example
        name: example
        imagePullPolicy: Always
Replace [account-id] and [region] with appropriate values.

​
Accessing ECR with NON-AWS Provider or Different AWS Account

If you are using a non-AWS provider or an AWS provider to access ECR in a different AWS account, follow these steps:

​
Step 1 - Create OIDC Identity Provider in AWS (If not already done)

Skip this step if you have already created the provider as part of the AWS Workload Identity configuration.
  1. Retrieve the cluster’s oidcProviderUrl: 
    cpln mk8s get -o json $cluster_name | jq -r '.status.oidcProviderUrl'
  2. Access the AWS console and navigate to IAM. In the left panel, under Access management, select Identity providers and then click Add provider.
  3. Select OpenID Connect, paste the Provider URL obtained in the previous step, and click Get thumbprint.
  4. In the Audience field, enter sts.amazonaws.com.

​
Step 2 - Update Trust Policy

  1. Obtain the trust policy template: 
    cpln mk8s get -o json $cluster_name | jq -r '.status.addOns.awsECR.trustPolicy'
  2. Update the Trust Policy of the IAM Role in the AWS Account to reflect these changes.

​
Step 3 - Creating Kubernetes workload

Deploy a Kubernetes workload using an image from private ECR Registry. Use proper values.
YAML
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-ecr
spec:
  replicas: 1
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      terminationGracePeriodSeconds: 0
      containers:
      - image: [account-id].dkr.ecr.[region].amazonaws.com/example
        name: example
        imagePullPolicy: Always
Replace [account-id] and [region] with appropriate values.