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

az ml workspace create

Create a workspace.
az ml workspace delete

Delete a workspace.
az ml workspace diagnose

Diagnose workspace setup problems.
az ml workspace list

List all the workspaces in a subscription.
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 outbound-rule

Manage outbound rules for the managed network of an Azure ML workspace.
az ml workspace outbound-rule list

List all the managed network outbound rules for a workspace.
az ml workspace outbound-rule remove

Remove an outbound rule from the managed network for a workspace.
az ml workspace outbound-rule show

Show details for a managed network outbound rule for a workspace.
az ml workspace show

Show details for a workspace.
az ml workspace sync-keys

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

Update a workspace.

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]
                       [--file]
                       [--image-build-compute]
                       [--location]
                       [--managed-network]
                       [--name]
                       [--no-wait]
                       [--primary-user-assigned-identity]
                       [--public-network-access]
                       [--set]
                       [--tags]
                       [--update-dependent-resources]

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.

--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.

--location -l

The location to be used for the new workspace.

--managed-network -m

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=.

--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

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.

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

Required Parameters

--name -n

Name of the Azure ML workspace. You can configure the default group 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
--yes -y

Do not prompt for confirmation.

default value: False

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 group 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

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>.

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 group 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>.

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 group 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>.

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 group 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

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 group 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

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 OR --remove propertyToRemove.

default value: []
--set

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

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