Uredi

Authenticate with Azure Container Registry from Azure Kubernetes Service

  • Članak

When using Azure Container Registry (ACR) with Azure Kubernetes Service (AKS), you need to establish an authentication mechanism. Configuring the required permissions between ACR and AKS can be accomplished using the Azure CLI, Azure PowerShell, and 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 Azure Active Directory (Azure AD) 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 is a latency issue with Azure Active Directory groups when attaching ACR. If the AcrPull role is granted to an Azure AD 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 are running automation that requires the RBAC configuration to be complete, we recommended you use the Bring your own kubelet identity as a workaround. You can pre-create a user-assigned identity, add it to the Azure AD group, then use the identity as the kubelet identity to create an AKS cluster. This ensures the identity is added to the Azure AD 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 to have the Owner, Azure account administrator, or Azure co-administrator role on your Azure subscription.
  • 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 AKS cluster with ACR integration

You can set up AKS and ACR integration during the creation of your AKS cluster. To allow an AKS cluster to interact with ACR, an Azure AD managed identity is used.

Create an ACR

If you don't already have an ACR, create one using the following command.

# Set this variable to the name of your ACR. The name must be globally unique.

MYACR=myContainerRegistry

az acr create -n $MYACR -g myContainerRegistryResourceGroup --sku basic

Create a new AKS cluster and integrate with an existing ACR

If you already have an ACR, use the following command to create a new AKS cluster with ACR integration. This command allows you to authorize an existing ACR in your subscription and configures the appropriate AcrPull role for the managed identity. Supply valid values for your parameters below.

# Set this variable to the name of your ACR. The name must be globally unique.

MYACR=myContainerRegistry

# Create an AKS cluster with ACR integration.

az aks create -n myAKSCluster -g myResourceGroup --generate-ssh-keys --attach-acr $MYACR

Alternatively, you can specify the ACR name using an ACR resource ID using the following format:

/subscriptions/\<subscription-id\>/resourceGroups/\<resource-group-name\>/providers/Microsoft.ContainerRegistry/registries/\<name\>

Note

If you're using an ACR located in a different subscription from your AKS cluster, use the ACR resource ID when attaching or detaching from the cluster.

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

This command may take several minutes to complete.

Configure ACR integration for existing AKS clusters

Attach an ACR to an AKS cluster

Integrate an existing ACR with an existing AKS cluster using the --attach-acr parameter and valid values for acr-name or acr-resource-id.

# 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>

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.

Detach an ACR from an AKS cluster

Remove the integration between an ACR and an AKS cluster using the --detach-acr parameter and valid values for acr-name or acr-resource-id.

# 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

Run the following command to import an image from Docker Hub into your ACR.

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.

az aks get-credentials -g myResourceGroup -n myAKSCluster

Create a file called acr-nginx.yaml using the sample YAML below. 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

After creating the file, run the following deployment in your AKS cluster.

kubectl apply -f acr-nginx.yaml

You can monitor the deployment by running kubectl get pods.

kubectl get pods

The output should show two running pods.

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

Troubleshooting