Frequently asked questions - Azure Container Registry

Yes. Here is a template that you can use to create a registry.

Yes. You can use Microsoft Defender for Containers or other solutions, such as Aqua.

See the documentation for Kubernetes and steps for Azure Kubernetes Service.

To get admin credentials, the registry's admin user must be enabled.

To get admin credentials using the Azure CLI, run the following command:

az acr credential show -n myRegistry

To get admin credentials using Azure PowerShell, run the following command:

Invoke-AzureRmResourceAction -Action listCredentials -ResourceType Microsoft.ContainerRegistry/registries -ResourceGroupName myResourceGroup -ResourceName myRegistry

To get admin credentials in a Resource Manager template, run the following command to get the first password:

{
    "password": "[listCredentials(resourceId('Microsoft.ContainerRegistry/registries', 'myRegistry'), '2025-04-01').passwords[0].value]"
}

Then, to get the second password, run the following command:

{
    "password": "[listCredentials(resourceId('Microsoft.ContainerRegistry/registries', 'myRegistry'), '2025-04-01').passwords[1].value]"
}

To get admin credentials using the Azure portal, go to the registry and in the service menu, under Settings, select Access keys.

The following Azure built-policies, can be used to prevent users from enabling admin user on registries:

This error occurs when you have the Container Registry Contributor and Data Access Configuration Administrator role on a registry—allowing replica deletion through Azure CLI—but you don't have the Reader role on the subscription. To resolve this issue, assign the Reader role to the user at the subscription scope.

It might take some time to propagate firewall rule changes. After you change firewall settings, wait for a few minutes before verifying the change.

Move to a newer version of the ACR API. You can find a list of supported versions here.

If you consume an API via SDKs, move to a newer API version by updating to a newer version of the SDK. You can find a list of SDKs and their latest versions here.

The following API versions have been deprecated and are supported as of the "Support end date" listed below:

ACR supports Docker Registry HTTP API V2. The APIs can be accessed at https://<your registry login server>/v2/. Example: https://mycontainerregistry.azurecr.cn/v2/

For Bash, run the following command:

az acr manifest list-metadata --name myRepository --registry myRegistry --query "[?tags[0]==null].digest" --output tsv  | xargs -I% az acr repository delete --name myRegistry --image myRepository@%

For PowerShell, run the following command:

az acr manifest list-metadata --name myRepository --repository myRegistry --query "[?tags[0]==null].digest" --output tsv | %{ az acr repository delete --name myRegistry --image myRepository@$_ }

For more information, see Delete container images in Azure Container Registry.

This situation occurs when the underlying layers are still being referenced by other container images. If you delete an image with no references, the registry usage should update within a few minutes.

Create an image with a 1 GB layer using the following docker file. This step ensures that the image has a layer that isn't shared with any other image in the registry.

FROM alpine
RUN dd if=/dev/urandom of=1GB.bin  bs=32M  count=32
RUN ls -lh 1GB.bin

Build and push the image to your registry using the docker CLI:

docker build -t myregistry.azurecr.cn/1gb:latest .
docker push myregistry.azurecr.cn/1gb:latest

You should be able to see that the storage usage has increased in the Azure portal, or you can query usage using the Azure CLI:

az acr show-usage -n myregistry

Next, delete the image by using the Azure CLI or in the Azure portal, wait a few minutes, and then check the updated usage.

az acr repository delete -n myregistry --image 1gb

You need to run the Azure CLI container by mounting the Docker socket:

docker run -it -v /var/run/docker.sock:/var/run/docker.sock azuresdk/azure-cli-python:dev

In the container, install docker:

apk --update add docker

Then authenticate with your registry:

az acr login -n MyRegistry

Currently, you can use trusted images in Azure Container Registry with Docker Content Trust (DCT). However, Azure Container Registry will retire DCT on March 31, 2028.

As an alternative to DCT, Azure offers signing and verification solutions based on Notary Project. We encourage you to transition from DCT to Notary Project as soon as possible.

Until May 31, 2026, Docker Content Trust can be enabled on new container registries or registries that haven't enabled it previously. For details, see Manage signed images by using Docker Content Trust in Azure Container Registry.

The file for the thumbprint is located under ~/.docker/trust/private/tuf/myregistry.azurecr.cn/myrepository/metadata:

• Public keys and certificates of all roles (except delegation roles) are stored in the root.json.
• Public keys and certificates of the delegation role are stored in the JSON file of its parent role (for example targets.json for the targets/releases role).

