CLI (v2) workspace YAML schema

Article
08/28/2024

APPLIES TO: Azure CLI ml extension v2 (current)

The source JSON schema can be found at https://azuremlschemas.azureedge.net/latest/workspace.schema.json.

Note

The YAML syntax detailed in this document is based on the JSON schema for the latest version of the ML CLI v2 extension. This syntax is guaranteed only to work with the latest version of the ML CLI v2 extension. You can find the schemas for older extension versions at https://azuremlschemasprod.azureedge.net/.

YAML syntax

Key	Type	Description	Allowed values	Default value
`$schema`	string	The YAML schema. If you use the Azure Machine Learning VS Code extension to author the YAML file, including `$schema` at the top of your file enables you to invoke schema and resource completions.
`name`	string	Required. Name of the workspace.
`display_name`	string	Display name of the workspace in the studio UI. Can be non-unique within the resource group.
`description`	string	Description of the workspace.
`tags`	object	Dictionary of tags for the workspace.
`location`	string	The location of the workspace. If omitted, defaults to the resource group location.
`resource_group`	string	Required. The resource group containing the workspace. If the resource group does not exist, a new one will be created.
`hbi_workspace`	boolean	Whether the customer data is of high business impact (HBI), containing sensitive business information. For more information, see Data encryption at rest.		`false`
`storage_account`	string	The fully qualified resource ID of an existing Azure storage account to use as the default storage account for the workspace. A storage account with premium storage or hierarchical namespace cannot be used as the default storage account. If omitted, a new storage account will be created.
`container_registry`	string	The fully qualified resource ID of an existing Azure container registry to use as the default container registry for the workspace. Azure Machine Learning uses Azure Container Registry (ACR) for managing container images used for training and deployment. If omitted, a new container registry will be created. Creation is lazy loaded, so the container registry gets created the first time it is needed for an operation for either training or deployment.
`key_vault`	string	The fully qualified resource ID of an existing Azure key vault to use as the default key vault for the workspace. If omitted, a new key vault will be created.
`application_insights`	string	The fully qualified resource ID of an existing Azure application insights to use as the default application insights for the workspace. If omitted, a new application insights will be created.
`customer_managed_key`	object	Azure Machine Learning stores metadata in an Azure Cosmos DB instance. By default the data is encrypted at rest with Microsoft-managed keys. To use your own customer-managed key for encryption, specify the customer-managed key information in this section. For more information, see Data encryption for Azure Cosmos DB.
`customer_managed_key.key_vault`	string	The fully qualified resource ID of the key vault containing the customer-managed key. This key vault can be different than the default workspace key vault specified in `key_vault`.
`customer_managed_key.key_uri`	string	The key URI of the customer-managed key to encrypt data at rest. The URI format is `https://<keyvault-dns-name>/keys/<key-name>/<key-version>`.
`image_build_compute`	string	Name of the compute target to use for building environment Docker images when the container registry is behind a VNet. For more information, see Secure workspace resources behind VNets.
`public_network_access`	string	Whether public endpoint access is allowed if the workspace will be using Private Link. For more information, see Enable public access when behind VNets.	`enabled`, `disabled`	`disabled`
`managed_network`	object	Azure Machine Learning Workspace managed network isolation. For more information, see Workspace managed network isolation.

Remarks

The az ml workspace command can be used for managing Azure Machine Learning workspaces.

Examples

Examples are available in the examples GitHub repository. Several are shown below.

YAML: basic

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-basic-prod
location: eastus
display_name: Basic workspace-example
description: This example shows a YML configuration for a basic workspace. In case you use this configuration to deploy a new workspace, since no existing dependent resources are specified, these will be automatically created.
hbi_workspace: false
tags:
  purpose: demonstration

YAML: with existing resources

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-basicex-prod
location: eastus
display_name: Bring your own dependent resources-example
description: This configuration specifies a workspace configuration with existing dependent resources
storage_account: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.Storage/storageAccounts/<STORAGE_ACCOUNT>
container_registry: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerRegistry/registries/<CONTAINER_REGISTRY>
key_vault: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT>
application_insights: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.insights/components/<APP_INSIGHTS>
tags:
  purpose: demonstration

YAML: customer-managed key

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-cmkexample-prod
location: eastus
display_name: Customer managed key encryption-example
description: This configurations shows how to create a workspace that uses customer-managed keys for encryption.
customer_managed_key: 
  key_vault: /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEY_VAULT>
  key_uri: https://<KEY_VAULT>.vault.azure.net/keys/<KEY_NAME>/<KEY_VERSION>
tags:
  purpose: demonstration

YAML: private link

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-privatelink-prod
location: eastus
display_name: Private Link endpoint workspace-example
description: When using private link, you must set the image_build_compute property to a cluster name to use for Docker image environment building. You can also specify whether the workspace should be accessible over the internet.
image_build_compute: cpu-compute
public_network_access: Disabled
tags:
  purpose: demonstration

YAML: high business impact

$schema: https://azuremlschemas.azureedge.net/latest/workspace.schema.json
name: mlw-hbiexample-prod
location: eastus
display_name: High business impact-example
description: This configuration shows how to configure a workspace with the hbi flag enabled. This flag specifies whether to reduce telemetry collection and enable additional encryption when high-business-impact data is used.
hbi_workspace: true
tags:
  purpose: demonstration

YAML: managed network with allow internet outbound

name: myworkspace_aio
managed_network:
  isolation_mode: allow_internet_outbound
  outbound_rules:
  - name: added-perule
    type: private_endpoint
    destination:
      service_resource_id: /subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/MyGroup/providers/Microsoft.Storage/storageAccounts/MyAccount1
      spark_enabled: true
      subresource_target: blob
  - name: added-perule2
    type: private_endpoint
    destination:
      service_resource_id: /subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/MyGroup/providers/Microsoft.Storage/storageAccounts/MyAccount2
      spark_enabled: true
      subresource_target: file

YAML: managed network with allow only approved outbound

name: myworkspace_dep
managed_network:
  isolation_mode: allow_only_approved_outbound
  outbound_rules:
  - name: added-servicetagrule
    type: service_tag
    destination:
      port_ranges: 80, 8080
      protocol: TCP
      service_tag: DataFactory
  - name: added-perule
    type: private_endpoint
    destination:
      service_resource_id: /subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/MyGroup/providers/Microsoft.Storage/storageAccounts/MyAccount2
      spark_enabled: true
      subresource_target: blob
  - name: added-fqdnrule
    type: fqdn
    destination: 'test2.com'

Next steps

Install and use the CLI (v2)

Share via