ACR Integration with AKS

Why this matters

You already build images and push them to Azure Container Registry from the Docker track. Now you need AKS to be able to pull those private images to run them as Pods. Getting the authentication wrong here is one of the most common real-world AKS failures (ImagePullBackOff), so this module covers the correct managed-identity approach first, and the fallback approach second.

Concepts

Why a private registry needs authentication for pulls. A registry like Docker Hub's public library needs no auth; your own ACR registry is private by default. Every node's kubelet needs some credential to pull from it, or every Pod referencing your private image sits in ImagePullBackOff.

The modern way: az aks update --attach-acr. AKS clusters run with a managed identity (an Azure AD identity Azure manages the credentials for, with no secrets for you to store or rotate). Attaching an ACR to a cluster grants that cluster's identity the AcrPull role on the registry, scoped just to pulling images — no image pull secret, no credential to expire, no YAML to maintain. This is the recommended approach whenever the ACR and the AKS cluster are reachable under role-assignment permissions you control (almost always true for a single subscription you own, which is your situation in this track).

The fallback: Kubernetes imagePullSecrets. Before managed-identity attachment existed (and still today for some cross-tenant/cross-subscription scenarios where you can't or don't want to grant a role assignment), you authenticate the old way: create a Docker-registry-type Secret holding ACR credentials, and reference it in a Pod/Deployment's imagePullSecrets. This works everywhere but means a credential exists that can expire or leak, and must be kept in sync per-namespace.

What AKS manages vs. what you own here: attaching ACR is a one-time role assignment Azure manages afterward (rotation, propagation to all nodes) — you don't touch node-level Docker/containerd credential files yourself, unlike the fallback secret approach where you own the secret's lifecycle (creation, rotation, revocation) directly.

Command reference

Hands-on exercises

1. Create an ACR registry (skip if you already have one from the Docker track you'd like to reuse — registry names must be globally unique): az acr create --resource-group rg-aks-learn --name acraskslearn --sku Basic. Verify: az acr list --output table shows it with Basic SKU.

2. Build and push an image to it. Using any small app from earlier tracks (or a trivial Dockerfile with a one-line web server), build, then authenticate and push:

   az acr login --name acraskslearn
   docker tag demo-app:latest acraskslearn.azurecr.io/demo-app:v1
   docker push acraskslearn.azurecr.io/demo-app:v1
   

   Verify: az acr repository list --name acraskslearn --output table shows demo-app.

3. Try deploying it to AKS before attaching ACR (deliberately, to see the failure). Write a Deployment referencing acraskslearn.azurecr.io/demo-app:v1 and kubectl apply -f it. Verify: kubectl get pods shows the pod stuck in ImagePullBackOff or ErrImagePull.

4. Diagnose it properly. Run kubectl describe pod <name> and read the Events section — you should see a message like unauthorized: authentication required or 401 Unauthorized pulling from the ACR login server. This is the exact real-world symptom of a missing AcrPull role assignment — confirm there's no role assignment yet: az role assignment list --scope $(az acr show --name acraskslearn --query id -o tsv) --output table (should be empty or missing an AcrPull entry for your cluster's identity).

5. Fix it with --attach-acr. Run az aks update --resource-group rg-aks-learn --name aks-learn --attach-acr acraskslearn. This can take a minute to propagate. Verify: re-run the role assignment list command from exercise 4 — you should now see an AcrPull entry. Then delete and recreate the pod (or just wait — the kubelet retries pulls with backoff): kubectl delete pod <name> (a Deployment will recreate it), and confirm with kubectl get pods that it reaches Running.

6. Try the fallback method for comparison. Enable the ACR admin user temporarily to get credentials for a demo (az acr update --name acraskslearn --admin-enabled true, then az acr credential show --name acraskslearn), then create an imagePullSecret:

   kubectl create secret docker-registry acr-secret \
     --docker-server=acraskslearn.azurecr.io \
     --docker-username=<username-from-credential-show> \
     --docker-password=<password-from-credential-show>
   

   Reference imagePullSecrets: [{name: acr-secret}] in a new test Deployment (leave your --attach-acr-based Deployment as-is), apply it, and verify it also pulls successfully. Afterward, turn the admin user back off (az acr update --name acraskslearn --admin-enabled false) since it's a weaker, shared credential you don't want lingering — the managed-identity approach from exercise 5 doesn't need it at all, which is why it's preferred.

7. Confirm which nodes/pods use which method. Run kubectl get pods -o yaml | grep -A2 imagePullSecrets — note that only the fallback Deployment's pods reference a secret; the --attach-acr based Deployment's pods have no imagePullSecrets at all, because authentication happens transparently via the cluster's managed identity at the node/kubelet level.

8. Clean up. Delete the test Deployment and secret from exercise 6: kubectl delete deployment <fallback-deployment-name> and kubectl delete secret acr-secret. Leave the --attach-acr based Deployment if you're continuing to module 04, or kubectl delete namespace demo if you created one and are done for now. ACR registries on the Basic SKU are inexpensive but not free — if you don't need the registry beyond this track, remove it later with az acr delete --name acraskslearn --resource-group rg-aks-learn --yes, or let the eventual az group delete for rg-aks-learn take care of it along with the cluster.

