Manage Azure Machine Learning workspaces using Azure CLI extension v1

APPLIES TO: Azure CLI ml extension v1

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.

In this article, you learn how to create and manage Azure Machine Learning workspaces using the Azure CLI. The Azure CLI provides commands for managing Azure resources and is designed to get you working quickly with Azure, with an emphasis on automation. The machine learning extension for the CLI provides commands for working with Azure Machine Learning resources.

Prerequisites

• An Azure subscription. If you don't have one, try the free or paid version of Azure Machine Learning.

• To use the CLI commands in this document from your local environment, you need the Azure CLI.

  If you use the Azure Cloud Shell, the CLI is accessed through the browser and lives in the cloud.

Limitations

• When you create a new workspace, you can either automatically create services needed by the workspace or use existing services. If you want to use existing services from a different Azure subscription than the workspace, you must register the Azure Machine Learning namespace in the subscription that contains those services. For example, if you create a workspace in subscription A that uses a storage account in subscription B, the Azure Machine Learning namespace must be registered in subscription B before the workspace can use the storage account.

  The resource provider for Azure Machine Learning is Microsoft.MachineLearningServices. For information on seeing whether it's registered or registering it, see Azure resource providers and types.

  Important

  This information applies only to resources provided during workspace creation: Azure Storage Accounts, Azure Container Registry, Azure Key Vault, and Application Insights.

Tip

An Azure Application Insights instance is created when you create the workspace. You can delete the Application Insights instance after cluster creation if you want. Deleting it limits the information gathered from the workspace, and might make it more difficult to troubleshoot problems. If you delete the Application Insights instance created by the workspace, the only way to recreate it is to delete and recreate the workspace.

For more information on using the Application Insights instance, see Monitor and collect data from Machine Learning web service endpoints.

Secure CLI communications

Some of the Azure CLI commands communicate with Azure Resource Manager over the internet. This communication is secured using HTTPS/TLS 1.2.

With the Azure Machine Learning CLI extension v1 (azure-cli-ml), only some of the commands communicate with the Azure Resource Manager. Specifically, commands that create, update, delete, list, or show Azure resources. Operations such as submitting a training job communicate directly with the Azure Machine Learning workspace. If your workspace is secured with a private endpoint, that is enough to secure commands provided by the azure-cli-ml extension.

Connect the CLI to your Azure subscription

Important

If you are using the Azure Cloud Shell, you can skip this section. The cloud shell automatically authenticates you using the account you log into your Azure subscription.

There are several ways that you can authenticate to your Azure subscription from the CLI. The most simple is to interactively authenticate using a browser. To authenticate interactively, open a command line or terminal and use the following command:

az login

If the CLI can open your default browser, it will do so and load a sign-in page. Otherwise, you need to open a browser and follow the instructions on the command line. The instructions involve browsing to https://aka.ms/devicelogin and entering an authorization code.

Tip

After you sign in, you see a list of subscriptions associated with your Azure account. The subscription information with isDefault: true is the currently activated subscription for Azure CLI commands. This subscription must be the same one that contains your Azure Machine Learning workspace. You can find the subscription information on the overview page for your workspace in the Azure portal.

To select another subscription to use for Azure CLI commands, run the az account set -s <subscription> command and specify the subscription name or ID to switch to. For more information about subscription selection, see Use multiple Azure subscriptions.

For other methods of authenticating, see Sign in with Azure CLI.

Create a resource group

The Azure Machine Learning workspace must be created inside a resource group. You can use an existing resource group or create a new one. To create a new resource group, use the following command. Replace <resource-group-name> with the name to use for this resource group. Replace <location> with the Azure region to use for this resource group:

Note

You should select a region where Azure Machine Learning is available. For information, see Products available by region.

az group create --name <resource-group-name> --location <location>

The response from this command is similar to the following JSON. You can use the output values to locate the created resources or parse them as input to subsequent CLI steps for automation.

{
  "id": "/subscriptions/<subscription-GUID>/resourceGroups/<resourcegroupname>",
  "location": "<location>",
  "managedBy": null,
  "name": "<resource-group-name>",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": null
}

For more information on working with resource groups, see az group.

Create a workspace

When you deploy an Azure Machine Learning workspace, various other services are required as dependent associated resources. When you use the CLI to create the workspace, the CLI can either create new associated resources on your behalf or you could attach existing resources.

Important

When attaching your own storage account, make sure that it meets the following criteria:

