Skip to main content
Version: 1.51

Okteto Registry with Azure Storage Container

The Okteto Registry can store your container images in an Azure Storage container.

The Okteto Registry authenticates to your storage account with either a storage account access key or Microsoft Entra Workload ID.

warning

Starting with Okteto 1.50, the Okteto Registry no longer finds the images pushed with earlier versions (distribution#4278). They aren't deleted, so they keep using space in your storage container. Before upgrading, see the upgrade guide to start with a new storage container or keep specific images.

Storage account access key​

In this guide, <<storage-account-access-key>> refers to a storage account access key with read/write permissions to the storage container you want to use for the Okteto Registry.

Create a secret with the value of <<storage-account-access-key>> using the command below:

kubectl create secret generic okteto-registry-secret --namespace=okteto --from-literal=secretKey=<<storage-account-access-key>>

Then, add the following configuration to your Okteto Helm configuration file:

config.yaml
registry:
  storage:
    provider:
      azure:
        enabled: true
        storage:
          container: <<your-storage-container-name>>
          accountName: <<your-storage-account-name>>

Microsoft Entra Workload ID​

On AKS, the Okteto Registry can authenticate with Microsoft Entra Workload ID instead of a storage account access key. Set the following environment variables:

export RESOURCE_GROUP="<<your-resource-group>>"
export AKS_CLUSTER="<<your-aks-cluster-name>>"
export STORAGE_ACCOUNT="<<your-storage-account-name>>"

Your AKS cluster needs the OIDC issuer and workload identity enabled:

az aks update --resource-group "${RESOURCE_GROUP}" --name "${AKS_CLUSTER}" --enable-oidc-issuer --enable-workload-identity

Create a user-assigned managed identity for the Okteto Registry:

az identity create --resource-group "${RESOURCE_GROUP}" --name okteto-registry
export IDENTITY_CLIENT_ID="$(az identity show --resource-group "${RESOURCE_GROUP}" --name okteto-registry --query clientId --output tsv)"
export IDENTITY_PRINCIPAL_ID="$(az identity show --resource-group "${RESOURCE_GROUP}" --name okteto-registry --query principalId --output tsv)"

Grant the identity the Storage Blob Data Contributor role on your storage account. Assign it on the storage account, not on the container: the Okteto Registry also requests a user delegation key to sign the URLs it redirects image pulls to.

az role assignment create \
  --assignee-object-id "${IDENTITY_PRINCIPAL_ID}" \
  --assignee-principal-type ServicePrincipal \
  --role "Storage Blob Data Contributor" \
  --scope "$(az storage account show --name "${STORAGE_ACCOUNT}" --query id --output tsv)"

Get the Okteto Registry service account name and federate it with the identity:

export OKTETO_REGISTRY_SERVICE_ACCOUNT_NAME="$(kubectl get sa -n=okteto -l=app.kubernetes.io/component=registry -o=jsonpath='{.items[0].metadata.name}')"
export AKS_OIDC_ISSUER="$(az aks show --resource-group "${RESOURCE_GROUP}" --name "${AKS_CLUSTER}" --query oidcIssuerProfile.issuerUrl --output tsv)"

az identity federated-credential create \
  --resource-group "${RESOURCE_GROUP}" \
  --identity-name okteto-registry \
  --name okteto-registry \
  --issuer "${AKS_OIDC_ISSUER}" \
  --subject "system:serviceaccount:okteto:${OKTETO_REGISTRY_SERVICE_ACCOUNT_NAME}" \
  --audiences api://AzureADTokenExchange

Then, add the following configuration to your Okteto Helm configuration file. The okteto-registry-secret secret isn't needed:

config.yaml
registry:
  storage:
    provider:
      azure:
        enabled: true
        storage:
          container: <<your-storage-container-name>>
          accountName: <<your-storage-account-name>>
        workloadIdentity:
          enabled: true
  serviceAccount:
    annotations:
      azure.workload.identity/client-id: <<your-identity-client-id>>

Network access​

With either authentication method, clients that pull images, such as your Kubernetes nodes, the Okteto Build Service, and developer machines, download image layers directly from your storage account (<<your-storage-account-name>>.blob.core.windows.net), so they need network access to it.

Upgrading your Okteto instance​

Finally, upgrade your Okteto instance for the new configuration to be applied. We recommend that you upgrade to the same version that you already have to minimize the changes and help you troubleshoot any issues.