Amazon ECR

This tutorial will guide you on how to use your private Elastic Container Registry (ECR) with Okteto. It's recommended that you have the AWS CLI installed to follow this tutorial.

ECR credentials can be configured with either static credentials belonging to an IAM user or using OIDC federation to assume an IAM Role via Web Identity.

Using IAM User credentials

The steps to configure your private ECR with Okteto are:

• Create a user with access to your private ECR
• Retrieve the user credentials
• Configure the credentials in Okteto

Step 1: Create a user with access to your private ECR

Create IAM user with the AWS CLI by executing:

aws iam create-user --user-name private-registry-user

aws iam attach-user-policy \
  --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly \
  --user-name private-registry-user

Step 2: Retrieve the user credentials

Once we have the User created, we need to retrieve their credentials. Create IAM user access key with the AWS CLI by executing:

aws iam create-access-key --user-name private-registry-user

{
    "AccessKey": {
        "UserName": "private-registry-user",
        "AccessKeyId": "<<your-access-key>>",
        "Status": "Active",
        "SecretAccessKey": "<<your-password>>",
        "CreateDate": "2023-10-10T09:08:27+00:00"
    }
}

Remember the value of AccessKeyId and SecretAccessKey. You will need them in the next step.

Step 3: Configure the credentials in Okteto

Add the following registry credentials to the Admin Registry Credentials view:

• Type: AWS IAM User
• Hostname: the default registry endpoint is https://{AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com
• Username: AccessKeyId from the previous step
• Password: SecretAccessKey from the previous step

Using OIDC Federation

Step 1: Create the Identity Provider

OIDC_ENDPOINT=https://container.googleapis.com/v1/projects/my-project-12345/locations/us-central1/clusters/development
AUDIENCE=registry.okteto.dev
aws iam create-open-id-connect-provider --url "${OIDC_ENDPOINT}" --client-id-list "${AUDIENCE}"
{
    "OpenIDConnectProviderArn": "arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/my-project-12345/locations/us-central1/clusters/development"
}

Okteto displays the OIDC endpoint of your cluster in the admin general view:

Traditionally, AUDIENCE is the client id of the requester. You'll only exchange token for these audiences. It is the aud field of the JWT payload.

We recommend creating a different/dedicated audience for each okteto cluster and region used even if you use the same identity provider:

your-okteto-instance.com/112233445566.dkr.ecr.your-region.amazonaws.com

or the more compact format:

your-okteto-instance.com/your-region

Step 2: Create the Role

First create the role and allow it to access EC2:

# ROLE_ARN is the OpenIDConnectProviderArn role name created in step 1
ROLE_ARN=arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/my-project-12345/locations/us-central1/clusters/development
AUDIENCE=registry.okteto.dev
OKTETO_SERVICE_ACCOUNT=system:serviceaccount:okteto:okteto
cat <<EOT > trust-policy.json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "${ROLE_ARN}"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "container.googleapis.com/v1/projects/my-project-12345/locations/us-central1/clusters/development:aud": "${AUDIENCE}",
          "container.googleapis.com/v1/projects/my-project-12345/locations/us-central1/clusters/development:sub": "${OKTETO_SERVICE_ACCOUNT}"
        }
      }
    }
  ]
}
EOT

aws iam create-role --role-name my-private-registry --assume-role-policy-document file://trust-policy.json
{
    "Role": {
        "Path": "/",
        "RoleName": "my-private-registry",
        "RoleId": "AR...",
        "Arn": "arn:aws:iam::112233445566:role/my-private-registry",
        "CreateDate": "2024-06-10T15:04:05+00:00",
        "AssumeRolePolicyDocument": {
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Principal": {
                        "Service": "ec2.amazonaws.com"
                    },
                    "Action": "sts:AssumeRole"
                }
            ]
        }
    }
}

Attach an EC2 Container Registry policy that allows you to pull and push from the registry:

aws iam attach-role-policy --role-name my-private-registry --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryPowerUser

If you only need read access you can use AmazonEC2ContainerRegistryReadOnly instead.

Step 3: Configure the credentials in Okteto

Add the following registry credentials to the Admin Registry Credentials view:

• Type: AWS IAM Role
• Hostname: The ECR registry endpoint is https://{AWS_ACCOUNT_ID}.dkr.ecr.{REGION}.amazonaws.com
• Role ARN: The Role ARN from the previous step
• Audience: The Audience used for the Identity Provider