Use Managed identities with Azure Machine Learning CLI v1

APPLIES TO: Python SDK azureml v1

APPLIES TO: Azure CLI ml extension v1

Managed identities allow you to configure your workspace with the minimum required permissions to access resources.

When configuring Azure Machine Learning workspace in trustworthy manner, it is important to ensure that different services associated with the workspace have the correct level of access. For example, during machine learning workflow the workspace needs access to Azure Container Registry (ACR) for Docker images, and storage accounts for training data.

Furthermore, managed identities allow fine-grained control over permissions, for example you can grant or revoke access from specific compute resources to a specific ACR.

In this article, you'll learn how to use managed identities to:

• Configure and use ACR for your Azure Machine Learning workspace without having to enable admin user access to ACR.
• Access a private ACR external to your workspace, to pull base images for training or inference.
• Create workspace with user-assigned managed identity to access associated resources.

Prerequisites

• An Azure Machine Learning workspace. For more information, see Create workspace resources.

• The Azure CLI extension for Machine Learning service

  Important

  Some of the Azure CLI commands in this article use the azure-cli-ml, or v1, extension for Azure Machine Learning. Support for the v1 extension will end on September 30, 2025. You will be able to install and use the v1 extension until that date.

  We recommend that you transition to the ml, or v2, extension before September 30, 2025. For more information on the v2 extension, see Azure ML CLI extension and Python SDK v2.

• The Azure Machine Learning Python SDK.

• To assign roles, the login for your Azure subscription must have the Managed Identity Operator role, or other role that grants the required actions (such as Owner).

• You must be familiar with creating and working with Managed Identities.

Configure managed identities

In some situations, it's necessary to disallow admin user access to Azure Container Registry. For example, the ACR may be shared and you need to disallow admin access by other users. Or, creating ACR with admin user enabled is disallowed by a subscription level policy.

When you create ACR without enabling admin user access, managed identities are used to access the ACR to build and pull Docker images.

You can bring your own ACR with admin user disabled when you create the workspace. Alternatively, let Azure Machine Learning create workspace ACR and disable admin user afterwards.

Bring your own ACR

If ACR admin user is disallowed by subscription policy, you should first create ACR without admin user, and then associate it with the workspace. Also, if you have existing ACR with admin user disabled, you can attach it to the workspace.

Create ACR from Azure CLI without setting --admin-enabled argument, or from Azure portal without enabling admin user. Then, when creating Azure Machine Learning workspace, specify the Azure resource ID of the ACR. The following example demonstrates creating a new Azure Machine Learning workspace that uses an existing ACR:

az ml workspace create -w <workspace name> \
-g <workspace resource group> \
-l <region> \
--container-registry /subscriptions/<subscription id>/resourceGroups/<acr resource group>/providers/Microsoft.ContainerRegistry/registries/<acr name>

Let Azure Machine Learning service create workspace ACR

If you do not bring your own ACR, Azure Machine Learning service will create one for you when you perform an operation that needs one. For example, submit a training run to Machine Learning Compute, build an environment, or deploy a web service endpoint. The ACR created by the workspace will have admin user enabled, and you need to disable the admin user manually.

1. Create a new workspace

   az ml workspace show -n <my workspace> -g <my resource group>
   

2. Perform an action that requires ACR. For example, the tutorial on training a model.

3. Get the ACR name created by the cluster:

   az ml workspace show -w <my workspace> \
   -g <my resource group>
   --query containerRegistry
   

   This command returns a value similar to the following text. You only want the last portion of the text, which is the ACR instance name:

   /subscriptions/<subscription id>/resourceGroups/<my resource group>/providers/MicrosoftContainerReggistry/registries/<ACR instance name>
   

4. Update the ACR to disable the admin user:

   az acr update --name <ACR instance name> --admin-enabled false
   

Create compute with managed identity to access Docker images for training

To access the workspace ACR, create machine learning compute cluster with system-assigned managed identity enabled. You can enable the identity from Azure portal or Studio when creating compute, or from Azure CLI using the below. For more information, see using managed identity with compute clusters.

az ml computetarget create amlcompute --name <cluster name> -w <workspace> -g <resource group> --vm-size <vm sku> --assign-identity '[system]'

A managed identity is automatically granted ACRPull role on workspace ACR to enable pulling Docker images for training.

Access base images from private ACR

By default, Azure Machine Learning uses Docker base images that come from a public repository managed by Azure. It then builds your training or inference environment on those images. For more information, see What are ML environments?.

To use a custom base image internal to your enterprise, you can use managed identities to access your private ACR. There are two use cases:

• Use base image for training as is.
• Build Azure Machine Learning managed image with custom image as a base.

Pull Docker base image to machine learning compute cluster for training as is

Create machine learning compute cluster with system-assigned managed identity enabled as described earlier. Then, determine the principal ID of the managed identity.

APPLIES TO: Azure CLI ml extension v1

az ml computetarget amlcompute identity show --name <cluster name> -w <workspace> -g <resource group>

Optionally, you can update the compute cluster to assign a user-assigned managed identity:

