Tutorial: How to create a secure workspace by using template

Templates provide a convenient way to create reproducible service deployments. The template defines what will be created, with some information provided by you when you use the template. For example, specifying a unique name for the Azure Machine Learning workspace.

In this tutorial, you learn how to use a Microsoft Bicep and Hashicorp Terraform template to create the following Azure resources:

• Azure Virtual Network. The following resources are secured behind this VNet:
  • Azure Machine Learning workspace
    • Azure Machine Learning compute instance
    • Azure Machine Learning compute cluster
  • Azure Storage Account
  • Azure Key Vault
  • Azure Application Insights
  • Azure Container Registry
  • Azure Bastion host
  • Azure Machine Learning Virtual Machine (Data Science Virtual Machine)
  • The Bicep template also creates an Azure Kubernetes Service cluster, and a separate resource group for it.

Tip

Microsoft recommends using an Azure Machine Learning managed virtual networks instead of the steps in this article. With a managed virtual network, Azure Machine Learning handles the job of network isolation for your workspace and managed computes. You can also add private endpoints for resources needed by the workspace, such as Azure Storage Account. For more information, see Workspace managed network isolation.

Prerequisites

Before using the steps in this article, you must have an Azure subscription. If you don't have an Azure subscription, create a free account.

You must also have either a Bash or Azure PowerShell command line.

Tip

When reading this article, use the tabs in each section to select whether to view information on using Bicep or Terraform templates.

Bicep

1. To install the command-line tools, see Set up Bicep development and deployment environments.

2. The Bicep template used in this article is located at https://github.com/Azure/azure-quickstart-templates/blob/master/quickstarts/microsoft.machinelearningservices/machine-learning-end-to-end-secure. Use the following commands to clone the GitHub repo to your development environment:

   Tip

   If you do not have the git command on your development environment, you can install it from https://git-scm.com/.

   git clone https://github.com/Azure/azure-quickstart-templates
   cd azure-quickstart-templates/quickstarts/microsoft.machinelearningservices/machine-learning-end-to-end-secure
   

Terraform

1. To install, configure, and authenticate Terraform to your Azure subscription, use the steps in one of the following articles:

   • Azure Cloud Shell
   • Windows with Bash
   • Windows with Azure PowerShell

2. The Terraform template files used in this article are located at https://github.com/Azure/terraform/tree/master/quickstart/201-machine-learning-moderately-secure. To clone the repo locally and change directory to where the template files are located, use the following commands from the command line:

   Tip

   If you do not have the git command on your development environment, you can install it from https://git-scm.com/.

   git clone https://github.com/Azure/terraform
   cd terraform/quickstart/201-machine-learning-moderately-secure
   

Understanding the template

Bicep

The Bicep template is made up of the main.bicep and the .bicep files in the modules subdirectory. The following table describes what each file is responsible for:

File	Description
main.bicep	Parameters and variables. Passing parameters & variables to other modules in the modules subdirectory.
vnet.bicep	Defines the Azure Virtual Network and subnets.
nsg.bicep	Defines the network security group rules for the VNet.
bastion.bicep	Defines the Azure Bastion host and subnet. Azure Bastion allows you to easily access a VM inside the VNet using your web browser.
dsvmjumpbox.bicep	Defines the Data Science Virtual Machine (DSVM). Azure Bastion is used to access this VM through your web browser.
storage.bicep	Defines the Azure Storage account used by the workspace for default storage.
keyvault.bicep	Defines the Azure Key Vault used by the workspace.
containerregistry.bicep	Defines the Azure Container Registry used by the workspace.
applicationinsights.bicep	Defines the Azure Application Insights instance used by the workspace.
machinelearningnetworking.bicep	Defines the private endpoints and DNS zones for the Azure Machine Learning workspace.
Machinelearning.bicep	Defines the Azure Machine Learning workspace.
machinelearningcompute.bicep	Defines an Azure Machine Learning compute cluster and compute instance.
privateaks.bicep	Defines an Azure Kubernetes Services cluster instance.

Important

The example templates may not always use the latest API version for Azure Machine Learning. Before using the template, we recommend modifying it to use the latest API versions. For information on the latest API versions for Azure Machine Learning, see the Azure Machine Learning REST API.

Each Azure service has its own set of API versions. For information on the API for a specific service, check the service information in the Azure REST API reference.

To update the API version, find the Microsoft.MachineLearningServices/<resource> entry for the resource type and update it to the latest version. The following example is an entry for the Azure Machine Learning workspace that uses an API version of 2022-05-01:

