az ml workspace

  • Reference

Note

This reference is part of the ml extension for the Azure CLI (version 2.15.0 or higher). The extension will automatically install the first time you run an az ml workspace command. Learn more about extensions.

Manage Azure ML workspaces.

An Azure ML workspace is the top-level resource for Azure Machine Learning. It provides a centralized place to track the assets and resources used in your ML workflows, along with the logs and artifacts produced from your training jobs.

If you are upgrading from CLI v1 to v2, you require the following two changes in scope of workspace management:

  • Upgrade az ml workspace private-endpoint commands to equivalent az network private-endpoint commands.
  • Also, upgrade az ml workspace share commands to equivalent az role assignment create commands.

Commands

Name Description Type Status
az ml workspace create

Create a workspace.

 Extension GA
az ml workspace delete

Delete a workspace.

 Extension GA
az ml workspace diagnose

Diagnose workspace setup problems.

 Extension GA
az ml workspace list

List all the workspaces in a subscription.

 Extension GA
az ml workspace list-keys

List workspace keys for dependent resources such as Azure Storage, Azure Container Registry, and Azure Application Insights.

 Extension GA
az ml workspace outbound-rule

Manage outbound rules for the managed network of an Azure ML workspace.

 Extension GA
az ml workspace outbound-rule list

List all the managed network outbound rules for a workspace.

 Extension GA
az ml workspace outbound-rule remove

Remove an outbound rule from the managed network for a workspace.

 Extension GA
az ml workspace outbound-rule set

Add or update an outbound rule in the managed network for a workspace.

 Extension GA
az ml workspace outbound-rule show

Show details for a managed network outbound rule for a workspace.

 Extension GA
az ml workspace provision-network

Provision workspace managed network.

 Extension GA
az ml workspace show

Show details for a workspace.

 Extension GA
az ml workspace sync-keys

Sync workspace keys for dependent resources such as Azure Storage, Azure Container Registry, and Azure Application Insights.

 Extension GA
az ml workspace update

Update a workspace.

 Extension GA

az ml workspace create

Create a workspace.

When a workspace is created, several Azure resources that will be used by Azure ML also get created by default: Azure Storage, Azure Container Registry, Azure Key Vault, and Azure Application Insights. You can instead use existing Azure resource instances for those when creating the workspace by specifying the resource IDs in the workspace configuration YAML file.

az ml workspace create --resource-group
                       [--application-insights]
                       [--container-registry]
                       [--description]
                       [--display-name]
                       [--enable-data-isolation]
                       [--file]
                       [--image-build-compute]
                       [--key-vault]
                       [--location]
                       [--managed-network]
                       [--name]
                       [--no-wait]
                       [--primary-user-assigned-identity]
                       [--public-network-access]
                       [--set]
                       [--storage-account]
                       [--tags]
                       [--update-dependent-resources]
                       [--workspace-hub]

Examples

Create a workspace from a YAML specification file.

az ml workspace create --file workspace.yml --resource-group my-resource-group

Required Parameters

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--application-insights -a

ARM id of the application insights associated with this workspace.

--container-registry -c

ARM id of the container registry associated with this workspace.

--description

Description of the Azure ML workspace.

--display-name

Display name for the workspace.

--enable-data-isolation -e

A flag to determine if a workspace has data isolation enabled. The flag can only be set at the creation stage, it can't be updated.

default value: False
--file -f

Local path to the YAML file containing the Azure ML workspace specification. The YAML reference docs for workspace can be found at: https://aka.ms/ml-cli-v2-workspace-yaml-reference.

--image-build-compute -i

The name of the compute target to use for building environment Docker images when the container registry is behind a VNet.

--key-vault -k

ARM id of the key vault associated with this workspace.

--location -l

The location to be used for the new workspace.

--managed-network -m
Preview

Managed Network Isolation Mode for the workspace.

--name -n

Name of the Azure ML workspace.

--no-wait

Do not wait for workspace creation to finish.

default value: False
--primary-user-assigned-identity -p

ARM identifier of primary user assigned managed identity, in case multiple ones are specified. Also the default managed identity for clusterless compute.

--public-network-access

Allow public endpoint connectivity when a workspace is private link enabled.

--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=.

--storage-account -s

ARM id of the storage account associated with this workspace.

--tags

Space-separated key-value pairs for the tags of the object.

--update-dependent-resources -u

Specifying --update_dependent_resources, gives your consent to update the workspace dependent resources. Updating the workspace-attached Azure Container Registry or Application Insights resource may break lineage of previous jobs, deployed inference endpoints, or your ability to rerun earlier jobs in this workspace.

default value: False
--workspace-hub
Preview

An ARM ID provided to create a workspace, the workspace becomes a project workspace and all dependent resources are used from the WorkspaceHub.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml workspace delete

Delete a workspace.

By default the dependent resources associated with the workspace (Azure Storage, Azure Container Registry, Azure Key Vault, Azure Application Insights) are not deleted. To delete those as well, include --all-resources. To permanently delete the workspace, include --permanently-delete.

az ml workspace delete --name
                       --resource-group
                       [--all-resources]
                       [--no-wait]
                       [--permanently-delete]
                       [--yes]

Required Parameters

--name -n

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--all-resources

Delete all the dependent resources associated with the workspace (Azure Storage account, Azure Container Registry, Azure Application Insights, Azure Key Vault).

default value: False
--no-wait

