Authenticate with Azure Container Registry (ACR) from Azure Kubernetes Service (AKS)
Article
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.
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.
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.
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
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.
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
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.
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.
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.
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>
The source for this content can be found on GitHub, where you can also create and review issues and pull requests. For more information, see our contributor guide.
Azure Kubernetes Service feedback
Azure Kubernetes Service is an open source project. Select a link to provide feedback:
Learn how to create and configure an Azure Container Registry, the process of pushing container images to Azure Container Registry and explore different authentication methods and security features for Azure Container Registry.