Edit

Share via

Quickstart: Create a connected registry using the Azure CLI or Azure portal

  • 05/21/2025

In this quickstart, you use the Azure CLI and Azure portal to create a connected registry resource in Azure. The connected registry feature of Azure Container Registry allows you to deploy a registry remotely or on your premises and synchronize images and other artifacts with the cloud registry.

Here you create two connected registry resources for a cloud registry: one connected registry allows read and write (artifact pull and push) functionality and one allows read-only functionality.

After creating a connected registry, you can follow other guides to deploy and use it on your on-premises or remote infrastructure.

Prerequisites

  • Azure Container registry - If you don't already have a container registry, create one (Premium tier required) in a region that supports connected registries.

To import images to the container registry, use the Azure CLI

Enable the dedicated data endpoint for the cloud registry

Enable the dedicated data endpoint for the Azure container registry in the cloud. This step is needed for a connected registry to communicate with the cloud registry.

  1. In the Azure portal, navigate to your container registry.
  2. Select Networking > Public access. Select the Enable dedicated data endpoint checkbox.
  3. Select Save.

Screenshot of enabling dedicated data endpoint.

Import images to your cloud registry

Import the following container images to your cloud registry using the az acr import command. Skip this step if you already imported these images.

Connected registry image

Use the az acr import command to import the connected registry image into your private registry.

# Use the REGISTRY_NAME variable in the following Azure CLI commands to identify the registry
REGISTRY_NAME=<container-registry-name>

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/acr/connected-registry:1.0.0

Hello-world image

For testing the connected registry, import the hello-world image. This repository will be synchronized to the connected registry and pulled by the connected registry clients.

az acr import \
  --name $REGISTRY_NAME \
  --source mcr.microsoft.com/hello-world:1.1.2

Create a connected registry resource for read and write functionality

The following steps create a connected registry in ReadWrite mode that is linked to the cloud registry.

  1. In the Azure portal, navigate to your container registry.
  2. Select Connected registries (Preview) > + Create.
  3. Enter or select the values in the following table, and select Save.
Item Description
Parent Select No parent for a connected registry linked to the cloud registry.
Mode Select ReadWrite.
Name The connected registry name must start with a letter and contain only alphanumeric characters. It must be 5 to 40 characters long and unique in the hierarchy for this Azure container registry.
Logging properties Accept the default settings.
Sync properties Accept the default settings. Because there's no synchronization schedule defined by default, the repositories are synchronized between the cloud registry and the connected registry without interruptions.
Repositories Select or enter the names of the repositories you imported in the previous step. The specified repositories are synchronized between the cloud registry and the connected registry once deployed.

Create a connected registry in ReadWrite mode

Create a connected registry resource for read-only functionality

The following steps create a connected registry in ReadOnly mode whose parent is the connected registry you created in the previous section. This connected registry enables read-only (artifact pull) functionality once deployed.

  1. In the Azure portal, navigate to your container registry.
  2. Select Connected registries (Preview) > + Create.
  3. Enter or select the values in the following table, and select Save.
Item Description
Parent Select the connected registry you created previously.
Mode Select ReadOnly.
Name The connected registry name must start with a letter and contain only alphanumeric characters. It must be 5 to 40 characters long and unique in the hierarchy for this Azure container registry.
Logging properties Accept the default settings.
Sync properties Accept the default settings. Because there's no synchronization schedule defined by default, the repositories are synchronized between the cloud registry and the connected registry without interruptions.
Repositories Select or enter the names of the repositories you imported in the previous step. The specified repositories are synchronized between the parent registry and the connected registry once deployed.

Create a connected registry in ReadOnly mode

Verify that the resources are created

Select a connected registry in the portal to view its properties, such as its connection status (Offline, Online, or Unhealthy) and whether it activated (deployed on-premises). In the following example, the connected registry isn't deployed. The connection state of "Offline" indicates that it disconnected from the cloud.

View connected registry properties

From this view, you can also generate a connection string and optionally generate passwords for the sync token. A connection string contains configuration settings used for deploying a connected registry and synchronizing content with a parent registry.

Next steps

In this quickstart, you used the Azure CLI and Azure portal to create two connected registry resources in Azure. Those new connected registry resources are tied to your cloud registry and allow synchronization of artifacts with the cloud registry.

Continue to the connected registry deployment guides to learn how to deploy and use a connected registry in your infrastructure.

Quickstart: Deploy connected registry to Azure Arc

Additional resources

Documentation