Read on for step-by-step instructions to set up a Terra billing project, including 1) set up a Google Cloud Billing account, 2) link Cloud billing to Terra, and 3) create a Terra billing project. Once you set up your billing, many funding and resources management tasks can be done in Terra. Terra takes care of interfacing with Google Cloud.
Do you have STRIDES credits? See How to access STRIDES for step-by-step instructions.
Set up billing in Terra from scratch - in three steps
Terra runs on Google Cloud; you will pay for all storage and analysis costs through a Google Cloud billing account linked to a Terra Billing Project. 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 can create or clone a workspace where you can store data and do analyses. After setting it up, Terra will manage the all Google Cloud costs.
To learn more about managing billing, see Best practices for managing shared funding.
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 Google Cloud fees.
Cloud Billing account options
- If you don't want to navigate Google Cloud console, you can go through a third-party reseller who will do it for you.
- If you're comfortable working in Google Cloud console, you can set up and manage a Google Cloud Billing account directly in Google Cloud.
- If you use a Broad Institute Cloud Billing account, you can request a Google Cloud Billing subaccount.
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 that if you have signed up for $300 in GCP credits, you will have already set up this part.
-
Request a Broad Cloud Billing sub-account
Users internal to 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 account. This step lets Terra and Google 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 Google Cloud console (separate from Terra).
You must be an administrator on the Google Cloud Billing accountThis 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 need to contact an administrator and ask them to add you.
Note: 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 role Billing > 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
Once Terra is linked to a Cloud Billing account, you can create a Terra Billing project. The billing project allows you to create a workspace in Terra to store and analyze data.
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.
Billing project name requirements
- Only contains lowercase letters, numbers and hyphens
- Starts with a lowercase letter
- Doesn't end with a hyphen
- Is 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), create 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
- or -
Create a Terra Managed Group and give the group "owner" permission
See Managing access to shared resources (data and tools) 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. Update their role to owner by selecting Edit role after clicking on the three dots icon.
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 Google Cloud resources you use. There is one for each workspace created after September 27, 2021. Terra automatically generates a Google Project in Google Cloud 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 Google Cloud 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: Creating a project on the Google Cloud console will not create a project in Terra. You can only create Terra Billing projects in Terra.
Next steps and billing resources
Once you have Cloud billing set up and linked to Terra, you can create workspaces (Billing project owners and users) to store data and run analyses.
Create (clone) a workspace
Congratulations on setting up billing on Terra! You should be able to create or clone a workspace to work on the Terra platform. For step-by-step instructions, see How to clone a workspace.
What to expect
Your Terra Billing project should appear in the dropdown menu in the workspace modal.
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 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.
To learn more, see How to troubleshoot and fix stalled workflows.
Additional links
Understanding costs and billing in Terra.
Best practices for managing shared team resources.
Set up billing with $300 Google credits to explore Terra.
Managing shared resources with groups and permissions