• The storage account is not a premium account (Premium_LRS and Premium_GRS)
• Both Azure Blob and Azure File capabilities enabled
• Hierarchical Namespace (ADLS Gen 2) is disabled These requirements are only for the default storage account used by the workspace.

When attaching Azure container registry, you must have the admin account enabled before it can be used with an Azure Machine Learning workspace.

Create with new resources

To create a new workspace where the services are automatically created, use the following command:

az ml workspace create -w <workspace-name> -g <resource-group-name>

Bring existing resources

To create a workspace that uses existing resources, you must provide the resource ID for each resource. You can get this ID either via the 'properties' tab on each resource via the Azure portal, or by running the following commands using the Azure CLI.

• Azure Storage Account: az storage account show --name <storage-account-name> --query "id"
• Azure Application Insights: az monitor app-insights component show --app <application-insight-name> -g <resource-group-name> --query "id"
• Azure Key Vault: az keyvault show --name <key-vault-name> --query "ID"
• Azure Container Registry: az acr show --name <acr-name> -g <resource-group-name> --query "id"

The returned resource ID has the following format: "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/<provider>/<subresource>/<resource-name>".

Once you have the IDs for the resource(s) that you want to use with the workspace, use the base az workspace create -w <workspace-name> -g <resource-group-name> command and add the parameter(s) and ID(s) for the existing resources. For example, the following command creates a workspace that uses an existing container registry:

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --container-registry "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/Microsoft.ContainerRegistry/registries/<acr-name>"

Important

When you attaching existing resources, you don't have to specify all. You can specify one or more. For example, you can specify an existing storage account and the workspace will create the other resources.

The output of the workspace creation command is similar to the following JSON. You can use the output values to locate the created resources or parse them as input to subsequent CLI steps.

{
  "applicationInsights": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.insights/components/<application-insight-name>",
  "containerRegistry": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.containerregistry/registries/<acr-name>",
  "creationTime": "2019-08-30T20:24:19.6984254+00:00",
  "description": "",
  "friendlyName": "<workspace-name>",
  "id": "/subscriptions/<service-GUID>/resourceGroups/<resource-group-name>/providers/Microsoft.MachineLearningServices/workspaces/<workspace-name>",
  "identityPrincipalId": "<GUID>",
  "identityTenantId": "<GUID>",
  "identityType": "SystemAssigned",
  "keyVault": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.keyvault/vaults/<key-vault-name>",
  "location": "<location>",
  "name": "<workspace-name>",
  "resourceGroup": "<resource-group-name>",
  "storageAccount": "/subscriptions/<service-GUID>/resourcegroups/<resource-group-name>/providers/microsoft.storage/storageaccounts/<storage-account-name>",
  "type": "Microsoft.MachineLearningServices/workspaces",
  "workspaceid": "<GUID>"
}

Advanced configurations

Configure workspace for private network connectivity

Dependent on your use case and organizational requirements, you can choose to configure Azure Machine Learning using private network connectivity. You can use the Azure CLI to deploy a workspace and a Private link endpoint for the workspace resource. For more information on using a private endpoint and virtual network (VNet) with your workspace, see Virtual network isolation and privacy overview. For complex resource configurations, also refer to template based deployment options including Azure Resource Manager.

If you want to restrict workspace access to a virtual network, you can use the following parameters as part of the az ml workspace create command or use the az ml workspace private-endpoint commands.

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --pe-name "<pe name>"
                       --pe-auto-approval "<pe-autoapproval>"
                       --pe-resource-group "<pe name>"
                       --pe-vnet-name "<pe name>"
                       --pe-subnet-name "<pe name>"

• --pe-name: The name of the private endpoint that is created.
• --pe-auto-approval: Whether private endpoint connections to the workspace should be automatically approved.
• --pe-resource-group: The resource group to create the private endpoint in. Must be the same group that contains the virtual network.
• --pe-vnet-name: The existing virtual network to create the private endpoint in.
• --pe-subnet-name: The name of the subnet to create the private endpoint in. The default value is default.

For more information on how to use these commands, see the CLI reference pages.

Customer-managed key and high business impact workspace

By default, metadata for the workspace is stored in an Azure Cosmos DB instance that Microsoft maintains. This data is encrypted using Microsoft-managed keys. Instead of using the Microsoft-managed key, you can also provide your own key. Doing so creates an extra set of resources in your Azure subscription to store your data.

To learn more about the resources that are created when you bring your own key for encryption, see Data encryption with Azure Machine Learning.

Use the --cmk-keyvault parameter to specify the Azure Key Vault that contains the key, and --resource-cmk-uri to specify the resource ID and uri of the key within the vault.

