Edit

Manage quantum workspaces with the Azure Resource Manager

  • Article

In this guide, learn to use an Azure Resource Manager template (ARM template) or a Bicep template to create Azure Quantum workspaces and the required resource groups and storage accounts. After template deployment, you can start running your quantum applications in Azure Quantum. Treating your infrastructure as code enables you to track changes to your infrastructure requirements and makes your deployments more consistent and repeatable.

An ARM template is a JavaScript Object Notation (JSON) file that defines the infrastructure and configuration for your project. The template uses declarative syntax. In declarative syntax, you describe your intended deployment without writing the sequence of programming commands to create the deployment. Bicep uses a declarative syntax that you treat like application code. If you're familiar with the JSON syntax for writing Azure Resource Manager templates (ARM templates), you'll find that Bicep provides a more concise syntax and improved type safety. In fact, Bicep files compile to standard ARM templates.

Prerequisites

Azure account

Before you begin, you must have 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.

Editor

To create ARM or Bicep templates, you need a good editor. We recommend Visual Studio Code with the Resource Manager Tools extension. If you need to install these tools, see Quickstart: Create ARM templates with Visual Studio Code.

Command-line deployment

You also need either Azure PowerShell or Azure CLI to deploy the template. If you use Azure CLI, you must have the latest version. For the installation instructions, see:

Sign in to Azure

After installing either Azure PowerShell or Azure CLI, make sure you sign in for the first time. Choose one of the following tabs and run the corresponding command line commands to sign in to Azure:

az login

If you have multiple Azure subscriptions, select the subscription you want to use. Replace SubscriptionName with your subscription name. You can also use the subscription ID instead of the subscription name.

az account set --subscription SubscriptionName

Create an empty resource group

When you deploy a template, you specify a resource group that will contain the quantum workspace with its associated resources. Before running the deployment command, create the resource group with either Azure CLI or Azure PowerShell.

az group create --name myResourceGroup --location "East US"

Review the template

@description('Application name used as prefix for the Azure Quantum workspace and its associated Storage account.')
param appName string

@description('Location of the Azure Quantum workspace and its associated Storage account.')
@allowed([
  'eastus'
  'japaneast'
  'japanwest'
  'northeurope'
  'uksouth'
  'ukwest'
  'westcentralus'
  'westeurope'
  'westus'
  'westus2'
])
param location string

var quantumWorkspaceName = '${appName}-ws'
var storageAccountName = '${appName}${substring(uniqueString(resourceGroup().id), 0, 5)}'


resource storageAccount 'Microsoft.Storage/storageAccounts@2021-06-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
}

resource quantumWorkspace 'Microsoft.Quantum/Workspaces@2019-11-04-preview' = {
  name: quantumWorkspaceName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  properties: {
    providers: [
      {
        providerId: 'Microsoft'
        providerSku: 'DZH3178M639F'
        applicationName: '${quantumWorkspaceName}-Microsoft'
      }
    ]
    storageAccount: storageAccount.id
  }
}

resource roleAssignment 'Microsoft.Authorization/roleAssignments@2020-04-01-preview' = {
  scope: storageAccount
  name: guid(quantumWorkspace.id, '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c', storageAccount.id)
  properties: {
    roleDefinitionId: '/subscriptions/${subscription().subscriptionId}/providers/Microsoft.Authorization/roleDefinitions/b24988ac-6180-42a0-ab88-20f7382dd24c'
    principalId: reference(quantumWorkspace.id, '2019-11-04-preview', 'full').identity.principalId
  }
}

output subscription_id string = subscription().subscriptionId
output resource_group string = resourceGroup().name
output name string = quantumWorkspace.name
output location string = quantumWorkspace.location
output tenant_id string = subscription().tenantId

The following Azure resources are created by both templates:

The templates also grant the quantum workspace Contributor-permissions to the storage account. This step is needed so that the workspace can read and write job data.

Both templates generate following output. You can use these values later to identify the generated quantum workspace and authenticate to it:

  • Subscription ID hosting all the deployed resources.
  • Resource Group containing all deployed resources.
  • Name of the quantum workspace.
  • Location of the datacenter that hosts the workspace.
  • Tenant ID holding credentials used at the deployment.

Deploy the template

To deploy the template, use either Azure CLI or Azure PowerShell. Use the resource group you created. Give a name to the deployment so you can easily identify it in the deployment history. Replace {provide-the-path-to-the-template-file} and the curly braces {} with the path to your template file. Furthermore, replace {provide-app-name} and {provide-location} with values for the overall application name and the location where the workspace should reside. The app name should only contain letters.

To run this deployment command, you must have the latest version of Azure CLI.

templateFile="{provide-the-path-to-the-template-file}"
az deployment group create \
  --name myDeployment \
  --resource-group myResourceGroup \
  --template-file $templateFile \
  --parameters appName="{provide-app-name}" location="{provide-location}"

The deployment command returns results. Look for ProvisioningState to see whether the deployment succeeded.

Important

In some cases you might get a deployment error (Code: PrincipalNotFound). Reason for this is that the workspace principal was not created yet when the resource manager tried to configure the role assignment. If this is the case, just repeat the deployment. It should succeed in the second run.

Validate the deployment

You can verify the deployment by exploring the resource group from the Azure portal.

  1. Sign in to the Azure portal.

  2. From the left menu, select Resource groups.

  3. Select the resource group deploy in the last procedure. The default name is myResourceGroup. You should see two resources deployed within the resource group - the storage account and the quantum workspace.

  4. Verify that the quantum workspace has necessary access rights for the storage account. Select the storage account. In the left menu pane, select Access Control (IAM) and verify that under Role assignments the quantum workspace resource is listed under Contributor.

Clean up resources

If you no longer need the quantum workspace, you might want to delete the resource group.

az group delete --name myResourceGroup

Next steps

Now that you can create and delete workspaces, learn about the different targets to run quantum algorithms in Azure Quantum. You now also have the tools to do workspace deployments from within Azure Pipelines or GitHub Actions.