ACR Integration & Image Management

# Cloud build — no Docker needed on your machine
az acr build \
  --registry myacr \
  --image myapp:v1.2.3 \
  --image myapp:latest \
  --file ./Dockerfile \
  .

# The build context (.) is uploaded to ACR
# ACR runs the Docker build on Azure-hosted compute
# Final image is stored in myacr.azurecr.io/myapp:v1.2.3

# Create an ACR Task that builds on every commit to 'main'
az acr task create \
  --registry myacr \
  --name build-myapp \
  --image myapp:{{.Run.ID}} \
  --context https://github.com/myorg/myapp.git#main \
  --file Dockerfile \
  --git-access-token $GITHUB_PAT \
  --commit-trigger-enabled true \
  --base-image-trigger-enabled true

# This triggers a build when:
# 1. Code is pushed to 'main' branch
# 2. The base image (e.g., node:20-alpine) is updated in Docker Hub

# Set retention policy — auto-delete untagged manifests after 7 days
az acr config retention update \
  --registry myacr \
  --status enabled \
  --days 7 \
  --type UntaggedManifests

# Manually purge old images — keep only the last 10 tags
az acr run \
  --registry myacr \
  --cmd "acr purge --filter 'myapp:.*' --ago 30d --keep 10 --untagged" \
  /dev/null

# Add replicas to West Europe and Southeast Asia
az acr replication create --registry myacr --location westeurope
az acr replication create --registry myacr --location southeastasia

# Verify replications
az acr replication list --registry myacr -o table
# NAME            LOCATION         STATUS
# eastus          eastus           Ready
# westeurope      westeurope       Ready
# southeastasia   southeastasia    Ready

# Push a Helm chart to ACR as an OCI artifact
helm push mychart-0.1.0.tgz oci://myacr.azurecr.io/helm

# Install directly from ACR
helm install myrelease oci://myacr.azurecr.io/helm/mychart --version 0.1.0

# Import NGINX from Docker Hub into ACR
az acr import \
  --name myacr \
  --source docker.io/library/nginx:1.27-alpine \
  --image nginx:1.27-alpine

# Import from another ACR (cross-subscription)
az acr import \
  --name myacr \
  --source otheracr.azurecr.io/myapp:latest \
  --image myapp:latest

# Create a Standard SKU ACR
az acr create \
  --resource-group myResourceGroup \
  --name myacr2025 \
  --sku Standard \
  --location eastus

# Verify creation
az acr show --name myacr2025 --query "{name:name, sku:sku.name, loginServer:loginServer}" -o table
# Name        Sku       LoginServer
# ----------  --------  -----------------------
# myacr2025   Standard  myacr2025.azurecr.io

# Attach ACR to AKS using managed identity (best practice)
az aks update \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --attach-acr myacr2025

# Verify the attachment — check that AcrPull role is assigned
az role assignment list \
  --scope $(az acr show -n myacr2025 --query id -o tsv) \
  --query "[?roleDefinitionName=='AcrPull'].{principal:principalName, role:roleDefinitionName}" \
  -o table

# Principal                              Role
# -------------------------------------  --------
# abc12345-xxxx-xxxx-xxxx-xxxxxxxxxxxx   AcrPull

# Create a simple app to build
mkdir myapp && cd myapp

cat > Dockerfile <<'EOF'
FROM node:20-alpine
WORKDIR /app
COPY package.json .
RUN npm install --production
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
EOF

cat > server.js <<'EOF'
const http = require('http');
const server = http.createServer((req, res) => {
  res.writeHead(200, {'Content-Type': 'application/json'});
  res.end(JSON.stringify({status: 'healthy', version: 'v1.0.0'}));
});
server.listen(3000, () => console.log('Server running on port 3000'));
EOF

cat > package.json <<'EOF'
{"name":"myapp","version":"1.0.0","main":"server.js"}
EOF

# Build in the cloud — no Docker Desktop needed
az acr build \
  --registry myacr2025 \
  --image myapp:v1.0.0 \
  --image myapp:latest \
  .

# Verify the image exists in ACR
az acr repository show-tags --name myacr2025 --repository myapp -o table
# Result
# --------
# latest
# v1.0.0

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      containers:
        - name: myapp
          image: myacr2025.azurecr.io/myapp:v1.0.0
          ports:
            - containerPort: 3000
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 250m
              memory: 256Mi

kubectl apply -f deployment.yaml

# Verify pods are running and pulled the image successfully
kubectl get pods -l app=myapp
# NAME                     READY   STATUS    RESTARTS   AGE
# myapp-6f8b4d5c9-2kj7x   1/1     Running   0          12s
# myapp-6f8b4d5c9-8mn3p   1/1     Running   0          12s
# myapp-6f8b4d5c9-q4r5t   1/1     Running   0          12s

