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.
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.
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 --versionto 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 Azto 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
If you don't already have an ACR, create one using the
az acr createcommand. The following example sets the
MYACRvariable 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 -n $MYACR -g myContainerRegistryResourceGroup --sku basic
Create a new AKS cluster and integrate with an existing ACR
Create a new AKS cluster and integrate with an existing ACR using the
az aks createcommand with the
--attach-acrparameter. 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 -n myAKSCluster -g myResourceGroup --generate-ssh-keys --attach-acr $MYACR
This command may take several minutes to complete.
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
Configure ACR integration for an existing AKS cluster
Attach an ACR to an existing AKS cluster
# Attach using acr-name az aks update -n myAKSCluster -g myResourceGroup --attach-acr <acr-name> # Attach using acr-resource-id az aks update -n myAKSCluster -g myResourceGroup --attach-acr <acr-resource-id>
Detach an ACR from an AKS cluster
# Detach using acr-name az aks update -n myAKSCluster -g myResourceGroup --detach-acr <acr-name> # Detach using acr-resource-id az aks update -n myAKSCluster -g myResourceGroup --detach-acr <acr-resource-id>
Working with ACR & AKS
Import an image into your ACR
Import an image from Docker Hub into your ACR using the
az acr importcommand.
az acr import -n <acr-name> --source docker.io/library/nginx:latest --image nginx:v1
Deploy the sample image from ACR to AKS
Ensure you have the proper AKS credentials using the
az aks get-credentialscommand.
az aks get-credentials -g myResourceGroup -n myAKSCluster
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
Run the deployment in your AKS cluster using the
kubectl apply -f acr-nginx.yaml
Monitor the deployment using the
kubectl get podscommand.
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