How to set up 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)

Terra can only be deployed to US regionsTerra is available in the global Azure marketplace. Currently, the Terra AMA (Azure Marketplace Application) can only be deployed to US regions.

Step 1: Set Azure subscription prerequisites

Before you can create the Terra Azure Managed Application, you must be a member of at least one organization’s subscription in the Microsoft Azure Portal.

If your organization already uses Azure

You will need to request access to an Azure Subscription you can use for working in Terra from your IT admin.

If your organization is new to Azure

To create an account and get started using Azure, see Azure documentation here.

Subscription prerequisites 

To work with Terra, your Azure subscription must have a number of resource providers enabled. Terra uses these resource providers to interface with Azure on your behalf (for example, for authentication, to set up storage and compute, and access cost information).

Some of these may already be enabled. Others may be disabled by your organization by default, and you will have to get admin approval to override. For additional guidance, see Additional Resources below.

Resource providers that must be 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"
• "Microsoft.ManagedIdentity"

Additional resources

• For more information about what each resource does, see Microsoft’s documentation on Matching resource providers to service.
• For more information on how Terra uses your data, see Terra’s Terms of Service.
• For more information on data privacy and security, see Terra's Security Posture.

Step 2: Create the Azure Managed Application

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

2.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.

Troubleshooting: If you cannot find the Terra ApplicationYou may need to explicitly add the Terra B2C tenant to your Azure tenant as an Enterprise Application.

What to do
Go to Home > Enterprise Applications > Consent and Permissions and select the Allow user consent for apps radio button.

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

Screenshot of Terra application in Azure portal

2.4. Enter the required information in the creation wizard.

Screenshot of the creation wizard

Required information explanation

• 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. If you are creating a new one, it is useful to give a name that helps you easily identify the resource group. For example, if you have different resource groups in different locations, include the location in the name. 

• 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 supports South Central US,  East US, and Central US regions. The default region is South Central US.

• 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.

  Names are limited to 40 charactersNote that this cannot be validated on the marketplace side. In order to avoid problems, you will need to keep track.

2.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 3: 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.

3.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).

3.2. Once you are at https://app.terra.bio, (1) click on the three parallel lines at the top left,(2) click LOG IN, and(3) sign in with the Microsoft credentials for the Authorized Terra User (from 2.4 above).

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

3.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 step 3.1. 

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.

3.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).

Troubleshooting

If you get an error message that includes the phrase “Missing required providers,” you will need to go back and make sure the indicated providers are enabled. These may be disabled by default for your organization. If so, you will need to ask to have them enabled.

What to do

See Step 1: Set up Azure subscription prerequisites for additional guidance.

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 Terra on Azure Featured Workspaces.
• 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 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 (writer or owner).
• 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).