How to set up billing in Terra

Terra runs on the Google Cloud Platform (GCP), so you pay for all storage and analysis costs through a Google account linked to a Terra Billing Project. Once you set up your billing, Terra takes care of interfacing with GCP. In this article, you'll learn step-by-step instructions on setting up billing in Terra for different scenarios. To learn more about the structure of billing in Terra, including what costs money and who pays, see Understanding costs and billing in Terra.

There is never a charge for administration or security services covered by the Terra platform or for support, and the community forum is available 24/7 free of charge to help you.  The costs are the standard GCP fees for storing and moving data as well as executing an analysis (bulk workflow or interactive Jupyter notebook). Billing account owners can check expenses at any time on the Google Cloud Platform billing console.    

How to pay for Cloud costs in Terra

There are a few different ways to pay for Cloud costs associated with Terra. We'll walk through all the costs and how to set up the associated billing in Terra. 

Start with $300 in Google Cloud Platform (GCP) credits 

Google Cloud credits are a way to try the platform - to see if it's right for you - before committing your own money. Google offers $300 in credits to new users signing up for billing on GCP.  

Free credits detailsFor step-by-step instructions on claiming $300 of GCP dollars to use on Terra, see Set up billing with $300 Google credits to explore Terra.  Once you claim the $300 credits, you can link your Google account to Terra (step2 below), create a Terra Billing project (step 3 below), and start exploring in a new workspace. 

Free-tier users are limited to five workspaces. See Google Cloud quotas: What are they and how do you request more? for more details. 

Accessing STRIDES credits in Terra

Participants in programs such as the BioData Catalyst pilot program will have program credits through STRIDES loaded on a pre-associated Google Cloud Billing account. These credits can be used for all storage, compute and egress charges on the Terra platform.   

Once you receive notice that you have access to your STRIDES credits, you can create a Terra Billing project to use when creating or cloning a workspace on the Billing page. See below for step-by-step instructions and screenshots.

Before you start (STRIDES users) The instructions below assume you have already registered for an account on Terra, and that your Terra account has already been linked to a STRIDES billing account. See How to register for a Terra account for step-by-step instructions. 

• 1. Go to your Billing page to access your Terra billing profile.

  2. To create a new Billing Project, click the + Create button to the right of Billing projects.  
  

  3. Enter a unique name for your Terra Billing project in the modal. Note that the name cannot be changed.
  

  4. Select your STRIDES Billing Account from the dropdown menu in the modal. This is the umbrella Cloud Billing account that funds the Terra Billing project. It will have the format "NIH.NHGRI.BDC.Fellow.00X".

  5. Click on the Create Billing Project button at the bottom of the modal. It will take several minutes to complete the setup.

  You'll use this Terra Billing project when creating workspaces in Terra, and costs incurred by any work done in the workspaces will be paid for via the STRIDES Billing Account.

Terra Billing projects versus Google projectsDespite the name, Terra Billing projects and Google projects are not related. Google projects are how Google organizes all the GCP resources you use. There is one for each workspace created after September 27, 2021. Terra automatically generates a Google Project in GCP when you create a workspace. 

Terra Billing projects are an internal mechanism for tracking billing resources on Terra. You can have as many of them as you need, all linked to the same Google Cloud Billing account.

