Edit

Restrict access to a container registry using a service endpoint in an Azure virtual network

  • Article

Azure Virtual Network provides secure, private networking for your Azure and on-premises resources. A service endpoint allows you to secure your container registry's public IP address to only your virtual network. This endpoint gives traffic an optimal route to the resource over the Azure backbone network. The identities of the virtual network and the subnet are also transmitted with each request.

This article shows how to configure a container registry service endpoint (preview) in a virtual network.

Each registry supports a maximum of 100 virtual network rules.

Important

Azure Container Registry now supports Azure Private Link, enabling private endpoints from a virtual network to be placed on a registry. Private endpoints are accessible from within the virtual network, using private IP addresses. We recommend using private endpoints instead of service endpoints in most network scenarios. The container registry does not support enabling both private link and service endpoint features configured from a virtual network. So, we recommend running the list and removing the network rules as required.

Configuring a registry service endpoint is available in the Premium container registry service tier. For information about registry service tiers and limits, see Azure Container Registry service tiers.

Preview limitations

  • Future development of service endpoints for Azure Container Registry isn't currently planned. We recommend using private endpoints instead.
  • You can't use the Azure portal to configure service endpoints on a registry.
  • Only an Azure Kubernetes Service cluster or Azure virtual machine can be used as a host to access a container registry using a service endpoint. Other Azure services including Azure Container Instances aren't supported.
  • Service endpoints for Azure Container Registry aren't supported in the Azure US Government cloud or Microsoft Azure operated by 21Vianet cloud.

Important

Some functionality may be unavailable or require more configuration in a container registry that restricts access to private endpoints, selected subnets, or IP addresses.

  • When public network access to a registry is disabled, registry access by certain trusted services including Azure Security Center requires enabling a network setting to bypass the network rules.
  • Once the public network access is disabled, instances of certain Azure services including Azure DevOps Services are currently unable to access the container registry.
  • Private endpoints are not currently supported with Azure DevOps managed agents. You will need to use a self-hosted agent with network line of sight to the private endpoint.
  • If the registry has an approved private endpoint and public network access is disabled, repositories and tags can't be listed outside the virtual network using the Azure portal, Azure CLI, or other tools.

Prerequisites

  • To use the Azure CLI steps in this article, Azure CLI version 2.0.58 or later is required. If you need to install or upgrade, see Install Azure CLI.

  • If you don't already have a container registry, create one (Premium tier required) and push a sample image such as hello-world from Docker Hub. For example, use the Azure portal or the Azure CLI to create a registry.

  • If you want to restrict registry access using a service endpoint in a different Azure subscription, register the resource provider for Azure Container Registry in that subscription. For example:

    az account set --subscription <Name or ID of subscription of virtual network>

az provider register --namespace Microsoft.ContainerRegistry

Create a Docker-enabled virtual machine

For test purposes, use a Docker-enabled Ubuntu VM to access an Azure container registry. To use Microsoft Entra authentication to the registry, also install the Azure CLI on the VM. If you already have an Azure virtual machine, skip this creation step.

You may use the same resource group for your virtual machine and your container registry. This setup simplifies clean-up at the end but isn't required. If you choose to create a separate resource group for the virtual machine and virtual network, run az group create. The following example assumes you've set environment variables for the resource group name and registry location:

az group create --name $RESOURCE_GROUP --location $REGISTRY_LOCATION

Now deploy a default Ubuntu Azure virtual machine with az vm create. The following example creates a VM named myDockerVM.

VM_NAME=myDockerVM

az vm create \
  --resource-group $RESOURCE_GROUP \
  --name $VM_NAME \
  --image Ubuntu2204 \
  --admin-username azureuser \
  --generate-ssh-keys

It takes a few minutes for the VM to be created. When the command completes, take note of the publicIpAddress displayed by the Azure CLI. Use this address to make SSH connections to the VM.

Install Docker on the VM

After the VM is running, make an SSH connection to the VM. Replace publicIpAddress with the public IP address of your VM.

ssh azureuser@publicIpAddress