Verify the public keys and certificates after the overall TUF verification done by the Docker and Notary client.

ACR supports Microsoft Entra role-based access control (RBAC) and built-in roles that provide different levels of Azure Entra-based permissions, such as granting image push or pull permissions without granting permissions to the entire registry.

You can optionally use Microsoft Entra attribute-based access control (ABAC) to manage Microsoft Entra-based repository permissions and scope role assignments to specific repositories.

Image quarantine is currently a preview feature of ACR. The quarantine mode of a registry can be enabled so that only images that pass security scans are visible to normal users. For details, see the ACR GitHub repo.

You can configure anonymous pull access by using the Azure CLI. For more information, see unauthenticated anonymous pull access.

A nondistributable layer in a manifest contains a URL parameter that content may be fetched from. Some possible use cases for enabling nondistributable layer pushes are for network restricted registries, air-gapped registries with restricted access, or for registries with no internet connectivity.

For example, if you have Network Security Group (NSG) rules set up so that a VM can pull images only from your Azure container registry, Docker might encounter failures when pulling foreign or nondistributable layers. For example, a Windows Server Core image would contain foreign layer references to Azure container registry in its manifest and would fail to pull in this scenario.

To enable pushing of nondistributable layers:

1. Edit the daemon.json file, which is located in /etc/docker/ on Linux hosts and at C:\ProgramData\docker\config\daemon.json on Windows Server. Assuming the file was previously empty, add the following contents:

   {
     "allow-nondistributable-artifacts": ["myregistry.azurecr.cn"]
   }
   

   Note

   The value is an array of registry addresses, separated by commas.

2. Save and exit the file.

3. Restart Docker.

When you push images to the registries in the list, their nondistributable layers are pushed to the registry.

You can use az acr check-health to troubleshoot common environment and registry issues, see Check the health of an Azure container registry.

You may see the error net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers). To resolve this issue:

• First, wait a few minutes and try again. This issue could be transient.
• If docker pull fails continuously, try restarting the Docker daemon.
• If you continue to see this issue after restarting Docker daemon, it could be due to a network connectivity issue. Run the following command to test endpoint connectivity:

az acr check-health -n myRegistry

• You should always have a retry mechanism on all Docker client operations.

This is usually due to the machine being on a slow network. Check your network download speed. To improve speed, consider using an Azure Virtual Machine (VM) in the same region as your registry to improve network speed.

First, make sure you use an all lowercase server URL, for example, docker push myregistry.azurecr.cn/myimage:latest, even if the registry resource name is uppercase or mixed case, like myRegistry.

This error can also happen with the Red Hat version of the Docker daemon, where --signature-verification is enabled by default. You can check the Docker daemon options for Red Hat Enterprise Linux (RHEL) or Fedora by running the following command:

grep OPTIONS /etc/sysconfig/docker

For instance, Fedora 28 Server has the following docker daemon options:

OPTIONS='--selinux-enabled --log-driver=journald --live-restore'

With --signature-verification=false missing, docker pull fails with an error similar to:

Trying to pull repository myregistry.azurecr.cn/myimage ...
unauthorized: authentication required

To resolve the error:

1. Add the option --signature-verification=false to the Docker daemon configuration file /etc/sysconfig/docker. For example:

   OPTIONS='--selinux-enabled --log-driver=journald --live-restore --signature-verification=false'

2. Restart the Docker daemon service by running the following command:

   sudo systemctl restart docker.service
   

Details of --signature-verification can be found by running man dockerd.

Start dockerd with the debug option. First, create the Docker daemon configuration file (/etc/docker/daemon.json) if it doesn't exist, and add the debug option:

{    
    "debug": true    
}

Then, restart the daemon.

sudo service docker restart

Details can be found in the Docker documentation.

• The logs may be generated at different locations, depending on your system. For specific information, see the Docker documentation.

• For Docker for Windows, the logs are generated under %LOCALAPPDATA%/docker/. However, in order to access the full daemon log, you might need to run these additional commands:

  docker run --privileged -it --rm -v /var/run/docker.sock:/var/run/docker.sock -v /usr/local/bin/docker:/usr/local/bin/docker alpine sh
  
  docker run --net=host --ipc=host --uts=host --pid=host -it --security-opt=seccomp=unconfined --privileged --rm -v /:/host alpine /bin/sh
  chroot /host
  

  Now you have access to all the files of the VM running dockerd. The log is at /var/log/docker.log.

