> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS ECR

> Enable Managed Kubernetes clusters to pull container images from private Amazon ECR registries.

## Overview

The AWS ECR add-on facilitates access to [Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html) for managed Kubernetes clusters.

## Supported Providers

* [AWS](../aws)
* [Hetzner](../hetzner)
* [Generic](../generic)

## Prerequisites

* The [AWS Workload Identity](/mk8s/add-ons/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 afterwards. 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 YAML theme={null}
  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 YAML theme={null}
  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](/cli-reference/overview).

  ```yaml YAML theme={null}
  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 YAML theme={null}
  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](/mk8s/add-ons/aws_workload_identity#steps-to-configure-access).

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 YAML theme={null}
---
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](/mk8s/add-ons/aws_workload_identity#steps-to-configure-access).

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 YAML theme={null}
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.