Do not wait for the long-running-operation to finish. Default is False.

default value: False
--permanently-delete -p

Workspaces are soft-deleted state by default to allow recovery of workspace data. Set this flag to override the soft-delete behavior and permanently delete your workspace.

default value: False
--yes -y

Do not prompt for confirmation.

default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml workspace diagnose

Diagnose workspace setup problems.

If your workspace is not working as expected, you can run this diagnosis to check if the workspace has been broken. For private endpoint workspace, it will also help check out if the network setup to this workspace and its dependent resource has problem or not.

az ml workspace diagnose --name
                         --resource-group
                         [--no-wait]

Examples

diagnose a workspace.

az ml workspace diagnose --name my-workspace-name --no-wait -g my-resource-group

Required Parameters

--name -n

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--no-wait

Do not wait for the long-running-operation to finish. Default is False.

default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml workspace list

List all the workspaces in a subscription.

The list of workspaces can be filtered by resource group.

az ml workspace list [--max-results]
                     [--resource-group]

Examples

List all the workspaces in a resource group

az ml workspace list --resource-group my-resource-group

List all the workspace using --query argument to execute a JMESPath query on the results of commands.

az ml workspace list --query "[].{Name:name}"  --output table --resource-group my-resource-group

Optional Parameters

--max-results -r

Max number of results to return.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml workspace list-keys

List workspace keys for dependent resources such as Azure Storage, Azure Container Registry, and Azure Application Insights.

az ml workspace list-keys --name
                          --resource-group

Required Parameters

--name -n

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml workspace provision-network

Provision workspace managed network.

Triggers the workspace to provision the managed network. Specifying spark enabled flag prepares the workspace managed network for supporting Spark. The default is false if not specified but can be enabled later by running this command again with this flag. Once enabled it cannot be disabled.

az ml workspace provision-network --name
                                  --resource-group
                                  [--include-spark]
                                  [--no-wait]

Examples

provision managed network.

az ml workspace provision-network --include-spark --name my-workspace-name --no-wait -g my-resource-group

Required Parameters

--name -n

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--include-spark

Boolean [true/false] for if managed network should be provisioned to account for spark jobs. The default is false if flag not set. It can be enabled later by running this command again with this flag.

default value: False
--no-wait

Do not wait for the long-running-operation to finish. Default is False.

default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml workspace show

Show details for a workspace.

az ml workspace show --name
                     --resource-group

Required Parameters

--name -n

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml workspace sync-keys

Sync workspace keys for dependent resources such as Azure Storage, Azure Container Registry, and Azure Application Insights.

If the keys for any resource in the workspace are changed, it can take around an hour for them to automatically be updated. This command triggers the workspace to immediately synchronize keys. A possible scenario is needing immediate access to storage after regenerating the storage keys.

az ml workspace sync-keys --name
                          --resource-group
                          [--no-wait]

Required Parameters

--name -n

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--no-wait

Do not wait for the long-running-operation to finish. Default is False.

default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az ml workspace update

Update a workspace.

The 'description', 'tags', and 'friendly_name' properties can be updated.

az ml workspace update --name
                       --resource-group
                       [--add]
                       [--application-insights]
                       [--container-registry]
                       [--description]
                       [--display-name]
                       [--file]
                       [--force-string]
                       [--image-build-compute]
                       [--managed-network]
                       [--no-wait]
                       [--primary-user-assigned-identity]
                       [--public-network-access]
                       [--remove]
                       [--set]
                       [--update-dependent-resources]

Examples

update a workspace from a YAML specification file.

az ml workspace update --resource-group my-resource-group --name my-workspace-name --file workspace.yml

Required Parameters

--name -n

Name of the Azure ML workspace. You can configure the default workspace using az configure --defaults workspace=<name>.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--add

Add an object to a list of objects by specifying a path and key value pairs. Example: --add property.listProperty <key=value, string or JSON string>.

default value: []
--application-insights -a

ARM id of the application insights associated with this workspace.

--container-registry -c

ARM id of the container registry associated with this workspace.

--description

Description of the Azure ML workspace.

--display-name

Display name for the workspace.

--file -f

Local path to the YAML file containing the Azure ML workspace specification. The YAML reference docs for workspace can be found at: https://aka.ms/ml-cli-v2-workspace-yaml-reference.

--force-string

When using 'set' or 'add', preserve string literals instead of attempting to convert to JSON.

default value: False
--image-build-compute -i

The name of the compute target to use for building environment Docker images when the container registry is behind a VNet.

--managed-network -m
Preview

Managed Network Isolation Mode for the workspace.

--no-wait

Do not wait for the long-running-operation to finish. Default is False.

default value: False
--primary-user-assigned-identity -p

ARM id of the primary user assigned identity associated with this workspace.

--public-network-access

Allow public endpoint connectivity when a workspace is private link enabled.

--remove

Remove a property or an element from a list. Example: --remove property.list <indexToRemove> OR --remove propertyToRemove.

default value: []
--set

Update an object by specifying a property path and value to set. Example: --set property1.property2=<value>.

default value: []
--update-dependent-resources -u

Specifying --update_dependent_resources, gives your consent to update the workspace dependent resources. Updating the workspace-attached Azure Container Registry or Application Insights resource may break lineage of previous jobs, deployed inference endpoints, or your ability to rerun earlier jobs in this workspace.

default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

accepted values: json, jsonc, none, table, tsv, yaml, yamlc
default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.