Manage quantum workspaces with the Azure CLI

Article
08/19/2024

In this guide, learn to use the Azure Command-Line Interface (Azure CLI) to create Azure Quantum workspaces and the required resource groups and storage accounts, and start running your quantum applications in Azure Quantum.

Prerequisites

To use the Azure Quantum service, you need:

An Azure account with an active subscription. If you don’t have an Azure account, register for free and sign up for a pay-as-you-go subscription.
An Azure resource group where the quantum workspace lives.
A storage account in the resource group to be associated with the quantum workspace. Multiple workspaces can be associated with the same account.
The Azure CLI.
The Microsoft Quantum Development Kit.

Environment setup

Install the Azure CLI quantum extension. Open a command prompt and run the following command, which also upgrades the extension if a previous version is already installed:
```
az extension add --upgrade -n quantum
```
Log in to Azure using your credentials. You see a list of subscriptions associated with your account.
```
az login
```

Specify the subscription you want to use.

az account set -s <Your subscription ID>

If this is the first time creating quantum workspaces in your subscription, register the resource provider with this command:
```
az provider register --namespace Microsoft.Quantum
```

Create an Azure Quantum workspace

To create a new Azure Quantum workspace, you need to know:

The location or Azure region name where the resource will live. You can use the list of regions and their resource manager codes supported by the Azure CLI tool, for example, westus.
The resource group associated with the new workspace, for example, MyResourceGroup.
A storage account in the same resource group and subscription as the quantum workspace. It's possible to create a new storage account from the Az CLI tool, for example, MyStorageAccount.
The name of the quantum workspace to create, for example, MyQuantumWorkspace.
The list of Azure Quantum providers to use in the workspace. A provider offers a set of plans, each of them representing a plan with associated terms and conditions, costs, and quotas. To create workspaces, you need to specify the corresponding plan along with the providers, unless you want to start with the providers that offer free credit – they are automatically added to your workspace.

If you already know the provider and plan names to use in your workspace, you can skip to step four, below. If you want to start with the providers that offer free credit, you can enter the following command:

az quantum workspace create \
   -l MyLocation \
   -g MyResourceGroup \
   -w MyQuantumWorkspace \
   -a MyStorageAccount

You might be prompted to accept terms of use. Enter Y to accept the terms. Note that the -r parameter shown in step four, below, was not required.

If you need to determine which providers and plans to use, proceed as follows:

To retrieve the list of available quantum providers, use the list command (this example uses westus as the location):
```
az quantum offerings list \
     -l westus \
     -o table
```
Tip

If want to see which providers give free credit, use the --autoadd-only parameter, for example:
az quantum offerings list --autoadd-only -l westus -o table
As mentioned previously, those providers are automatically added to your workspace. You do not need to specify them with the -r parameter.
Once you determine the provider and plan to include in your workspace, you can review terms using the show-terms command (adding your MyProviderID and MyPlan as example values):
```
az quantum offerings show-terms \
     -l westus \
     -p MyProviderId \
     -k MyPlan
```
The output of the show-terms command includes a Boolean field accepted that shows whether the terms for this provider have been accepted already or not, as well as a link to the license terms to review. If you decide to accept those terms, use the accept-terms command to record your acceptance.
```
az quantum offerings accept-terms \
     -l westus \
     -p MyProviderId \
     -k MyPlan
```
Once you have reviewed and accepted all required terms and conditions, you can create your workspace using the create command, specifying a list of provider and plan combinations separated by commas, as in the following example:
```
az quantum workspace create \
     -l westus \
     -g MyResourceGroup \
     -w MyQuantumWorkspace \
     -a MyStorageAccount \
     -r "MyProvider1/MyPlan1, MyProvider2/MyPlan2"
```

Once you create a workspace, you can still add or remove providers using the Azure portal.

Change the default storage account for a quantum workspace

If you need to change the default storage account for an existing workspace, you can use the create command, specifying all the current properties along with the new storage account. The following example uses the same settings as the workspace created in the previous example:

az quantum workspace create \
   -l westus \
   -g MyResourceGroup \
   -w MyQuantumWorkspace \
   -a MyNEWStorageAccount \
   -r "MyProvider1/MyPlan1, MyProvider2/MyPlan2"

Important

This procedure actually re-creates the workspace with the new storage account. Ensure that all properties other than the storage account are exactly the same as the original, otherwise a second workspace is created.

Delete a quantum workspace

If you know the name and resource group of a quantum workspace you want to delete, you can do it with the delete command (using the same names as the previous example):

az quantum workspace delete \
   -g MyResourceGroup \
   -w MyQuantumWorkspace

Tip

If you don't remember the exact name, you can view the entire list of quantum workspaces in your subscription using az quantum workspace list -o table.

After you delete a workspace, it is still listed while it's being deleted in the cloud. However, the provisioningState property of the workspace changes immediately to indicate that it's being deleted. You can see this information by using the show command:

az quantum workspace show \
   -g MyResourceGroup \
   -w MyQuantumWorkspace

Note

In case you used the az quantum workspace set command previously to specify a default quantum workspace, then you can call the delete command without parameters to delete (and clear) the default workspace.

az quantum workspace delete

Next steps

Now that you can create and delete workspaces, learn about the different targets to run quantum algorithms in Azure Quantum.

Share via