Container Registry

Introduction

Azure Container Registry (ACR) is a managed, private OCI-compatible registry for storing container images and Helm charts. It integrates natively with Azure Kubernetes Service, Azure Container Instances, and Azure App Service to streamline container-based application deployments. ACR is commonly used to build, store, and manage container images as part of a continuous integration and deployment pipeline. For more information, see What is Azure Container Registry?.

LocalStack for Azure provides a local environment for building and testing applications that make use of Azure Container Registry. The supported APIs are available on our API Coverage section, which provides information on the extent of Container Registry’s integration with LocalStack.

Getting started

This guide walks you through creating a registry, logging in with Docker, pushing an image, and listing repositories.

Launch LocalStack using your preferred method. For more information, see Introduction to LocalStack for Azure. Once the container is running, enable Azure CLI interception by running:

azlocal start-interception

This command points the az CLI away from the public Azure management REST API and toward the LocalStack for Azure emulator API. To revert this configuration, run:

azlocal stop-interception

This reconfigures the az CLI to send commands to the official Azure management REST API.

Create a resource group

Create a resource group to hold all resources created in this guide:

az group create --name rg-acr-demo --location westeurope

Output

{
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-acr-demo",
  "location": "eastus",
  "name": "rg-acr-demo",
  "properties": { "provisioningState": "Succeeded" },
  "type": "Microsoft.Resources/resourceGroups"
}

Create a container registry

Create a Standard-tier Azure Container Registry:

az acr create \
  --name myacrdemo \
  --resource-group rg-acr-demo \
  --sku Basic \
  --admin-enabled true

Output

{
  "adminUserEnabled": true,
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-acr-demo/providers/Microsoft.ContainerRegistry/registries/myacrdemo",
  "location": "eastus",
  "loginServer": "myacrdemo.azurecr.azure.localhost.localstack.cloud:4566",
  "name": "myacrdemo",
  "provisioningState": "Succeeded",
  "resourceGroup": "rg-acr-demo",
  "sku": { "name": "Basic", "tier": "Basic" },
  "type": "Microsoft.ContainerRegistry/registries"
...
}

Log in with Docker

Authenticate the local Docker daemon to the registry using the Azure CLI:

az acr login --name myacrdemo

The emulator does not issue an AAD challenge, so the CLI prints an informational warning before confirming Login Succeeded. This is expected behaviour.

Build and push an image

Create a minimal Dockerfile for the demo image:

cat > Dockerfile <<'EOF'
FROM alpine:latest
CMD ["echo", "Hello from LocalStack ACR!"]
EOF

Capture the registry login server returned by the emulator, then build and push the image using that address:

LOGIN_SERVER=$(az acr show --name myacrdemo --resource-group rg-acr-demo --query loginServer -o tsv)
docker build -t $LOGIN_SERVER/hello:v1 .
docker push $LOGIN_SERVER/hello:v1

Alternatively build directly within the emulated registry:

az acr build \
  --image hello:v1 \
  --registry myacrdemo \
  .

Pull an image

Pull the image back from the registry to confirm it was pushed correctly:

docker pull $LOGIN_SERVER/hello:v1

List repositories

List all image repositories stored in the registry:

az acr repository list --name myacrdemo

Output

[
  "hello"
]

Check name availability

Check that the registry name is globally available before creating:

az acr check-name --name myacrdemo

Output

{
  "message": "The registry myacrdemo is already in use.",
  "nameAvailable": false,
  "reason": "AlreadyExists"
}

Update registry settings

Enable the admin user account on the registry:

az acr update --name myacrdemo --resource-group rg-acr-demo --admin-enabled false

Output

{
  "adminUserEnabled": false,
  "id": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/rg-acr-demo/providers/Microsoft.ContainerRegistry/registries/myacrdemo",
  "loginServer": "myacrdemo.azurecr.azure.localhost.localstack.cloud:4566",
  "name": "myacrdemo",
  "provisioningState": "Succeeded",
  "resourceGroup": "rg-acr-demo",
  "sku": { "name": "Basic", "tier": "Basic" },
  "type": "Microsoft.ContainerRegistry/registries"
...
}

Show registry usage

Show current storage usage statistics for the registry:

az acr show-usage --name myacrdemo --resource-group rg-acr-demo

Output

{
  "value": [
    { "currentValue": 0, "limit": 10737418240, "name": "Size", "unit": "Bytes" },
    { "currentValue": 0, "limit": 2, "name": "Webhooks", "unit": "Count" },
    { "currentValue": 0, "limit": 100, "name": "ScopeMaps", "unit": "Count" },
    { "currentValue": 0, "limit": 100, "name": "Tokens", "unit": "Count" }
  ]
}

Delete and verify

Delete the registry and remove the demo Dockerfile created earlier:

az acr delete --name myacrdemo --resource-group rg-acr-demo --yes
rm -f Dockerfile

Features

• Full CRUD lifecycle: Create, read, update, and delete registry resources using the Azure CLI or ARM API.
• Admin user management: Enable or disable admin user access and retrieve admin credentials.
• Name availability check: Validate registry name uniqueness via az acr check-name.
• Image push and pull: Push and pull OCI-compliant container images using the standard Docker CLI.
• In-registry builds: Build images directly in the emulated registry using az acr build.
• Repository listing: List repositories and image tags stored in the registry.
• Registry usage reporting: Retrieve storage and limit usage via az acr show-usage.
• Registry update: Modify registry properties such as admin enabled and SKU.
• Multiple SKUs accepted: Basic, Standard, and Premium SKU names are accepted (all backed by the same local registry).

Limitations

• Geo-replication not supported: Multi-region registry replication is not emulated.
• ACR Tasks beyond basic build: Task scheduling, triggers, and multi-step task workflows are mocked at the ARM level but not executed.
• Private endpoints for ACR: Private Link–based network isolation is not supported.
• Webhook notifications: Registry webhooks defined via the ARM API are stored but not fired on push events.
• Content trust and quarantine: Image signing and quarantine policies are not enforced.
• Delete is not persisted: az acr delete returns HTTP 200 and exits cleanly, but the registry record is not removed from the in-memory store in the current emulator version.

Samples

The following sample demonstrates how to use Azure Container Registry with LocalStack for Azure:

• Azure Container Instances, Key Vault, and Storage

API Coverage

Operation ▲	Implemented ▼

PreviousPage 1 of 0Next