Pull images from a connected registry on IoT Edge device

To pull images from a connected registry, configure a client token and pass the token credentials to access registry content.


Create a scope map

Use the az acr scope-map create command to create a scope map for read access to the hello-world repository:

# Use the REGISTRY_NAME variable in the following Azure CLI commands to identify the registry

az acr scope-map create \
  --name hello-world-scopemap \
  --registry $REGISTRY_NAME \
  --repository hello-world content/read \
  --description "Scope map for the connected registry."

Create a client token

Use the az acr token create command to create a client token and associate it with the newly created scope map:

az acr token create \
  --name myconnectedregistry-client-token \
  --registry $REGISTRY_NAME \
  --scope-map hello-world-scopemap

The command will return details about the newly generated token including passwords.


Make sure that you save the generated passwords. Those are one-time passwords and cannot be retrieved. You can generate new passwords using the az acr token credential generate command.

Update the connected registry with the client token

Use the az acr connected-registry update command to update the connected registry with the newly created client token.

az acr connected-registry update \
  --registry $REGISTRY_NAME \
  --add-client-token myconnectedregistry-client-token

Pull an image from the connected registry

From a machine with access to the IoT Edge device, use the following example command to sign into the connected registry, using the client token credentials. For best practices to manage login credentials, see the docker login command reference.


If you set up your connected registry as an insecure registry, update the insecure registries list in the Docker daemon configuration to include the IP address (or FQDN) and port of your connected registry on the IoT Edge device. This configuration should only be used for testing purposes. For more information, see Test an insecure registry.

docker login --username myconnectedregistry-client-token \
  --password <token_password> <IP_address_or_FQDN_of_connected_registry>:<port>

For IoT Edge scenarios, be sure to include the port used to reach the connected registry on the device. Example:

docker login --username myconnectedregistry-client-token \
  --password xxxxxxxxxxx

Then, use the following command to pull the hello-world image:

docker pull <IP_address_or_FQDN_of_connected_registry>:<port>/hello-world

Next steps