Skip to main content
Version: 1.22

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:

OIDC configuration in 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:

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": "arn:aws:iam::112233445566:oidc-provider/container.googleapis.com/v1/projects/my-project-12345/locations/us-central1/clusters/development"
      },
      "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