Microsoft Entra role assignments usually happen quickly, but there can be occasional delays. You might also experience a permission delay of up to 10 minutes on the ACR token server. To mitigate, run docker logout, wait one minute, and then authenticate again with the same user credentials:

docker logout myregistry.azurecr.cn
docker login myregistry.azurecr.cn

Currently, ACR doesn't support home replication deletion by users. Instead, you can include the home replication create in the template, but skip its creation by adding "condition": false:

{
    "name": "[concat(parameters('acrName'), '/', parameters('location'))]",
    "condition": false,
    "type": "Microsoft.ContainerRegistry/registries/replications",
    "apiVersion": "2025-04-01",
    "location": "[parameters('location')]",
    "properties": {},
    "dependsOn": [
        "[concat('Microsoft.ContainerRegistry/registries/', parameters('acrName'))]"
     ]
},

You may encounter an InvalidAuthenticationInfo error, especially using the curl tool with the option -L, --location (to follow redirects). For example, you might fetch the blob using curl with -L option and basic authentication:

curl -L -H "Authorization: basic $credential" https://$registry.azurecr.cn/v2/$repository/blobs/$digest

This could result in the following response:

<?xml version="1.0" encoding="utf-8"?>
<Error><Code>InvalidAuthenticationInfo</Code><Message>Authentication information is not given in the correct format. Check the value of Authorization header.
RequestId:00000000-0000-0000-0000-000000000000
Time:2023-01-01T00:00:00.0000000Z</Message></Error>

The root cause is that some curl implementations follow redirects with headers from the original request.

To resolve the problem, follow redirects manually without the headers. Print the response headers with the -D - option of curl and then extract: the Location header:

REDIRECT_URL=$(curl -s -D - -H "Authorization: basic $credential" https://$registry.azurecr.cn/v2/$repository/blobs/$digest | grep "^Location: " | cut -d " " -f2 | tr -d '\r')
curl $REDIRECT_URL

Failures to send fetch requests can be caused by various reasons, such as:

• Lack of network connectivity
• Firewall
• Using the portal from a public network for a registry that allows only private access
• Ad blockers
• Domain Name Server (DNS) errors

Contact your network administrator or check your network configuration and connectivity. Try running az acr check-health -n yourRegistry to check if your environment is able to connect to the registry. You can also try using an incognito or private session in your browser to avoid any stale browser cache or cookies.

Here are some scenarios where operations may be disallowed:

• Classic registries are no longer supported. Upgrade to a supported service tier using az acr update or the Azure portal.
• The image or repository maybe locked so that it can't be deleted or updated. You can use the az acr repository show command to view current attributes.
• Some operations are disallowed if the image is in quarantine.
• Your registry may have reached its storage limit.

If you see an error such as "unsupported repository format," "invalid format," or "the requested data does not exist" when specifying a repository name in repository operations, check the spelling and case of the name. Valid repository names can only include lowercase alphanumeric characters, periods, dashes, underscores, and forward slashes.

First, enable decrypting HTTPS in Fiddler and enable Docker to use a proxy via the Docker UI. Be sure to revert after you finish, as Docker doesn't work with the proxy enabled and Fiddler not running.

For Windows containers, configure Docker proxy to 127.0.0.1:8888.

For Linux containers, find the ip of the Docker vm virtual switch:

(Get-NetIPAddress -InterfaceAlias "*Docker*" -AddressFamily IPv4).IPAddress

Then, configure the Docker proxy to output of the previous command and the port 8888 (for example 10.0.75.1:8888).

The following commands cancel all running tasks in the specified registry.

az acr task list-runs -r $myregistry --run-status Running --query '[].runId' -o tsv \
| xargs -I% az acr task cancel-run -r $myregistry --run-id %

If you pass a local source folder to the az acr build command, the .git folder is excluded from the uploaded package by default. You can create a .dockerignore file with the following setting:

!.git/**

This setting tells the command to restore all files under .git in the uploaded package. It also applies to the az acr run command.

We currently don't support GitLab for Source triggers.

You might see an error saying that no access was configured, so no subscriptions were found when using az login --identity in your ACR Task. This error is generally transient and occurs when the role assignment of your managed identity isn't propagated yet. Wait a few seconds before retrying.

You can find sample CI/CD integration with ACR Tasks in the following links:

• CircleCI
• GitHub Actions

Next steps

• Learn more about Azure Container Registry.