Authenticate with Azure Container Registry (ACR) from Azure Kubernetes Service (AKS)

When using Azure Container Registry (ACR) with Azure Kubernetes Service (AKS), you need to establish an authentication mechanism. You can configure the required permissions between ACR and AKS using the Azure CLI, Azure PowerShell, or Azure portal. This article provides examples to configure authentication between these Azure services using the Azure CLI or Azure PowerShell.

The AKS to ACR integration assigns the AcrPull role to the Microsoft Entra ID managed identity associated with the agent pool in your AKS cluster. For more information on AKS managed identities, see Summary of managed identities.

Important

There's a latency issue with Microsoft Entra groups when attaching ACR. If the AcrPull role is granted to a Microsoft Entra group and the kubelet identity is added to the group to complete the RBAC configuration, there may be a delay before the RBAC group takes effect. If you're running automation that requires the RBAC configuration to be complete, we recommend you use Bring your own kubelet identity as a workaround. You can pre-create a user-assigned identity, add it to the Microsoft Entra group, then use the identity as the kubelet identity to create an AKS cluster. This ensures the identity is added to the Microsoft Entra group before a token is generated by kubelet, which avoids the latency issue.

Note

This article covers automatic authentication between AKS and ACR. If you need to pull an image from a private external registry, use an image pull secret.

Before you begin

• You need the Owner, Azure account administrator, or Azure co-administrator role on your Azure subscription.
  • To avoid needing one of these roles, you can instead use an existing managed identity to authenticate ACR from AKS. For more information, see Use an Azure managed identity to authenticate to an ACR.
• If you're using Azure CLI, this article requires that you're running Azure CLI version 2.7.0 or later. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.
• If you're using Azure PowerShell, this article requires that you're running Azure PowerShell version 5.9.0 or later. Run Get-InstalledModule -Name Az to find the version. If you need to install or upgrade, see Install Azure PowerShell.
• Examples and syntax to use Terraform for configuring ACR can be found in the Terraform reference.

Create a new ACR

Azure CLI

• If you don't already have an ACR, create one using the az acr create command. The following example sets the MYACR variable to the name of the ACR, mycontainerregistry, and uses the variable to create the registry. Your ACR name must be globally unique and use only lowercase letters.

  MYACR=mycontainerregistry
  
  az acr create --name $MYACR --resource-group myContainerRegistryResourceGroup --sku basic
  

Azure PowerShell

• If you don't already have an ACR, create one using the New-AzContainerRegistry cmdlet. The following example sets the MYACR variable to the name of the ACR, mycontainerregistry, and uses the variable to create the registry. Your ACR name must be globally unique and use only lowercase letters.

  $MYACR = 'mycontainerregistry'
  
  New-AzContainerRegistry -Name $MYACR -ResourceGroupName myContainerRegistryResourceGroup -Sku Basic
  

Create a new AKS cluster and integrate with an existing ACR

Azure CLI

• Create a new AKS cluster and integrate with an existing ACR using the az aks create command with the --attach-acr parameter. This command allows you to authorize an existing ACR in your subscription and configures the appropriate AcrPull role for the managed identity.

  MYACR=mycontainerregistry
  
  az aks create --name myAKSCluster --resource-group myResourceGroup --generate-ssh-keys --attach-acr $MYACR
  

  This command may take several minutes to complete.

  Note

  If you're using an ACR located in a different subscription from your AKS cluster or would prefer to use the ACR resource ID instead of the ACR name, you can do so using the following syntax:

  az aks create -n myAKSCluster -g myResourceGroup --generate-ssh-keys --attach-acr /subscriptions/<subscription-id>/resourceGroups/myContainerRegistryResourceGroup/providers/Microsoft.ContainerRegistry/registries/myContainerRegistry
  

Azure PowerShell

• Create a new AKS cluster and integrate with an existing ACR using the New-AzAksCluster cmdlet with the -AcrNameToAttach parameter parameter. This command allows you to authorize an existing ACR in your subscription and configures the appropriate AcrPull role for the managed identity.

  $MYACR = 'mycontainerregistry'
  
  New-AzAksCluster -Name myAKSCluster -ResourceGroupName myResourceGroup -GenerateSshKey -AcrNameToAttach $MYACR
  

  This command may take several minutes to complete.

Configure ACR integration for an existing AKS cluster

Attach an ACR to an existing AKS cluster

Azure CLI

• Integrate an existing ACR with an existing AKS cluster using the az aks update command with the --attach-acr parameter and a valid value for acr-name or acr-resource-id.

  # Attach using acr-name
  az aks update --name myAKSCluster --resource-group myResourceGroup --attach-acr <acr-name>
  
  # Attach using acr-resource-id
  az aks update --name myAKSCluster --resource-group myResourceGroup --attach-acr <acr-resource-id>
  

  Note

  The az aks update --attach-acr command uses the permissions of the user running the command to create the ACR role assignment. This role is assigned to the kubelet managed identity. For more information on AKS managed identities, see Summary of managed identities.

Azure PowerShell