Independent challenge

No commands given here — figure it out yourself using what you know from this module and earlier ones.

Task: Prove to yourself that you can turn an ImagePullBackOff into a running pod using only the managed-identity path, and that you understand exactly which grant fixed it. Build and push a trivial private image to an ACR, then deploy it to your cluster (reusing the namespace-and-Deployment workflow from module 02, conceptually building on that module) so that it fails to pull — and confirm from the pod's own events that the failure is an authentication one, not a missing-image typo. Then make the cluster able to pull it without creating any Kubernetes secret, and independently verify at the Azure level that the specific role you granted now exists on the registry. As a final check, reason about why none of your pods reference an imagePullSecrets field even though the pull now works. Clean up the test Deployment when done, and remember the ACR and cluster both keep billing until you remove them.

Common mistakes & troubleshooting

• Confusing az acr login (your local Docker CLI's auth, for pushing) with cluster-to-registry auth (for pulling). They're unrelated — logging in locally does nothing for the cluster's ability to pull.
• Attaching the wrong ACR or forgetting the registry name is globally unique. az acr create fails immediately if the name is taken; double-check az acr list output before assuming attachment failed for a permissions reason instead.
• Not waiting for propagation. --attach-acr role assignment can take up to a minute or so to be usable; if a pod created immediately after still fails, wait and retry (kubectl delete pod to force a fresh pull attempt) before assuming the attach didn't work.
• Leaving the ACR admin user enabled after a fallback-secret demo. The admin account is a single shared credential with full pull/push rights — leaving it on is a standing security exposure with no corresponding benefit once you've moved to managed-identity auth.
• Cost pitfall: creating multiple ACR registries "just to try things" and forgetting about them. Even Basic-tier ACR has a small ongoing cost plus storage cost per image layer. Reuse one registry per track rather than creating a new one per exercise, and delete ones you're not using.

Checkpoint quiz

Write down your answer to each question before expanding it — checking without attempting first is the single easiest way to fool yourself into thinking you've learned this.

1. Why does a private ACR registry need explicit authentication for AKS to pull from it, unlike a public registry?
2. What role does az aks update --attach-acr actually grant, and to whom?
3. What's the concrete symptom in kubectl describe pod output when a pull fails due to missing authentication, versus a pull failure from a typo'd image name?
4. Why is --attach-acr preferred over imagePullSecrets when both the ACR and AKS cluster are in a subscription you control?
5. When might you still need imagePullSecrets instead of --attach-acr?
6. What Kubernetes Secret type does kubectl create secret docker-registry produce, and where does a Pod reference it?

Cumulative review

Closed-book. Don't reopen earlier modules while attempting these — the point is to find out what actually stuck.

1. You run kubectl get pods and see one pod Pending and another in ImagePullBackOff. Explain what each state means, which module's material each traces back to, and why the very first command you run to diagnose both is the same one.
2. Trace the full billing story of a single learning cluster from nothing: which az command first creates something billable, which resource groups end up existing (name the second, AKS-managed one), and which single command tears down the cluster, its nodes, and an attached ACR all at once.
3. You created a resource group, a cluster, and an ACR, but a teammate says your pods "obviously can't pull the image." Without looking at any pod yet, what one Azure-level thing would you check to confirm or rule out their claim, and what role name are you looking for?
4. Why does a Deployment that ran fine on kind fail to fully schedule on your two-node Standard_B2s cluster, and how does that same node-capacity reality connect to why you keep the cluster small in the first place (cost)?
5. Distinguish az acr login from az aks update --attach-acr: which one affects your ability to push an image, which affects the cluster's ability to pull it, and why does succeeding at one tell you nothing about the other?
6. You have both a local kind context and your aks-learn context in the same kubeconfig. Give the command to confirm which one is active, and explain why this habit matters more now than it did in the pure-local Kubernetes track.
7. An empty resource group, a stopped cluster (az aks stop), and a deleted resource group (az group delete) each have different cost and recoverability implications. Rank them from "cheapest but gone" to "still there and may still bill," and say which you'd pick between study sessions.
8. Put these in the correct order for going from zero to a running private image on AKS, and name the module each step comes from: attach ACR to the cluster; create the cluster; push the image to ACR; create the resource group; kubectl apply the Deployment; az aks get-credentials.
9. The managed-identity ACR pull and the fallback imagePullSecrets approach both make a private pull work. For a single subscription you own, why is the managed-identity path preferred, and what lingering security exposure does the fallback demo tell you to switch back off afterward?
10. If you switched to the wrong Azure subscription midway through these modules and re-ran az group list, why might your cluster's resource group appear to have "vanished," and what single command reorients you before you panic?

Next

04-aks-networking-loadbalancer-and-ingress — expose your workloads to the internet with real public IPs and Ingress.