Edit

Share via

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

Azure Virtual Network provides secure, private networking for your Azure and on-premises resources. By using a service endpoint, you can 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.

Important

Azure Container Registry now supports Azure Private Link, enabling private endpoints from a virtual network to be placed on a registry. We recommend using private endpoints instead of service endpoints in most network scenarios. Private endpoints are accessible from within the virtual network, using private IP addresses. The container registry doesn't support enabling both private link and service endpoint features configured from a virtual network. Run the list and remove 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 SKU features and limits. Each Premium registry supports a maximum of 100 virtual network rules.

Preview limitations

Keep in mind the following current limitations when using service endpoints to restrict access to a container registry:

  • 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 by 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

If your container registry restricts access to private endpoints, selected subnets, or IP addresses, some functionality might be unavailable or require more configuration.

  • When you disable public network access to a registry, certain trusted services, including Microsoft Defender for Cloud, can access the registry only if you enable a network setting to bypass the network rules.
  • Once you disable the public network access, instances of certain Azure services, including Azure DevOps Services, can't access the container registry.
  • Private endpoints aren't currently supported with agents managed by Azure DevOps. You 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 you disable public network access, you can't list repositories and tags outside the virtual network by using the Azure portal, Azure CLI, or other tools.

Prerequisites

  • To use the Azure CLI steps in this article, you need Azure CLI version 2.0.58 or later. 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.

  • To restrict registry access by 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 can 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 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. After 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

You should see output confirming 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

Follow these steps to configure your container registry to allow access from a subnet in an Azure virtual network by using the Azure CLI.

Add a service endpoint to a subnet

When you create a VM, Azure creates a virtual network in the same resource group by default. 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 configuration 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 ID 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 authenticate 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 authenticate from another host using the az acr login command or docker login command, you see output 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 you 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 you 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 you no longer need them, you can delete the entire resource group by using the az group delete command:

az group delete --name myResourceGroup

Related content

  • Last updated on