You will not see a Terra Billing project if you log into GCP console (https://console.cloud.google.com/billing/<your-billing-account-id>/manage). However, if you create a workspace, you will see the workspace Google project (format = <Terra-billing-project-name><first-letters-of-workspace-name>). 

Note that creating a project on the GCP console will not create a project in Terra. You can only create Terra Billing projects in Terra.

Collaborating with someone on Terra? Two ways to share billing 

If you are working with someone who has already set up their billing, you may be able to access their billing resources,  indirectly or directly. The two options - Collaborating in a shared workspace or using a shared Terra Billing project - are outlined below.

For more information about controlling shared lab costs, including sharing workspaces, see Best practices for managing shared team resources.

• Collaborating in a shared workspace

  Costs in Terra are billed to the workspace Billing project; it doesn't matter who does the work. If a colleague shares a workspace with you and assigns you "WRITER can-compute" access, you will be able to move data into and out of the workspace bucket, store data, and  run analyses within that workspace. All charges for these operations will be paid by your colleague's Billing project, which is assigned to the workspace when it's created.

  To learn more, see Best practices for managing shared team resources.  

• Using a shared Terra Billing project

  To create or clone a workspace of your own, you will need to have a Terra Billing Project. However, you don't necessarily need to set one up from scratch! Billing project owners can add and remove Billing project users in their Terra Billing page, so you may be able to access a colleague's already existing project. This may apply, for example, if you are joining a research group that is already working in Terra. You'll need to ask the Billing project owner to add you using the steps below.

  Once you are a designated Billing project user, the project will appear in your Billing page, and in the drop-down menu when you create a workspace. All costs incurred in the workspaces you create will be covered by the colleague's Billing project.

  To learn more about using a shared Terra Billing project, see Best practices for managing shared team resources.

  Owners can edit any user's role and delete users from a Billing project at any time by clicking on the Billing project from the list (access Billing from the User Profile drop-down in the main navigation menu at the top left).

Set up billing in Terra from scratch - in three steps

If you don't have access to shared workspaces or billing, follow three steps below to set up a Terra Billing project from scratch. Once you have a Billing project, you'll be able to create or clone a workspace where you can store data and do analyses. After setting it up, Terra will manage all GCP costs.  

 Step 1. Set up a Google Cloud Billing account

The first step is to set up a Google Cloud Billing account to pay for all GCP fees. 

• If you don't want to navigate GCP console, you can go through a third-party reseller who will do it for you.
• If you're comfortable working in GCP console, you can set up and manage a Google Cloud Billing account directly in Google Cloud Platform.
• If you are using a Broad Institute Cloud Billing account, you can request a Google Cloud Billing sub-account. 

Hint (setting up a Google Billing account) Talk to your institutional procurement office and see if they have a preferred account set-up method with Google (such as a third party reseller or an existing account). Remember to use the same Google account ID you use to log into Terra for the  Google Cloud Billing account.

• Use a third-party reseller

  This is a good option if you do not want to navigate GCP console or are new to Cloud computing. Note that the third-party reseller will be the Cloud Billing account Owner, so you may not have full access to detailed cost breakouts and spending reports in the GCP console.

  Third-party resellers can facilitate and manage billing, helping to alleviate anxiety around spending in the Cloud. They will work with you to set up a billing environment and a budget. They may have tools to help visualize storage, egress and compute charges, broken out by project and/or workspace. For researchers on grants, they can do purchase orders, and even help prepay with grant funding so you can spend when you need to. 

  There are many options for third-party resellers, who provide additional options for accessing and managing Google Accounts at no extra cost. Two examples are: Onix Networking or Sada Systems. To get started, you should contact the third-party reseller directly. 
  
  Note that if you are located in North America, you can leverage Onix as the Google Cloud Platform reseller. Onix is already experienced working with Terra accounts, so the setup to a new billing account is easy. Contact Onix at terrabilling@onixnet.com or (216) 584-6649.

• Create a new Google Cloud Billing account

  Creating a Google Cloud Billing account backed by a credit card or bank account is a good option if you want to have full control over your billing and are comfortable working in the GCP console.
  
  Go to the Google Developers Console Billing page, click on Add billing account and follow the instructions. 

  

  Remember to use the same Google ID you use to log into Terra for the Cloud Billing account. 

  You will need to provide billing information, which can be a personal or institutional credit card or bank account, as well as personal information to verify your identity (address and birthday). Note: If earlier, you signed up for $300 in GCP credits, you've done this and you're all set. 

• Request a Broad Cloud Billing sub-account

  Internal users at the Broad Institute may request a Google Cloud Billing sub-account to bill Terra usage costs to a Broad Institute-managed cost object.

  Before you request a sub-account, please speak to your grant administrator and primary investigator (PI) to determine the availability of funding, and to discuss a monthly and total budget for Terra.

  Once you are ready to request a sub-account, please fill out the form at this link (You should be signed in to your Broad Institute email to access this form).

 Step 2. Link the Cloud Billing account to Terra

Unless you are using a third-party reseller (who will take care of linking the accounts), the next step is to link the Google Cloud  Billing Account to your Terra user account. This step enables Terra and Google to communicate about cost and billing. You must use the same Google ID for both the Cloud Billing account and your Terra user name.

You'll do this step in the GCP console (separate from Terra).  

You must be an administrator on the Google Cloud Billing account This will automatically be true if you created the Cloud Billing account. If you can't follow the directions below, or know that you are not an administrator on the Billing account, you will need to contact an administrator and ask them to add you.

Note that the Cloud account owner or admin may be the PI or business administrator in your office.

2.1. When logged into Google with your Terra user ID, go to the Google Cloud Console Billing page.

2.2. Select the checkbox beside the Google Cloud billing account you will use for Terra.

2.3. On the right panel, below Permissions, select the Add Principal button.

2.4. Add "terra-billing@terra.bio" under New Principal in the form.

2.5.In the dropdown, select the Billing role Billing Account User.

2.5. Click Add.

2.6. Don't forget the Save button!

Note: "terra-billing@terra.bio" will appear in the list as "terra-billing@firecloud.org." This is expected!

 Step 3. Create a Terra Billing project 

When you create a workspace, you need to assign a Terra Billing project to cover workspace costs. You can create a Terra Billing project once Terra is linked to a Cloud Billing account.

Note:  You're automatically designated as the owner when you create a new Terra Billing project.

3.1. Go to the Billing page from the main navigation (click on your name to expand the drop-down, and select Billing).

3.2. Click on the "+ Create" button at the top left.

If prompted to Enable Billing Permissions, select the Google identity of the Google Cloud  Billing account, and click Allow. This lets Terra access Cloud Billing accounts associated with your Terra user name (Google ID).

3.3. Enter a unique name for your Terra Billing project. The name of the Terra Billing project must:
        - Only contain lowercase letters, numbers and hyphens
        - Start with a lowercase letter
        - Not end with a hyphen
        - Be between 6 and 30 characters

3.4. Select the Google Cloud Billing account that will fund the Billing project.
You may see multiple Cloud Billing accounts that you can select for this Terra Billing project. If you need to locate a Billing account ID, navigate to the Google Developers Console and click on Billing. Look for the number below Billing account ID.

Protect your group from getting locked out of billing!If your Terra Billing project will be used by a group (such as members in a research lab, or scientists with a common funding source), make sure to set up more than one individual with "owner" permission. That way, you will not be locked out of the Billing project if the sole owner leaves the group.

Add a second owner in the UI
       - or - 
Create a Terra Managed Group and give the group "owner" permission

See Managing shared resources with groups and permissions for step-by-step instructions to create a Terra managed group.

• 1. From your billing page, click on the Terra Billing project.

  2. Under the Users tab, select the blue Add Users button. 

  3. Important: Update their role to owner by selecting Edit role after clicking on the three dots icon.
  

Next step: Create (clone) a workspace

Congratulations on setting up your Terra billing! You should now be able to create or clone a workspace to work on the Terra platform. Your Terra Billing project should appear in the dropdown menu in the workspace modal. For step-by-step instructions, see How to clone a workspace.

Need more than five workspaces? Request a project quota increase.

There is a limit on how many Google projects you can have in a single Google Cloud Billing account (the default is five), and Terra creates a Google project for each workspace. It's a little unfortunate that they're both called "projects", since the Terra Billing project is not at all connected to the Google project.

Because most Terra users will want more than five workspaces, we recommend requesting a project quota increase right away when you set up your paid Cloud Billing account. Quota increases can take several days to process and must be made by the individual. 

For additional details, see Google Cloud quotas: What are they and how do you request more?

Terra resources that don't cost (you) anything to use

You do not need access to your own billing to browse Terra or to work in a collaborator's workspace. However, you won't be able to create your own workspace without setting up a Google Cloud Billing account linked to your Google (Terra) ID. 

Some things you can do without your own billing include: 

1. Browsing tutorial workspaces and open-access data (no GCP costs)
   These resources will be available to view in the Library after you register. Note: To run a workflow or interactive analysis, you need to make your own copy of the tutorial with your own Billing project. 
   
   
2. Working in shared workspaces with WRITER (can compute) permission (owner pays all GCP costs)
   If a Terra user, such as a collaborator or PI, shares a workspace with you and grants you WRITER (can compute) access, you can run workflows and interactive analyses within that workspace. All charges incurred will be paid by the workspace owner’s Terra Billing Project.