Use a User-Assigned Managed Identity for ACR Image Pull¶

Configure an existing Container App to pull images from Azure Container Registry using a user-assigned managed identity (UAMI). This approach eliminates long-lived credentials and provides explicit principal separation for role assignments.

flowchart TD
    App[Container App] --> RegistryConfig[Registry configuration]
    RegistryConfig --> UAMI[User-assigned managed identity]
    UAMI --> AcrPull[AcrPull role assignment]
    AcrPull --> ACR[Azure Container Registry]
    ACR --> Image[Container image pull]

Prerequisites¶

• Azure CLI 2.62+ with the containerapp extension
• An existing Container App
• An Azure Container Registry with the target image
• Permissions to create managed identities and role assignments in the subscription

When to Use¶

• Migrating from admin credentials or service principal to managed identity
• Reconnecting Continuous Deployment after RBAC conflicts
• Separating image pull identity from application identity (system-assigned)
• Establishing a dedicated principal for ACR access auditing

Procedure¶

Step 1: Create a User-Assigned Managed Identity¶

az identity create \
  --resource-group $RG \
  --name "${APP_NAME}-uami" \
  --location $LOCATION

Note the id (resource ID) and principalId from the output — both are needed in later steps.

Step 2: Assign the UAMI to the Container App¶

UAMI_ID=$(az identity show \
  --resource-group $RG \
  --name "${APP_NAME}-uami" \
  --query id \
  --output tsv)

az containerapp identity assign \
  --resource-group $RG \
  --name $APP_NAME \
  --user-assigned "$UAMI_ID"

Step 3: Grant AcrPull Role on the Registry¶

UAMI_PRINCIPAL=$(az identity show \
  --resource-group $RG \
  --name "${APP_NAME}-uami" \
  --query principalId \
  --output tsv)

ACR_ID=$(az acr show \
  --name $ACR_NAME \
  --resource-group $RG \
  --query id \
  --output tsv)

az role assignment create \
  --assignee-object-id "$UAMI_PRINCIPAL" \
  --assignee-principal-type ServicePrincipal \
  --role AcrPull \
  --scope "$ACR_ID"

Step 4: Configure the Container App Registry to Use the UAMI¶

az containerapp registry set \
  --resource-group $RG \
  --name $APP_NAME \
  --server "${ACR_NAME}.azurecr.io" \
  --identity "$UAMI_ID"

This tells Container Apps to use the specified UAMI when pulling images from this registry. Without this step, simply having AcrPull on the identity is not sufficient.

Step 5: Update the Container Image to Pull from ACR¶

az containerapp update \
  --resource-group $RG \
  --name $APP_NAME \
  --image "${ACR_NAME}.azurecr.io/${IMAGE_NAME}:${TAG}"

Verification¶

Confirm the app is running with the ACR image:

az containerapp show \
  --resource-group $RG \
  --name $APP_NAME \
  --query "{image:properties.template.containers[0].image, registries:properties.configuration.registries, provisioningState:properties.provisioningState}" \
  --output json

Expected output shows:

• image pointing to your ACR
• registries[0].identity set to the UAMI resource ID
• provisioningState is Succeeded

Reconnect Continuous Deployment (Optional)¶

If you are reconnecting Portal-based Continuous Deployment (Deployment Center) after this change:

1. Remove any previous GitHub Actions workflow or secrets that referenced old credentials.
2. In the Azure Portal, navigate to the Container App → Continuous Deployment.
3. Re-run the connection wizard. The new UAMI with AcrPull is now the active pull identity.

Rollback / Troubleshooting¶

For detailed diagnosis, see the Image Pull Failure playbook and Image Pull and Auth Errors KQL queries.

Clean Up¶

To remove the demo resources:

az group delete --name $RG --yes --no-wait

See Also¶

• Image Pull and Registry Operations
• Managed Identity (Platform Concepts)
• CD RBAC Role Assignment Conflict Playbook
• CD Reconnect RBAC Conflict Lab

Sources¶

• Use managed identity for image pull — Microsoft Learn
• Managed identities in Azure Container Apps — Microsoft Learn
• AcrPull built-in role — Microsoft Learn