Quickstart: Create an Azure container registry using the Azure portal

Azure Container Registry is a private registry service for building, storing, and managing container images and related artifacts. In this quickstart, you create an Azure container registry instance with the Azure portal. Then, use Docker commands to push a container image into the registry, and finally pull and run the image from your registry.

You must also have Docker installed locally with the daemon running. Docker provides packages that easily configure Docker on any Mac, Windows, or Linux system.

Sign in to Azure

Sign in to the Azure portal.

Create a container registry

Select Create a resource > Containers > Container Registry.

Configure container registry name and SKU

In the Basics tab, enter values for Resource group and Registry name. The registry name must be unique within Azure, and contain 5-50 alphanumeric characters, with dash characters (-) not allowed in the registry name. For this quickstart create a new resource group in the West US 2 location named myResourceGroup, and for SKU, select Standard.

For more information about different SKU options, see Azure Container Registry SKUs.

Configure Domain Name Label (DNL) option

The Domain Name Label (DNL) feature strengthens security by preventing subdomain takeover attacks of registry DNS names. These attacks occur when a registry is deleted, and another entity reuses the same registry name, potentially causing downstream references to pull from the registry re-created by the other entity.

DNL addresses this by appending a unique hash to the registry's DNS name. This ensures that even if the same registry name is reused by another entity, the DNS names will differ due to the unique hash. This safeguards your downstream references from inadvertently pointing to the registry re-created by the other entity.

When creating a registry from the Portal, select the Domain Name Label Scope from the available options:

• Unsecure: Creates the DNS name as-is, based on the registry name (e.g., contosoacrregistry.azurecr.io). This option does not include DNL protection.
• Tenant Reuse: Appends a unique hash based on the tenant and registry name, ensuring the DNS name is unique within the tenant.
• Subscription Reuse: Appends a unique hash based on the subscription, tenant, and registry name, ensuring the DNS name is unique within the subscription.
• Resource Group Reuse: Appends a unique hash based on the resource group, subscription, tenant, and registry name, ensuring the DNS name is unique within the resource group.
• No Reuse: Generates a unique DNS name with a unique hash every time the registry is created, regardless of other factors, ensuring the DNS name is always unique.

DNS Name Implications of DNL options

DNS Name Format: For all DNL-enabled options except Unsecure, the DNS name follows the format registryname-hash.azurecr.io, where the dash (-) serves as the hash delineator. To avoid conflicts, dash (-) is not permitted in the registry name. For instance, a registry named contosoacrregistry with the Tenant Reuse DNL scope will have a DNS name like contosoacrregistry-e7ggejfuhzhgedc8.azurecr.io.

Downstream References: The DNS name may differ from the registry name, necessitating updates in downstream files such as Dockerfiles, Kubernetes YAML, and Helm charts to reflect the full DNS name with the DNL hash. For example, if you want your downstream Dockerfile to reference a registry named contosoacrregistry with the Tenant Reuse DNL scope, you would need to update the reference to contosoacrregistry-e7ggejfuhzhgedc8.azurecr.io in your downstream Dockerfile.

Configure role assignment permissions mode

Configure the "Role assignment permissions mode" of the new registry. This option determines how Microsoft Entra role-based access control (RBAC) and role assignments are managed for the registry, including the use of Microsoft Entra attribute-based access control (ABAC) for Microsoft Entra repository permissions.

Choose "RBAC Registry + ABAC Repository Permissions" to retain standard Microsoft Entra RBAC role assignments, while optionally applying Microsoft Entra ABAC conditions for fine‑grained, repository‑level access control.

For more information on this option, see Microsoft Entra attribute-based access control (ABAC) for repository permissions.

Deploying the container registry

Accept default values for the remaining settings. Then select Review + create. After reviewing the settings, select Create.

When the Deployment succeeded message appears, select the container registry in the portal.

Take note of the registry name and the value of the Login server, which is a fully qualified name ending with azurecr.io in the Azure cloud. If you selected a DNL option, the login server name will include a unique hash.

Please use the login server in the following steps when you push and pull images with Docker, as well as in downstream references such as Dockerfiles, Kubernetes YAML, and Helm charts.

Log in to registry

az acr login --name <registry-name>

az acr login --name contosoacrregistry

Connect-AzContainerRegistry -Name <registry-name>

Connect-AzContainerRegistry -Name contosoacrregistry

Push image to registry

To push an image to an Azure Container registry, you must first have an image. If you don't yet have any local container images, run the following docker pull command to pull an existing public image. For this example, pull the hello-world image from Microsoft Container Registry.

docker pull mcr.microsoft.com/hello-world

Before you can push an image to your registry, you must tag it using the docker tag with the fully qualified name of your registry login server.

• The login server name format for Domain Name Label (DNL) protected registries with a unique DNS name hash included is mycontainerregistry-abc123.azurecr.io.
• The login server name format for registries created with the Unsecure DNL option is mycontainerregistry.azurecr.io.

For example, if your registry was created with the Tenant Reuse DNL scope, the login server might look like mycontainerregistry-abc123.azurecr.io with a hash in the DNS name. If your registry was created with the Unsecure DNL option, the login server would look like mycontainerregistry.azurecr.io without the hash.

For more details on DNL options during registry creation and DNS name implications, see Quickstart - Create Registry in Portal.

Example: Tagging an image before push

Tag the image using the docker tag command using your registry's login server.

Tagging image for a non-DNL registry:

docker tag mcr.microsoft.com/hello-world mycontainerregistry.azurecr.io/hello-world:v1

Tagging image for a DNL-enabled registry:

docker tag mcr.microsoft.com/hello-world mycontainerregistry-abc123.azurecr.io/hello-world:v1

Finally, use docker push to push the image to the registry instance. Replace <login-server> with the login server name of your registry instance. This example creates the hello-world repository, containing the hello-world:v1 image.

docker push <login-server>/hello-world:v1

After pushing the image to your container registry, remove the hello-world:v1 image from your local Docker environment. (Note that this docker rmi command doesn't remove the image from the hello-world repository in your Azure container registry.)

docker rmi <login-server>/hello-world:v1

List container images

To list the images in your registry, navigate to your registry in the portal and select Repositories, then select the hello-world repository you created with docker push.

By selecting the hello-world repository, you see the v1-tagged image under Tags.

Run image from registry

Now, you can pull and run the hello-world:v1 container image from your container registry by using docker run:

docker run <login-server>/hello-world:v1  

Example output:

Unable to find image 'mycontainerregistry.azurecr.io/hello-world:v1' locally
v1: Pulling from hello-world
Digest: sha256:662dd8e65ef7ccf13f417962c2f77567d3b132f12c95909de6c85ac3c326a345
Status: Downloaded newer image for mycontainerregistry.azurecr.io/hello-world:v1

Hello from Docker!
This message shows that your installation appears to be working correctly.

[...]

Clean up resources

To clean up your resources, navigate to the myResourceGroup resource group in the portal. Once the resource group is loaded, click on Delete resource group to remove the resource group, the container registry, and the container images stored there.

Next steps

In this quickstart, you created an Azure Container Registry with the Azure portal, pushed a container image, and pulled and ran the image from the registry. Continue to the Azure Container Registry tutorials for a deeper look at ACR.