diff --git a/src/content/admin/registry-credentials/amazon-ecr.mdx b/src/content/admin/registry-credentials/amazon-ecr.mdx
index 9e93b8019..f95dc8e5d 100644
--- a/src/content/admin/registry-credentials/amazon-ecr.mdx
+++ b/src/content/admin/registry-credentials/amazon-ecr.mdx
@@ -8,6 +8,10 @@ id: 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](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) 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
@@ -55,7 +59,117 @@ Remember the value of `AccessKeyId` and `SecretAccessKey`. You will need them in
Add the following registry credentials to the [Admin Registry Credentials view](index.mdx#add-registry-credentials):
-- **Type**: `AWS`
+- **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
+
+```bash
+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:
+
+```bash
+# 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 < 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:
+
+```bash
+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](index.mdx#add-registry-credentials):
+
+- **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
diff --git a/src/content/admin/registry-credentials/index.mdx b/src/content/admin/registry-credentials/index.mdx
index 79f416a9a..37e4c5792 100644
--- a/src/content/admin/registry-credentials/index.mdx
+++ b/src/content/admin/registry-credentials/index.mdx
@@ -22,7 +22,7 @@ Registry credentials are applied to the [Okteto Build service](core/build-servic
## Add Registry Credentials
Click in the **Add Credential** button on the top right corner of the Registry Credentials view.
-A dialog will let you choose the type of credentials (Static or AWS), your registry hostname, and your username and password:
+A dialog will let you choose the type of credentials, your registry hostname, and your username and password:
-`Static` credentials use a username and password, ideal for platforms like DockerHub.
-`AWS` credentials are for Amazon Elastic Container Registry (ECR) and requirean Access Key and a Secret Key, with Okteto refreshing credentials every 4 hours.
+There are three types of registries that can be configured in Okteto:
+
+- **Static** - credentials use a username and password, ideal for platforms like DockerHub.
+- **AWS IAM User** - Provides credentials for Amazon Elastic Container Registry (ECR) using an Access Key and a Secret Key. Okteto will exchange an ECR temporary token with AWS using these credentials.
+- **AWS IAM Role** - Provides credentials for Amazon Elastic Container Registry (ECR) using a predefined AWS IAM Role. Okteto will exchange an ECR temporary token with AWS using [OIDC federation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html)
+
Follow our guides below to learn how to retrieve your registry credentials:
- [Amazon ECR](admin/registry-credentials/amazon-ecr.mdx)
diff --git a/static/img/amazon-ecr-oidc-config.png b/static/img/amazon-ecr-oidc-config.png
new file mode 100644
index 000000000..e3b51c539
Binary files /dev/null and b/static/img/amazon-ecr-oidc-config.png differ