• Integrate an existing ACR with an existing AKS cluster using the Set-AzAksCluster command with the -AcrNameToAttach parameter and a valid value for acr-name.

  Set-AzAksCluster -Name myAKSCluster -ResourceGroupName myResourceGroup -AcrNameToAttach <acr-name>
  

  Note

  Running the Set-AzAksCluster -AcrNameToAttach cmdlet uses the permissions of the user running the command to create the role ACR assignment. This role is assigned to the kubelet managed identity. For more information on AKS managed identities, see Summary of managed identities.

Detach an ACR from an AKS cluster

Azure CLI

• Remove the integration between an ACR and an AKS cluster using the az aks update command with the --detach-acr parameter and a valid value for acr-name or acr-resource-id.

  # Detach using acr-name
  az aks update --name myAKSCluster --resource-group myResourceGroup --detach-acr <acr-name>
  
  # Detach using acr-resource-id
  az aks update --name myAKSCluster --resource-group myResourceGroup --detach-acr <acr-resource-id>
  

Azure PowerShell

• Remove the integration between an ACR and an AKS cluster using the Set-AzAksCluster command with the -AcrNameToDetach parameter and a valid value for acr-name.

  Set-AzAksCluster -Name myAKSCluster -ResourceGroupName myResourceGroup -AcrNameToDetach <acr-name>
  

Working with ACR & AKS

Import an image into your ACR

Azure CLI

• Import an image from Docker Hub into your ACR using the az acr import command.

  az acr import --name <acr-name> --source docker.io/library/nginx:latest --image nginx:v1
  

Azure PowerShell

• Import an image from Docker Hub into your ACR using the [Import-AzContainerRegistryImage] cmdlet.

  Import-AzContainerRegistryImage -RegistryName <acr-name> -ResourceGroupName myResourceGroup -SourceRegistryUri docker.io -SourceImage library/nginx:latest
  

Deploy the sample image from ACR to AKS

Azure CLI

1. Ensure you have the proper AKS credentials using the az aks get-credentials command.

   az aks get-credentials --resource-group myResourceGroup --name myAKSCluster
   

2. Create a file called acr-nginx.yaml using the following sample YAML and replace acr-name with the name of your ACR.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nginx0-deployment
     labels:
       app: nginx0-deployment
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: nginx0
     template:
       metadata:
         labels:
           app: nginx0
       spec:
         containers:
         - name: nginx
           image: <acr-name>.azurecr.io/nginx:v1
           ports:
           - containerPort: 80
   

3. Run the deployment in your AKS cluster using the kubectl apply command.

   kubectl apply -f acr-nginx.yaml
   

4. Monitor the deployment using the kubectl get pods command.

   kubectl get pods
   

   The output should show two running pods, as shown in the following example output:

   NAME                                 READY   STATUS    RESTARTS   AGE
   nginx0-deployment-669dfc4d4b-x74kr   1/1     Running   0          20s
   nginx0-deployment-669dfc4d4b-xdpd6   1/1     Running   0          20s
   

Azure PowerShell

1. Ensure you have the proper AKS credentials using the Import-AzAksCredential cmdlet.

   Import-AzAksCredential -ResourceGroupName myResourceGroup -Name myAKSCluster
   

2. Create a file called acr-nginx.yaml using the following sample YAML and replace acr-name with the name of your ACR.

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: nginx0-deployment
     labels:
       app: nginx0-deployment
   spec:
     replicas: 2
     selector:
       matchLabels:
         app: nginx0
     template:
       metadata:
         labels:
           app: nginx0
       spec:
         containers:
         - name: nginx
           image: <acr-name>.azurecr.io/nginx:v1
           ports:
           - containerPort: 80
   

3. Run the deployment in your AKS cluster using the kubectl apply command.

   kubectl apply -f acr-nginx.yaml
   

4. Monitor the deployment using the kubectl get pods command.

   kubectl get pods
   

   The output should show two running pods, as shown in the following example output:

   NAME                                 READY   STATUS    RESTARTS   AGE
   nginx0-deployment-669dfc4d4b-x74kr   1/1     Running   0          20s
   nginx0-deployment-669dfc4d4b-xdpd6   1/1     Running   0          20s
   

Configure ACR with private link through Azure HTTP Proxy and AKS

ACR has two endpoints:

• REST endpoint: {REGISTRY_NAME}.azurecr.io
• Data endpoint: {REGISTRY_NAME}.{REGISTRY_LOCATION}.data.azurecr.io

1. Ensure the rest and data endpoints are added to noProxy under the HTTP Proxy config.

{
  "httpProxy": "string",
  "httpsProxy": "string",
  "noProxy": [
    "{REGISTRY_NAME}.azurecr.io",
    "{REGISTRY_NAME}.{REGISTRY_LOCATION}.data.azurecr.io"
  ],
  "trustedCa": "string"
}

2. Verify through logs that traffic is through private link.

Note

Both endpoints are needed otherwise some traffic will be over HTTP proxy rather than private link.

Troubleshooting

• Validate the registry is accessible from the AKS cluster using the az aks check-acr command.
• Learn more about ACR monitoring.
• Learn more about ACR health.