Image Pull and Registry Operations¶

Image distribution reliability is foundational for stable deployments. This guide covers authentication, tagging, rotation, and troubleshooting for registry operations.

ACR Authentication Methods¶

Container Apps can pull images from Azure Container Registry using several methods:

Managed identity (recommended)
Best for production security posture
No long-lived credentials in configuration
Service principal
Useful for cross-tenant or constrained scenarios
Requires credential lifecycle management
Admin user (not recommended for production)
Fast setup for testing only
Broad credentials increase risk

Assign pull role for managed identity:

az role assignment create \
  --assignee-object-id "<object-id>" \
  --assignee-principal-type "ServicePrincipal" \
  --role "AcrPull" \
  --scope "/subscriptions/<subscription-id>/resourceGroups/$RG/providers/Microsoft.ContainerRegistry/registries/$ACR_NAME"

Command	Why it is used
`az role assignment create ...`	Grants the required Azure RBAC role at the documented scope.

Private ACR with VNet¶

For regulated workloads:

Use Private Endpoint for ACR.
Configure private DNS resolution in the same network boundary as Container Apps environment.
Restrict public network access for the registry.

Validate connectivity from workload subnet before enforcing deny-public rules.

Image Tagging Strategy¶

Use immutable version tags for deployment references:

Good: python-app:20260404.1, python-app:gitsha-1a2b3c4d
Avoid: relying only on latest in production

Maintain retention policy to prune stale tags while preserving rollback window.

Registry Credential Rotation¶

If using service principal credentials:

Rotate client secret on a fixed schedule.
Update Container Apps secret references before expiry.
Verify image pull after rotation and keep previous secret for rollback window.

Prefer managed identity to reduce operational rotation burden.

ACR Tasks for Automated Builds¶

ACR Tasks can build images on commit or schedule without external runners.

az acr task create \
  --registry "$ACR_NAME" \
  --name "build-python-app" \
  --context "https://github.com/yeongseon/azure-container-apps-practical-guide.git" \
  --file "apps/python/Dockerfile" \
  --image "python-app:{{.Run.ID}}" \
  --commit-trigger-enabled true

Command	Why it is used
`az acr task create ...`	Runs the Azure CLI operation required by the documented step.

Troubleshooting Image Pull Failures¶

Common causes:

Identity lacks AcrPull
Image tag does not exist
Registry firewall/private endpoint DNS misconfiguration
Secret reference mismatch when using username/password auth

Collect system logs and verify effective image reference during rollout:

az containerapp logs show \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --type system

Command	Purpose
`az containerapp logs show`	Pulls platform-generated system logs, which are where image-pull failures, registry auth errors, and revision provisioning errors are surfaced.
`--name "$APP_NAME"` / `--resource-group "$RG"`	Scopes the log collection to the app whose rollout failed so the investigation is tied to the correct revision history.
`--type system`	Chooses system logs instead of console logs because image download and registry authentication failures happen before the container process starts.

Image Pull Workflow¶

flowchart TD
    A[Deploy Revision] --> B[Container Apps requests image]
    B --> C{Registry Authentication}
    C -->|Managed identity authorized| D[Pull image manifest and layers]
    C -->|Unauthorized| E[Image pull failure]
    D --> F[Replica starts]
    E --> G[System logs + rollback action]

Registry Access Strategy Matrix¶

Method	Security Posture	Operational Overhead	Recommendation
System-assigned managed identity	Strong	Low	Preferred default
User-assigned managed identity	Strong	Medium	Use for shared identity patterns
Service principal secret	Medium	High	Use only when MI is not possible
ACR admin user	Low	Medium	Avoid in production

Validate image existence before deployment

Run a registry tag check in CI before calling az containerapp update to prevent preventable revision failures.

Network-restricted ACR requires DNS correctness

Private endpoint registry access fails if private DNS zone links are missing or stale, even when identity permissions are correct.

Registry and Image Validation Commands¶

az acr repository show-tags \
  --name "$ACR_NAME" \
  --repository "$APP_NAME" \
  --output table

az containerapp show \
  --name "$APP_NAME" \
  --resource-group "$RG" \
  --query "properties.template.containers[].image" \
  --output table

Command	Purpose
`az acr repository show-tags ...`	Lists the tags that actually exist in ACR for `$APP_NAME`, which lets the operator confirm the referenced image tag was published before blaming identity or networking.
`--repository "$APP_NAME"`	Checks the repository that matches the deployed app image naming convention in this guide, which is the most direct way to catch tag drift or missing pushes.
`az containerapp show --query "properties.template.containers[].image"`	Reads the image reference stored in the current app template so you can compare what the app is trying to pull against the tags that ACR currently exposes.
`--output table`	Formats both checks for quick side-by-side operational review during triage.

Pull Failure Triage Table¶

Log Pattern	Likely Cause	Immediate Action
`UNAUTHORIZED`	Missing `AcrPull` role or wrong identity	Verify role assignment scope and principal
`MANIFEST_UNKNOWN`	Tag does not exist in repository	Confirm image tag pushed to ACR
`dial tcp` timeout	DNS or network path issue to registry	Validate private DNS and subnet routing
`denied`	Registry firewall policy blocks request	Allow trusted network path or private endpoint