Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
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.
az --version
to find the version. If you need to install or upgrade, see Install Azure CLI.Get-InstalledModule -Name Az
to find the version. If you need to install or upgrade, see Install Azure PowerShell.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
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
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.
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>
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
Ensure you have the proper AKS credentials using the az aks get-credentials
command.
az aks get-credentials --resource-group myResourceGroup --name 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
command.
kubectl apply -f acr-nginx.yaml
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
az aks check-acr
command.Azure Kubernetes Service feedback
Azure Kubernetes Service is an open source project. Select a link to provide feedback:
Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Configure Azure Container Registry for container app deployments - Training
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.
Certification
Microsoft Certified: Azure Administrator Associate - Certifications
Demonstrate key skills to configure, manage, secure, and administer key professional functions in Microsoft Azure.