# Check the image used by a pod
kubectl describe pod myapp-6f8b4d5c9-2kj7x | Select-String "Image:"
#   Image:         myacr2025.azurecr.io/myapp:v1.0.0

# Check events for ImagePull success
kubectl get events --field-selector reason=Pulled --sort-by='.lastTimestamp'
# Successfully pulled image "myacr2025.azurecr.io/myapp:v1.0.0" in 1.2s

# Test the running application
kubectl port-forward deployment/myapp 3000:3000 &
curl http://localhost:3000
# {"status":"healthy","version":"v1.0.0"}

# Step 1: Check the exact error
kubectl describe pod myapp-xxxx
# Events:
#   Warning  Failed  kubelet  Failed to pull image "myacr2025.azurecr.io/myapp:v1.0.0":
#   unauthorized: authentication required, visit https://aka.ms/acr/authorization

# Step 2: Verify AKS-ACR attachment
az aks check-acr \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --acr myacr2025.azurecr.io
# If this fails, the attachment is broken

# Step 3: Check if AcrPull role assignment exists
ACR_ID=$(az acr show -n myacr2025 --query id -o tsv)
KUBELET_ID=$(az aks show -g myResourceGroup -n myAKSCluster \
  --query "identityProfile.kubeletidentity.objectId" -o tsv)

az role assignment list --scope $ACR_ID --assignee $KUBELET_ID -o table

# Step 4: If role assignment is missing, re-attach
az aks update \
  --resource-group myResourceGroup \
  --name myAKSCluster \
  --attach-acr myacr2025

# Step 5: If using private ACR, verify the private endpoint is reachable
# from the AKS nodes (VNet peering, DNS resolution)
kubectl run acr-test --image=busybox:1.36 --rm -it --restart=Never -- \
  nslookup myacr2025.azurecr.io
# Should resolve to a private IP (10.x.x.x), not a public IP

# Step 6: After fixing, delete the failing pod to trigger a fresh pull
kubectl delete pod myapp-xxxx

# Step 1: Verify the exact image name and tag in ACR
az acr repository list --name myacr2025 -o table
# Result
# ------
# myapp
# nginx

az acr repository show-tags --name myacr2025 --repository myapp -o table
# Result
# --------
# latest
# v1.0.0
# (v2.0.0 is NOT listed — the image was never pushed)

# Step 2: Check for typos in the deployment spec
kubectl get deployment myapp -o jsonpath='{.spec.template.spec.containers[0].image}'
# myacr2025.azurecr.io/myapp:v2.0.0  ← This tag doesn't exist

# Step 3: Common mistakes to check:
# - Wrong registry name (myacr vs myacr2025)
# - Wrong repository name (my-app vs myapp)
# - Tag was overwritten by retention policy
# - Image was pushed to a different ACR

# Step 4: Fix the image tag
kubectl set image deployment/myapp myapp=myacr2025.azurecr.io/myapp:v1.0.0

# Step 5: If the tag was deleted by retention, rebuild
az acr build --registry myacr2025 --image myapp:v2.0.0 .

# Step 1: Check the build log output — az acr build streams logs
# Common errors:

# ERROR: "unable to prepare context: unable to evaluate symlinks"
# → The build context (.) doesn't contain the Dockerfile
# Fix: Specify the correct path
az acr build --registry myacr2025 --image myapp:v1 --file ./src/Dockerfile ./src

# ERROR: "COPY failed: file not found in build context"
# → The file referenced in COPY doesn't exist in the uploaded context
# Fix: Ensure your .dockerignore isn't excluding needed files
cat .dockerignore  # Check for overly broad exclude patterns

# ERROR: "failed to fetch anonymous token: 403 Forbidden"
# → ACR public access is disabled and you're running from outside the VNet
# Fix: Use a self-hosted agent inside the VNet, or temporarily enable public access
az acr update --name myacr2025 --public-network-enabled true

# Step 2: Check past build runs
az acr task list-runs --registry myacr2025 -o table --top 5
# RUN ID    TASK           STATUS    TRIGGER    STARTED
# -------   ----           -------   -------    -------
# cb15      build-myapp    Failed    Manual     2025-04-20T10:30:00Z

# Step 3: Get detailed logs for a specific run
az acr task logs --registry myacr2025 --run-id cb15

# Step 4: Validate Dockerfile locally before cloud build
# (if Docker is available)
docker build --no-cache -t test:local .