resource machineLearning 'Microsoft.MachineLearningServices/workspaces@2022-05-01' = {

Terraform

The template consists of multiple files. The following table describes what each file is responsible for:

File	Description
variables.tf	Variables and default values used by the template.
main.tf	Specifies the Azure Resource Manager provider and defines the resource group.
network.tf	Defines the Azure Virtual Network, subnets, and network security groups.
bastion.tf	Defines the Azure Bastion host and associated NSG. Azure Bastion allows you to easily access a VM inside a VNet using your web browser.
dsvm.tf	Defines the Data Science Virtual Machine (DSVM). Azure Bastion is used to access this VM through your web browser.
workspace.tf	Defines the Azure Machine Learning workspace. Including dependency resources for Azure Storage, Key Vault, Application Insights, and Container Registry.
compute.tf	Defines an Azure Machine Learning compute instance and cluster.

Tip

The Terraform Azure provider supports additional arguments that are not used in this tutorial. For example, the environment argument allows you to target cloud regions such as Azure Government and Microsoft Azure operated by 21Vianet.

Important

The DSVM and Azure Bastion is used as an easy way to connect to the secured workspace for this tutorial. In a production environment, we recommend using an Azure VPN gateway or Azure ExpressRoute to access the resources inside the VNet directly from your on-premises network.

Configure the template

Bicep

To run the Bicep template, use the following commands from the machine-learning-end-to-end-secure where the main.bicep file is:

1. To create a new Azure Resource Group, use the following command. Replace exampleRG with your resource group name, and eastus with the Azure region you want to use:

   Azure CLI

   az group create --name exampleRG --location eastus
   

   Azure PowerShell

   New-AzResourceGroup -Name exampleRG -Location eastus
   

2. To run the template, use the following command. Replace the prefix with a unique prefix. The prefix will be used when creating Azure resources that are required for Azure Machine Learning. Replace the securepassword with a secure password for the jump box. The password is for the login account for the jump box (azureadmin in the examples below):

   Tip

   The prefix must be 5 or less characters. It can't be entirely numeric or contain the following characters: ~ ! @ # $ % ^ & * ( ) = + _ [ ] { } \ | ; : . ' " , < > / ?.

   Azure CLI

   az deployment group create \
       --resource-group exampleRG \
       --template-file main.bicep \
       --parameters \
       prefix=prefix \
       dsvmJumpboxUsername=azureadmin \
       dsvmJumpboxPassword=securepassword
   

   Azure PowerShell

   $dsvmPassword = ConvertTo-SecureString "mysecurepassword" -AsPlainText -Force
   New-AzResourceGroupDeployment -ResourceGroupName exampleRG `
       -TemplateFile ./main.bicep `
       -prefix "prefix" `
       -dsvmJumpboxUsername "azureadmin" `
       -dsvmJumpboxPassword $dsvmPassword
   

   Warning

   You should avoid using plain text strings in script or from the command line. The plain text can show up in event logs and command history. For more information, see ConvertTo-SecureString.

Terraform

To run the Terraform template, use the following commands from the 201-machine-learning-moderately-secure directory where the template files are:

1. To initialize the directory for working with Terraform, use the following command:

   terraform init
   

2. To create a configuration, use the following command. Use the -var parameter to set the value for the variables used by the template. For a full list of variables, see the variables.tf file:

   terraform plan \
       -var name=myworkspace \
       -var environment=dev \
       -var location=westus \
       -var dsvm_name=jumpbox \
       -var dsvm_host_password=secure_password \
       -out azureml.tfplan
   

   After this command completes, the configuration is displayed in the terminal. To display it again, use the terraform show azureml.tfplan command.

3. To run the template and apply the saved configuration to your Azure subscription, use the following command:

   terraform apply azureml.tfplan
   

   The progress is displayed as the template is processed.

Connect to the workspace

After the template completes, use the following steps to connect to the DSVM:

1. From the Azure portal, select the Azure Resource Group you used with the template. Then, select the Data Science Virtual Machine that was created by the template. If you have trouble finding it, use the filters section to filter the Type to virtual machine.

   

2. From the Overview section of the Virtual Machine, select Connect, and then select Bastion from the dropdown.

   

3. When prompted, provide the username and password you specified when configuring the template and then select Connect.

   Important

   The first time you connect to the DSVM desktop, a PowerShell window opens and begins running a script. Allow this to complete before continuing with the next step.

4. From the DSVM desktop, start Microsoft Edge and enter https://ml.azure.com as the address. Sign in to your Azure subscription, and then select the workspace created by the template. The studio for your workspace is displayed.

Troubleshooting

Error: Windows computer name cannot be more than 15 characters long, be entirely numeric, or contain the following characters

This error can occur when the name for the DSVM jump box is greater than 15 characters or includes one of the following characters: ~ ! @ # $ % ^ & * ( ) = + _ [ ] { } \ | ; : . ' " , < > / ?.

When using the Bicep template, the jump box name is generated programmatically using the prefix value provided to the template. To make sure the name does not exceed 15 characters or contain any invalid characters, use a prefix that is 5 characters or less and do not use any of the following characters in the prefix: ~ ! @ # $ % ^ & * ( ) = + _ [ ] { } \ | ; : . ' " , < > / ?.

When using the Terraform template, the jump box name is passed using the dsvm_name parameter. To avoid this error, use a name that is not greater than 15 characters and does not use any of the following characters as part of the name: ~ ! @ # $ % ^ & * ( ) = + _ [ ] { } \ | ; : . ' " , < > / ?.

Next steps

Important

The Data Science Virtual Machine (DSVM) and any compute instance resources bill you for every hour that they are running. To avoid excess charges, you should stop these resources when they are not in use. For more information, see the following articles:

• Create/manage VMs (Linux).
• Create/manage VMs (Windows).
• Create compute instance.

To continue learning how to use the secured workspace from the DSVM, see Tutorial: Azure Machine Learning in a day.

To learn more about common secure workspace configurations and input/output requirements, see Azure Machine Learning secure workspace traffic flow.