Detailed instructions for steps 2 and 3 to set up cloud billing for Terra on Azure. This article is for team finance admins or those with access to the Azure subscription that will cover cloud costs. Once you go through these steps, you will be able to set up workspaces to store and analyze data in Terra.
Before you startTerra on Azure is available for private use by Enterprises who require deeper integration with Azure, and by individuals with specific reasons to use Azure.
Currently, setting up Terra on Azure is not a self-serve process. Please contact terra-enterprise@broadinstitute.org before following the steps below.
Steps to set up billing (admins)
Terra on Azure supports several regions (with more coming soon!)
Terra is available in the global Azure marketplace and all your resources will be created in the region you specify when deploying your Terra Environment. The Terra AMA (Azure Marketplace Application) can be deployed to the following regions.
Central US
| East US
| South Africa North
| South Central US
| West US 2
| UAE North
The default (preferred) region is South Central US
. NOTE: You will need to select from the dropdown (there is no default region). If you need to deploy Terra on Azure to a different region, please contact support (support@terra.bio).
Step 2: Create the Azure Managed Application
Do you have all prerequisites in place?Note that you should make sure to have set your prerequisites (step 1) before following the steps 2 and 3 below. For details and step-by-step instructions, see Setting up billing (Azure prerequisites).
2.1. Go to the Terra application in the Managed Application Marketplace in the Azure portal under your subscription.
-
How to search the marketplace
The application can also be found under the Analytics or Compute categories or by searching for The Broad Institute publisher name in the marketplace.
If you still cannot find the Terra Application
You may need to explicitly add the Terra B2C tenant to your Azure tenant as an Enterprise Application.
Go to Home > Enterprise Applications > Consent and Permissions and select the Allow user consent for apps radio button.
2.2. Click on the Terra application and then click Create to surface the Terra application in Azure portal (screenshot below).
2.3. Enter the required information in the creation wizard.
Screenshot of the creation wizard
Required information guidance
- 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 caveats: If you have data residency requirementsNote that this is the region where all data - including data in tables and in workspace blob storage - will be stored.
The preferred region isSouth Central US
(note that you will have to select from an alphabetical list in the dropdown). Terra also supports Central US, West US 2, East US, UAE North, and South Africa North. If you need to deploy Terra on Azure to a different region, please contact support (support@terra.bio). -
Authorized Terra User: The email of the Terra user who will link a Terra billing project to this managed application. 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). You can use a comma-separated list of multiple email addresses.
Microsoft and Google Authorized Terra UsersAn Authorized Terra User can be any active Terra account user, regardless of whether they use Microsoft or Google to sign into Terra. Note that this role is used during setup only. In other words, you can designate a billing/IT admin as the authorized user for this process, but they need not have access to data or tools down the line.
-
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.4. 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, please wait another hour or two before contacting support.
Note that the Terra Managed Application will be empty when you first deploy it to the Azure Portal.
Step 3: Connect Terra to the Azure Managed Application
If you haven’t yet registered for a Terra account, you will need to register before you can complete the steps below.
3.1. Wait until the managed app has been deployed in the Azure portal.
3.2. Go to the Terra Billing page (https://app.terra.bio/#billing) and sign in with the credentials for the Authorized Terra User (from 2.3 above).
3.3. Click the Create button, and 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). This will simultaneously create a new Terra Billing project and your own Terra Environment.
Finding the subscription ID
You'll find the subscription on the Azure Managed Application homepage. To get to that from the deployment page displayed in Step 3.1, click Go to Resource. Then you will see the Subscription ID like this:
If you don’t see the Azure Managed Application Make 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. In the Billing Page, you should now see the Azure-backed 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 ($10/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 Setting up Billing: Azure subscription prerequisites for additional guidance.
Next steps: Set up workspaces/team access
Terra Billing project users can now create workspaces where your team can collaborate under your Terra Billing project (Terra Environment instance).
Working in a shared workspace versus creating workspaces
- 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).
- Sharing workspaces is a way to share a funding source that gives less control to individual team members. Colleagues in a shared workspace can perform actions with a cost (store data, run analyses) but cannot create workspaces (which have automatic infrastructure costs).
- 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).
To try out working in Terra
- Check out Terra on Azure Featured Workspaces to create your own template workspace to practice in.
- 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.