APPLIES TO: Azure CLI ml extension v1

az ml computetarget amlcompute identity assign --name <cluster name> \
-w $mlws -g $mlrg --identities <my-identity-id>

To allow the compute cluster to pull the base images, grant the managed service identity ACRPull role on the private ACR

az role assignment create --assignee <principal ID> \
--role acrpull \
--scope "/subscriptions/<subscription ID>/resourceGroups/<private ACR resource group>/providers/Microsoft.ContainerRegistry/registries/<private ACR name>"

Finally, when submitting a training run, specify the base image location in the environment definition.

APPLIES TO: Python SDK azureml v1

from azureml.core import Environment
env = Environment(name="private-acr")
env.docker.base_image = "<ACR name>.azurecr.cn/<base image repository>/<base image version>"
env.python.user_managed_dependencies = True

Build Azure Machine Learning managed environment into base image from private ACR for training or inference

APPLIES TO: Azure CLI ml extension v1

In this scenario, Azure Machine Learning service builds the training or inference environment on top of a base image you supply from a private ACR. Because the image build task happens on the workspace ACR using ACR Tasks, you must perform more steps to allow access.

1. Create user-assigned managed identity and grant the identity ACRPull access to the private ACR.

2. Grant the workspace system-assigned managed identity a Managed Identity Operator role on the user-assigned managed identity from the previous step. This role allows the workspace to assign the user-assigned managed identity to ACR Task for building the managed environment.

   1. Obtain the principal ID of workspace system-assigned managed identity:

      az ml workspace show -w <workspace name> -g <resource group> --query identityPrincipalId
      

   2. Grant the Managed Identity Operator role:

      az role assignment create --assignee <principal ID> --role managedidentityoperator --scope <user-assigned managed identity resource ID>
      

      The user-assigned managed identity resource ID is Azure resource ID of the user assigned identity, in the format /subscriptions/<subscription ID>/resourceGroups/<resource group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned managed identity name>.

3. Specify the external ACR and client ID of the user-assigned managed identity in workspace connections by using Workspace.set_connection method:

   APPLIES TO: Python SDK azureml v1

   workspace.set_connection(
       name="privateAcr", 
       category="ACR", 
       target = "<acr url>", 
       authType = "RegistryConnection", 
       value={"ResourceId": "<user-assigned managed identity resource id>", "ClientId": "<user-assigned managed identity client ID>"})
   

4. Once the configuration is complete, you can use the base images from private ACR when building environments for training or inference. The following code snippet demonstrates how to specify the base image ACR and image name in an environment definition:

   APPLIES TO: Python SDK azureml v1

   from azureml.core import Environment
   
   env = Environment(name="my-env")
   env.docker.base_image = "<acr url>/my-repo/my-image:latest"
   

   Optionally, you can specify the managed identity resource URL and client ID in the environment definition itself by using RegistryIdentity. If you use registry identity explicitly, it overrides any workspace connections specified earlier:

   APPLIES TO: Python SDK azureml v1

   from azureml.core.container_registry import RegistryIdentity
   
   identity = RegistryIdentity()
   identity.resource_id= "<user-assigned managed identity resource ID>"
   identity.client_id="<user-assigned managed identity client ID>"
   env.docker.base_image_registry.registry_identity=identity
   env.docker.base_image = "my-acr.azurecr.cn/my-repo/my-image:latest"
   

Use Docker images for inference

Once you've configured ACR without admin user as described earlier, you can access Docker images for inference without admin keys from your Azure Kubernetes service (AKS). When you create or attach AKS to workspace, the cluster's service principal is automatically assigned ACRPull access to workspace ACR.

Create workspace with user-assigned managed identity

When creating a workspace, you can bring your own user-assigned managed identity that will be used to access the associated resources: ACR, KeyVault, Storage, and App Insights.

Use Azure CLI or Python SDK to create the workspace. When using the CLI, specify the ID using the --primary-user-assigned-identity parameter. When using the SDK, use primary_user_assigned_identity. The following are examples of using the Azure CLI and Python to create a new workspace using these parameters:

Azure CLI

APPLIES TO: Azure CLI ml extension v1

az ml workspace create -w <workspace name> -g <resource group> --primary-user-assigned-identity <managed identity ARM ID>

Python

APPLIES TO: Python SDK azureml v1

from azureml.core import Workspace

ws = Workspace.create(name="workspace name", 
    subscription_id="subscription id", 
    resource_group="resource group name",
    primary_user_assigned_identity="managed identity ARM ID")

You can also use an ARM template to create a workspace with user-assigned managed identity.

For a workspace with customer-managed keys for encryption, you can pass in a user-assigned managed identity to authenticate from storage to Key Vault. Use argument user-assigned-identity-for-cmk-encryption (CLI) or user_assigned_identity_for_cmk_encryption (SDK) to pass in the managed identity. This managed identity can be the same or different as the workspace primary user assigned managed identity.

Next steps

• Learn more about enterprise security in Azure Machine Learning
• Learn about identity-based data access
• Learn about managed identities on compute cluster.