Create and manage an Azure Machine Learning compute instance

Learn how to create and manage a compute instance in your Azure Machine Learning workspace.

Use a compute instance as your fully configured and managed development environment in the cloud. For development and testing, you can also use the instance as a training compute target or for an inference target. A compute instance can run multiple jobs in parallel and has a job queue. As a development environment, a compute instance cannot be shared with other users in your workspace.

In this article, you learn how to:

  • Create a compute instance
  • Manage (start, stop, restart, delete) a compute instance
  • Access the terminal window
  • Install R or Python packages
  • Create new environments or Jupyter kernels

Compute instances can run jobs securely in a virtual network environment, without requiring enterprises to open up SSH ports. The job executes in a containerized environment and packages your model dependencies in a Docker container.

Prerequisites

Create

Time estimate: Approximately 5 minutes.

Creating a compute instance is a one time process for your workspace. You can reuse this compute as a development workstation or as a compute target for training. You can have multiple compute instances attached to your workspace.

The dedicated cores per region per VM family quota and total regional quota, which applies to compute instance creation, is unified and shared with Azure Machine Learning training compute cluster quota. Stopping the compute instance does not release quota to ensure you will be able to restart the compute instance. Please note it is not possible to change the virtual machine size of compute instance once it is created.

The following example demonstrates how to create a compute instance:

import datetime
import time

from azureml.core.compute import ComputeTarget, ComputeInstance
from azureml.core.compute_target import ComputeTargetException

# Choose a name for your instance
# Compute instance name should be unique across the azure region
compute_name = "ci{}".format(ws._workspace_id)[:10]

# Verify that instance does not exist already
try:
    instance = ComputeInstance(workspace=ws, name=compute_name)
    print('Found existing instance, use it.')
except ComputeTargetException:
    compute_config = ComputeInstance.provisioning_configuration(
        vm_size='STANDARD_D3_V2',
        ssh_public_access=False,
        # vnet_resourcegroup_name='<my-resource-group>',
        # vnet_name='<my-vnet-name>',
        # subnet_name='default',
        # admin_user_ssh_public_key='<my-sshkey>'
    )
    instance = ComputeInstance.create(ws, compute_name, compute_config)
    instance.wait_for_completion(show_output=True)

For more information on the classes, methods, and parameters used in this example, see the following reference documents:

You can also create a compute instance with an Azure Resource Manager template.

Create on behalf of (preview)

As an administrator, you can create a compute instance on behalf of a data scientist and assign the instance to them with:

The data scientist you create the compute instance for needs the following be Azure role-based access control (Azure RBAC) permissions:

  • Microsoft.MachineLearningServices/workspaces/computes/start/action
  • Microsoft.MachineLearningServices/workspaces/computes/stop/action
  • Microsoft.MachineLearningServices/workspaces/computes/restart/action
  • Microsoft.MachineLearningServices/workspaces/computes/applicationaccess/action

The data scientist can start, stop, and restart the compute instance. They can use the compute instance for:

  • Jupyter
  • JupyterLab
  • RStudio
  • Integrated notebooks

Manage

Start, stop, restart and delete a compute instance. A compute instance does not automatically scale down, so make sure to stop the resource to prevent ongoing charges.

In the examples below, the name of the compute instance is instance

  • Get status

    # get_status() gets the latest status of the ComputeInstance target
    instance.get_status()
    
  • Stop

    # stop() is used to stop the ComputeInstance
    # Stopping ComputeInstance will stop the billing meter and persist the state on the disk.
    # Available Quota will not be changed with this operation.
    instance.stop(wait_for_completion=True, show_output=True)
    
  • Start

    # start() is used to start the ComputeInstance if it is in stopped state
    instance.start(wait_for_completion=True, show_output=True)
    
  • Restart

    # restart() is used to restart the ComputeInstance
    instance.restart(wait_for_completion=True, show_output=True)
    
  • Delete

    # delete() is used to delete the ComputeInstance target. Useful if you want to re-use the compute name 
    instance.delete(wait_for_completion=True, show_output=True)
    

Azure RBAC allows you to control which users in the workspace can create, delete, start, stop, restart a compute instance. All users in the workspace contributor and owner role can create, delete, start, stop, and restart compute instances across the workspace. However, only the creator of a specific compute instance, or the user assigned if it was created on their behalf, is allowed to access Jupyter, JupyterLab, and RStudio on that compute instance. A compute instance is dedicated to a single user who has root access, and can terminal in through Jupyter/JupyterLab/RStudio. Compute instance will have single-user log in and all actions will use that user’s identity for Azure RBAC and attribution of experiment runs. SSH access is controlled through public/private key mechanism.

These actions can be controlled by Azure RBAC:

  • Microsoft.MachineLearningServices/workspaces/computes/read
  • Microsoft.MachineLearningServices/workspaces/computes/write
  • Microsoft.MachineLearningServices/workspaces/computes/delete
  • Microsoft.MachineLearningServices/workspaces/computes/start/action
  • Microsoft.MachineLearningServices/workspaces/computes/stop/action
  • Microsoft.MachineLearningServices/workspaces/computes/restart/action

Access the terminal window

Open the terminal window of your compute instance in any of these ways:

  • RStudio: Select the Terminal tab on top left.
  • Jupyter Lab: Select the Terminal tile under the Other heading in the Launcher tab.
  • Jupyter: Select New>Terminal on top right in the Files tab.
  • SSH to the machine, if you enabled SSH access when the compute instance was created.

Use the terminal window to install packages and create additional kernels.

Install packages

You can install packages directly in Jupyter Notebook or RStudio:

  • RStudio Use the Packages tab on the bottom right, or the Console tab on the top left.
  • Python: Add install code and execute in a Jupyter Notebook cell.

Or you can install from a terminal window. Install Python packages into the Python 3.6 - AzureML environment. Install R packages into the R environment.

Note

For package management within a notebook, use %pip or %conda magic functions to automatically install packages into the currently-running kernel, rather than !pip or !conda which refers to all packages (including packages outside the currently-running kernel)

Add new kernels

Warning

While customizing the compute instance, make sure you do not delete the azureml_py36 conda environment or Python 3.6 - AzureML kernel. This is needed for Jupyter/JupyterLab functionality

To add a new Jupyter kernel to the compute instance:

  1. Create new terminal from Jupyter, JupyterLab or from notebooks pane or SSH into the compute instance

  2. Use the terminal window to create a new environment. For example, the code below creates newenv:

    conda create --name newenv
    
  3. Activate the environment. For example, after creating newenv:

    conda activate newenv
    
  4. Install pip and ipykernel package to the new environment and create a kernel for that conda env

    conda install pip
    conda install ipykernel
    python -m ipykernel install --user --name newenv --display-name "Python (newenv)"
    

Any of the available Jupyter Kernels can be installed.

Next steps