To limit the data that Microsoft collects on your workspace, you can additionally specify the --hbi-workspace parameter.

az ml workspace create -w <workspace-name>
                       -g <resource-group-name>
                       --cmk-keyvault "<cmk keyvault name>"
                       --resource-cmk-uri "<resource cmk uri>"
                       --hbi-workspace

Note

Authorize the Machine Learning App (in Identity and Access Management) with contributor permissions on your subscription to manage the data encryption additional resources.

Note

Azure Cosmos DB is not used to store information such as model performance, information logged by experiments, or information logged from your model deployments. For more information on monitoring these items, see the Monitoring and logging section of the architecture and concepts article.

Important

Selecting high business impact can only be done when creating a workspace. You cannot change this setting after workspace creation.

For more information on customer-managed keys and high business impact workspace, see Enterprise security for Azure Machine Learning.

Using the CLI to manage workspaces

Get workspace information

To get information about a workspace, use the following command:

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

Update a workspace

To update a workspace, use the following command:

az ml workspace update -n <workspace-name> -g <resource-group-name>

Sync keys for dependent resources

If you change access keys for one of the resources used by your workspace, it takes around an hour for the workspace to synchronize to the new key. To force the workspace to sync the new keys immediately, use the following command:

az ml workspace sync-keys -w <workspace-name> -g <resource-group-name>

For more information on changing keys, see Regenerate storage access keys.

Delete a workspace

Warning

If soft-delete is enabled for the workspace, it can be recovered after deletion. If soft-delete isn't enabled, or you select the option to permanently delete the workspace, it can't be recovered. For more information, see Recover a deleted workspace.

To delete a workspace after it's no longer needed, use the following command:

az ml workspace delete -w <workspace-name> -g <resource-group-name>

Important

Deleting a workspace does not delete the application insight, storage account, key vault, or container registry used by the workspace.

You can also delete the resource group, which deletes the workspace and all other Azure resources in the resource group. To delete the resource group, use the following command:

az group delete -g <resource-group-name>

Tip

The default behavior for Azure Machine Learning is to soft delete the workspace. This means that the workspace is not immediately deleted, but instead is marked for deletion. For more information, see Soft delete.

Troubleshooting

Resource provider errors

When creating an Azure Machine Learning workspace, or a resource used by the workspace, you may receive an error similar to the following messages:

• No registered resource provider found for location {location}
• The subscription is not registered to use namespace {resource-provider-namespace}

Most resource providers are automatically registered, but not all. If you receive this message, you need to register the provider mentioned.

The following table contains a list of the resource providers required by Azure Machine Learning:

Resource provider	Why it's needed
Microsoft.MachineLearningServices	Creating the Azure Machine Learning workspace.
Microsoft.Storage	Azure Storage Account is used as the default storage for the workspace.
Microsoft.ContainerRegistry	Azure Container Registry is used by the workspace to build Docker images.
Microsoft.KeyVault	Azure Key Vault is used by the workspace to store secrets.
Microsoft.Notebooks	Integrated notebooks on Azure Machine Learning compute instance.
Microsoft.ContainerService	If you plan on deploying trained models to Azure Kubernetes Services.

If you plan on using a customer-managed key with Azure Machine Learning, then the following service providers must be registered:

Resource provider	Why it's needed
Microsoft.DocumentDB	Azure CosmosDB instance that logs metadata for the workspace.
Microsoft.Search	Azure Search provides indexing capabilities for the workspace.

If you plan on using a managed virtual network with Azure Machine Learning, then the Microsoft.Network resource provider must be registered. This resource provider is used by the workspace when creating private endpoints for the managed virtual network.

For information on registering resource providers, see Resolve errors for resource provider registration.

Moving the workspace

Warning

Moving your Azure Machine Learning workspace to a different subscription, or moving the owning subscription to a new tenant, is not supported. Doing so may cause errors.

Deleting the Azure Container Registry

The Azure Machine Learning workspace uses Azure Container Registry (ACR) for some operations. It will automatically create an ACR instance when it first needs one.

Warning

Once an Azure Container Registry is created for a workspace, don't delete it. Doing so breaks your Azure Machine Learning workspace.

Next steps

For more information on the Azure CLI extension for machine learning, see the az ml (v1) documentation.

To check for problems with your workspace, see How to use workspace diagnostics.

To learn how to move a workspace to a new Azure subscription, see How to move a workspace.

For information on how to keep your Azure Machine Learning up to date with the latest security updates, see Vulnerability management.