Run the following commands to install Docker on the Ubuntu VM:

sudo apt-get update
sudo apt install docker.io -y

After installation, run the following command to verify that Docker is running properly on the VM:

sudo docker run -it hello-world

Output:

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

Install the Azure CLI

Follow the steps in Install Azure CLI with apt to install the Azure CLI on your Ubuntu virtual machine. For example:

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

Exit the SSH connection.

Configure network access for registry

In this section, configure your container registry to allow access from a subnet in an Azure virtual network. Steps are provided using the Azure CLI.

Add a service endpoint to a subnet

When you create a VM, Azure by default creates a virtual network in the same resource group. The name of the virtual network is based on the name of the virtual machine. For example, if you name your virtual machine myDockerVM, the default virtual network name is myDockerVMVNET, with a subnet named myDockerVMSubnet. Verify this by using the az network vnet list command:

az network vnet list \
  --resource-group myResourceGroup \
  --query "[].{Name: name, Subnet: subnets[0].name}"

Output:

[
  {
    "Name": "myDockerVMVNET",
    "Subnet": "myDockerVMSubnet"
  }
]

Use the az network vnet subnet update command to add a Microsoft.ContainerRegistry service endpoint to your subnet. Substitute the names of your virtual network and subnet in the following command:

az network vnet subnet update \
  --name myDockerVMSubnet \
  --vnet-name myDockerVMVNET \
  --resource-group myResourceGroup \
  --service-endpoints Microsoft.ContainerRegistry

Use the az network vnet subnet show command to retrieve the resource ID of the subnet. You need this in a later step to configure a network access rule.

az network vnet subnet show \
  --name myDockerVMSubnet \
  --vnet-name myDockerVMVNET \
  --resource-group myResourceGroup \
  --query "id"
  --output tsv

Output:

/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myDockerVMVNET/subnets/myDockerVMSubnet

Change default network access to registry

By default, an Azure container registry allows connections from hosts on any network. To limit access to a selected network, change the default action to deny access. Substitute the name of your registry in the following az acr update command:

az acr update --name myContainerRegistry --default-action Deny

Add network rule to registry

Use the az acr network-rule add command to add a network rule to your registry that allows access from the VM's subnet. Substitute the container registry's name and the resource ID of the subnet in the following command:

az acr network-rule add \
  --name mycontainerregistry \
  --subnet <subnet-resource-id>

Verify access to the registry

After waiting a few minutes for the configuration to update, verify that the VM can access the container registry. Make an SSH connection to your VM, and run the az acr login command to login to your registry.

az acr login --name mycontainerregistry

You can perform registry operations such as run docker pull to pull a sample image from the registry. Substitute an image and tag value appropriate for your registry, prefixed with the registry login server name (all lowercase):

docker pull mycontainerregistry.azurecr.io/hello-world:v1

Docker successfully pulls the image to the VM.

This example demonstrates that you can access the private container registry through the network access rule. However, the registry can't be accessed from a login host that doesn't have a network access rule configured. If you attempt to login from another host using the az acr login command or docker login command, output is similar to the following:

Error response from daemon: login attempt to https://xxxxxxx.azurecr.io/v2/ failed with status: 403 Forbidden

Restore default registry access

To restore the registry to allow access by default, remove any network rules that are configured. Then set the default action to allow access.

Remove network rules

To see a list of network rules configured for your registry, run the following az acr network-rule list command:

az acr network-rule list --name mycontainerregistry

For each rule that is configured, run the az acr network-rule remove command to remove it. For example:

# Remove a rule that allows access for a subnet. Substitute the subnet resource ID.

az acr network-rule remove \
  --name mycontainerregistry \
  --subnet /subscriptions/ \
  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/myDockerVMVNET/subnets/myDockerVMSubnet

Allow access

Substitute the name of your registry in the following az acr update command:

az acr update --name myContainerRegistry --default-action Allow

Clean up resources

If you created all the Azure resources in the same resource group and no longer need them, you can optionally delete the resources by using a single az group delete command:

az group delete --name myResourceGroup

Next steps