Setting up team billing in Terra on Azure (admins)

Step-by-step instructions for team finance admins (with access to the Azure subscription that will cover cloud costs) to set up cloud billing for Terra on Azure. Once you go through these steps, you will be able to set up workspaces to store and analyze data in Terra.

Steps to set up billing (admins)

Before you start: Prerequisites

Make sure to have these in place before trying to follow the instructions below.

• You are a member of at least one organization’s subscriptions in the Microsoft Azure Portal.
• The Azure subscription has the following resource providers enabled:
  • "Microsoft.Storage"
  • "Microsoft.Compute"
  • "Microsoft.Authorization"
  • "Microsoft.Batch"
  • "Microsoft.OperationalInsights"
  • "Microsoft.OperationsManagement"
  • "Microsoft.Insights"
  • "Microsoft.Network"
  • "Microsoft.DBforPostgreSQL"
  • "Microsoft.ContainerRegistry"
  • "Microsoft.KeyVault"
  • "Microsoft.ContainerService"
  • "Microsoft.Relay"

Terra requires a US-based subscription Currently, a US-based subscription is needed to deploy the Terra AMA (Azure Marketplace Application.)

Step 1: Create an Azure Managed Application

1.1. Go to the Managed Application Marketplace in the Azure portal under your subscription.

1.2. Search for the Terra application. The application can also be found under the Analytics or “Compute” categories or by searching for “The Broad Institute” publisher name in the marketplace.

1.3. Click on the Terra application and then click Create.

Screenshot of Terra application in Azure portal

1.4. Enter the required information in the creation wizard.

Screenshot of creation wizard

Required information details

• Subscription: The Azure subscription to bill to.
• Resource Group: The parent collection of resources that the Terra application will belong to. This can be a new group or an existing one within the subscription.

• Location: The region where the Terra application and its resources will be located.

  Location caveatsIf you have data residency requirements Note that this is the region where all data - including data in tables and in workspace blob storage - will be stored.
  
  Note that Terra on Azure currently only supports East US region.

• Authorized Terra User: The email of the Terra user who will link a Terra billing project to this managed application. This can be a comma separated list of multiple email addresses.
  NOTE: This could be the IT/Finance admin setting up billing, or you may designate a different person to set up on the Terra side (team lead or PI).
• Application Name and Managed Resource Group: These are user-configurable values that refer back to the Terra application within the Azure portal.

1.5. Click Review and Create, accept the license terms, and then click Create.

It can take an hour or two to deploy the application We recommend waiting at least an hour before proceeding to the next step. If you run into problems following the next steps, wait another hour or two before contacting support.

Step 2: Connect Terra to the Azure Managed Application

Note that if you haven’t yet registered for a Terra account, you will need to register first.

2.1. Once the managed app has been deployed in the Azure portal, click Go to Resource to go to the managed application home page to connect Terra (step 2 below).

2.2. Once you are at https://app.terra.bio, click on the three parallel lines at the top left (1), click "LOG IN" (2), and sign in with your Microsoft credentials (3).

2.3. Navigate to the billing page (click the three horizontal lines at the top left and expand the menu under your name), click the Create button, and select Azure Billing Project.

2.4. Follow the steps to link your Azure Subscription to Terra. Enter an Azure subscription ID, add additional users (optional), and enter a Billing Project name in the form to create a new Terra Billing Project.

Finding the subscription ID

You'll find the subscription on the Azure Managed Application homepage shown in Part 1, Step 7

If you don’t see the Azure Managed ApplicationMake sure your email address matches the “Authorized Terra User” entered in Step 1.4.

Colleagues don’t need to be on the Billing Project to collaborate It’s always best to start by giving colleagues minimal access and grant additional permissions as needed. The admin or PI who sets up billing can create workspaces and add collaborators as co-owners or writers. How you share funding, data, and analysis tools ultimately depends on your group's needs.

2.5. Click the Create button. You should now see the Azure Terra Billing Project in the list to the left.

This operation takes approximately 15 minutes to completeYou’ll see a loading spinner next to the project to indicate progress. This is when you start to accrue the fixed workbench infrastructure cost ($5/day).

Next steps: Set up workspaces/team access

You can now use the Terra Billing project to create workspaces where your team can collaborate in Terra.

To try out working in Terra

Check out the Bulk and Single cell RNASeq with Bioconductor Featured Workspace. 

See How to create or clone a workspace for step-by-step instructions.

Once you create a workspace, you can add colleagues who can work collaboratively.

Shared workspace concepts to consider

• Sharing workspaces is a way to share a funding source that gives less control to individual team members.
• All workspace costs are paid by the linked Azure Marketplace subscription via the associated Terra Billing project.
• The workspace owner (creator) controls exactly what each collaborator can do in the workspace (i.e., reader, writer, owner roles).
  For a detailed description of shared workspace roles, see ToA draft: Sharing data and tools (workspace permissions)
• Collaborators can only accrue costs (run an analysis or store or egress data) if the workspace owner gives sufficient workspace permission.
• Colleagues cannot create workspaces of their own unless they are on a Terra Billing project.

Controlling cost and access

Owners have fine-grained control of what collaborators in a shared workspace are able to do. When you share the workspace, you give each person or managed group reader, writer, or owner access.

For more details, see Sharing data and tools (workspace permissions).