Configure rules to access an Azure container registry behind a firewall

  • Article

This article explains how to configure rules on your firewall to allow access to an Azure container registry. For example, an Azure IoT Edge device behind a firewall or proxy server might need to access a container registry to pull a container image. Or, a locked-down server in an on-premises network might need access to push an image.

If instead you want to configure inbound network access to a container registry only within an Azure virtual network, see Configure Azure Private Link for an Azure container registry.

About registry endpoints

To pull or push images or other artifacts to an Azure container registry, a client such as a Docker daemon needs to interact over HTTPS with two distinct endpoints. For clients that access a registry from behind a firewall, you need to configure access rules for both endpoints. Both endpoints are reached over port 443.

  • Registry REST API endpoint - Authentication and registry management operations are handled through the registry's public REST API endpoint. This endpoint is the login server name of the registry. Example: myregistry.azurecr.cn

    • Registry REST API endpoint for certificates - Azure container registry uses a wildcard SSL certificate for all subdomains. When connecting to the Azure container registry using SSL, the client must be able to download the certificate for the TLS handshake. In such cases, azurecr.cn must also be accessible.

  • Storage (data) endpoint - Azure allocates blob storage in Azure Storage accounts on behalf of each registry to manage the data for container images and other artifacts. When a client accesses image layers in an Azure container registry, it makes requests using a storage account endpoint provided by the registry.

If your registry is geo-replicated, a client might need to interact with the data endpoint in a specific region or in multiple replicated regions.

Allow access to REST and data endpoints

  • REST endpoint - Allow access to the fully qualified registry login server name, <registry-name>.azurecr.cn, or an associated IP address range

  • Storage (data) endpoint - Allow access to all Azure blob storage accounts using the wildcard *.blob.core.chinacloudapi.cn, or an associated IP address range.

    Note

    Azure Container Registry is introducing dedicated data endpoints, allowing you to tightly scope client firewall rules for your registry storage. Optionally enable data endpoints in all regions where the registry is located or replicated, using the form <registry-name>.<region>.data.azurecr.cn.

About Registry FQDN's

Registry has two FQDN's, the login url and the data endpoint.

  • Both the login url and the data endpoint are accessible from within the virtual network, using private IP's by enabling a private link.
  • A registry that does not use data endpoints would have to access the data from an endpoint of the form *.blob.core.chinacloudapi.cn and does not provide the isolation required when configuring firewall rules.
  • A registry with a private link enabled gets the dedicated data endpoint automatically.
  • A dedicated data endpoint is created per region for a registry.
  • Login url remains the same irrespective of whether data endpoint is enabled or disabled.

Allow access by IP address range

If your organization has policies to allow access only to specific IP addresses or address ranges, download Azure IP Ranges and Service Tags - China Cloud.

To find the ACR REST endpoint IP ranges for which you need to allow access, search for AzureContainerRegistry in the JSON file.

Important

IP address ranges for Azure services can change, and updates are published weekly. Download the JSON file regularly, and make necessary updates in your access rules. If your scenario involves configuring network security group rules in an Azure virtual network or you use Azure Firewall, use the AzureContainerRegistry service tag instead.

REST IP addresses for all regions

{
  "name": "AzureContainerRegistry",
  "id": "AzureContainerRegistry",
  "properties": {
    "changeNumber": 10,
    "region": "",
    "platform": "Azure",
    "systemService": "AzureContainerRegistry",
    "addressPrefixes": [
      "40.73.136.24/29",
    [...]

REST IP addresses for a specific region

Search for the specific region, such as AzureContainerRegistry.ChinaNorth.

{
  "name": "AzureContainerRegistry.ChinaNorth",
  "id": "AzureContainerRegistry.ChinaNorth",
  "properties": {
    "changeNumber": 1,
    "region": "chinanorth",
    "platform": "Azure",
    "systemService": "AzureContainerRegistry",
    "addressPrefixes": [
      "139.217.48.104/29",
    [...]

Storage IP addresses for all regions

{
  "name": "Storage",
  "id": "Storage",
  "properties": {
    "changeNumber": 19,
    "region": "",
    "platform": "Azure",
    "systemService": "AzureStorage",
    "addressPrefixes": [
      "40.72.64.0/24",
    [...]

Storage IP addresses for specific regions

Search for the specific region, such as Storage.ChinaNorth.

{
  "name": "Storage.ChinaNorth",
  "id": "Storage.ChinaNorth",
  "properties": {
    "changeNumber": 1,
    "region": "chinanorth",
    "platform": "Azure",
    "systemService": "AzureStorage",
    "addressPrefixes": [
      "40.72.64.0/24"
    [...]

Allow access by service tag

In an Azure virtual network, use network security rules to filter traffic from a resource such as a virtual machine to a container registry. To simplify the creation of the Azure network rules, use the AzureContainerRegistry service tag. A service tag represents a group of IP address prefixes to access an Azure service globally or per Azure region. The tag is automatically updated when addresses change.

For example, create an outbound network security group rule with destination AzureContainerRegistry to allow traffic to an Azure container registry. To allow access to the service tag only in a specific region, specify the region in the following format: AzureContainerRegistry.[region name].

Enable dedicated data endpoints

Warning

If you previously configured client firewall access to the existing *.blob.core.chinacloudapi.cn endpoints, switching to dedicated data endpoints will impact client connectivity, causing pull failures. To ensure clients have consistent access, add the new data endpoint rules to the client firewall rules. Once completed, enable dedicated data endpoints for your registries using the Azure CLI or other tools.

Dedicated data endpoints is an optional feature of the Premium container registry service tier. For information about registry service tiers and limits, see Azure Container Registry service tiers.

You can enable dedicated data endpoints using the Azure portal or the Azure CLI. The data endpoints follow a regional pattern, <registry-name>.<region>.data.azurecr.cn. In a geo-replicated registry, enabling data endpoints enables endpoints in all replica regions.

Portal

To enable data endpoints using the portal:

  1. Navigate to your container registry.
  2. Select Networking > Public access.
  3. Select the Enable dedicated data endpoint checkbox.
  4. Select Save.

The data endpoint or endpoints appear in the portal.

Dedicated data endpoints in portal

Azure CLI

To enable data endpoints using the Azure CLI, use Azure CLI version 2.4.0 or higher. If you need to install or upgrade, see Install Azure CLI.

The following az acr update command enables dedicated data endpoints on a registry myregistry.

az acr update --name myregistry --data-endpoint-enabled

To view the data endpoints, use the az acr show-endpoints command:

az acr show-endpoints --name myregistry

Output for demonstration purposes shows two regional endpoints

{
    "loginServer": "myregistry.azurecr.cn",
    "dataEndpoints": [
        {
            "region": "chinaeast2",
            "endpoint": "myregistry.chinaeast2.data.azurecr.cn",
        },
        {
            "region": "chinanorth2",
            "endpoint": "myregistry.chinanorth2.data.azurecr.cn",
        }
    ]
}

After you set up dedicated data endpoints for your registry, you can enable client firewall access rules for the data endpoints. Enable data endpoint access rules for all required registry regions.

Configure client firewall rules for MCR

If you need to access Microsoft Container Registry (MCR) from behind a firewall, see the guidance to configure MCR client firewall rules. MCR is the primary registry for all Microsoft-published docker images, such as Windows Server images.

Next steps