How to set up billing in Terra
This means how - and by whom - your your analysis costs are paid depend on whether you create (or clone) the workspace or if it is shared with you:
1. Workspaces you create or clone
When you create or clone a workspace, you will assign it one of your Billing Projects. Available Billing Projects include ones that you create or ones others created that you are part of.
Shared workspaces
When someone shares a workspace with you as writer (can-compute), your analysis costs will be covered by the Billing Project of the original workspace. For more information about sharing workspaces, see this article.
This article walks through the steps of setting up billing on Terra, including how to create a Terra Billing Project or access an existing project.
Contents
Setting up billing in Terra: Overview
1. Set up a Google Billing Account
- Request a Google sub-account (Broad internal users)
- Set up a billing account through your institution
- Use a third-party reseller
- Create a personal Google Billing Account using a credit card or bank account
2. Link the Google Billing Account to Terra
3. Create a new Terra Billing Project
4. Accessing and Managing a Billing Project (i.e. adding or removing users)
- How to accessing an existing Terra billing project (if you're not the owner)
- How to add or remove users from a Billing Project (Owners)
- How to change a Project's Google Billing Account (Owners)
5. Create or clone a workspace
How to remove Terra from a Google Billing Account
Using Terra without a Terra billing project
Setting up billing in Terra: Overview
Because Terra runs on the Google Cloud Platform, all Terra costs - including storage, compute, and data egress - are ultimately billed via Google Billing Accounts via Terra Billing Projects. There are four steps to setting up a Terra Billing Project, which allows you to create and clone workspaces (step 5 below) and run analyses. See the sections below for more detail on each step.
Important note about required steps:
Your group may already have completed some of the steps below. For example, some labs already have Google Billing accounts linked to Terra and associated Billing Projects, in which case you can skip to step 4 to set up your billing.
1. Set up Google Billing Account |
2. Link Google Billing to Terra |
3.Create a Terra Billing Project |
4. Add users to Billing Project |
5. Create or clone a workspace |
1. Set up a Google Billing Account
You will first need to set up a Google Billing Account, or be included on an existing Google Billing Account. Remember to use the same Google account ID you use to log into Terra. Options and instructions for setting up a Google BIlling Account are below.
Request a Google Billing sub-account (Broad users)
Broad internal users can request a Google Billing Sub-Account to bill Terra usage costs to a Broad Managed Cost Object.
Before you request a Google Billing Sub-Account, please speak to your Grant Admin 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 Google Billing Sub-Account, please fill out the form at this link (Please note you will have to be signed in to your Broad email to access this form).
Set up an account through your institution
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).
Use a third-party reseller
There are many options for third party resellers, who provide additional billing options at no extra cost. Two examples are: Onix Networking or Sada Systems.
Note that if you are located in North America, you can leverage Onix as the Google Cloud Platform re-seller. Onix is already distributing the free credits to your Terra account, so the setup to a new billing account is easy. Contact Onix at broad@onixnet.com or (216) 584-6649.
Create a personal Google Billing Account using a credit card or bank account
Go to the Google Developers Console Billing page and click on Add billing account. You will need to provide billing information, but can start with Google's free trial that includes $300 in compute and storage credits.
2. Link the Google Billing Account to Terra
Once you have access to a Google Billing Account, you will need to link it to Terra to use it to create Terra Billing Projects. In order to be compatible with multiple cloud environments, institutional payment systems, and security requirements, the Terra interface does not directly display the Google Developers Console Billing interface.
Once the Google Billing Account is linked, you'll create one or more Terra Billing Projects to cover the costs of creating or cloning a new workspace, storing data in a workspace bucket or running an analysis. To help keep track of where your spending occurs, you can have different Terra Billing Projects paid by the same or different Google Billing Accounts. For example, you may have distinct Google BIlling Accounts corresponding to different grants.
NOTE: You must be an administrator on the Google Billing Account to link the account with Terra. This will automatically be true if you created the Google billing account. If you are not already an administrator on the Google Billing Account, you should contact an administrator and ask them to add you (or ask them to add Terra as a Billing Account User). This may be the PI or business administrator in your office. Or it may be someone within a third party billing entity, such as with Terra's free credit accounts, which are administered by Onix.
Step-by-step instructions to link Google Billing to Terra
2.1. When logged into Google with your Terra user ID, go to the Google Cloud Console Billing page
2.2. Select the check box beside the Google billing account you will use for Terra
2.3. On the right panel, below "Permissions," select the "Add Members" button
2.4. Add "terra-billing@terra.bio" and select the role Billing Account User. Click Add.
3. Create a new Terra billing project
Once Terra is linked to a Google Billing Account under your Terra user ID, you should be able to create a Terra Billing Project through the Billing Management Screen in the Terra UI using the steps below. Note that when you create a new Terra Billing Project, you are automatically designated as the Owner.
3.1. Click on the User Profile drop-down from the main navigation menu and select Billing
3.2. Click on Create New Billing Project.
If prompted, click to Enable Billing Permissions, select the Google identity of the Google Billing Account, and click Allow. This enables Terra to access Google Billing Accounts associated with your Terra account.
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
- Be unique across all Google Billing Projects
3.4 Select a Google Billing Account to associate with the Billing Project.
Note: You may see multiple Google Billing Accounts that you can select for this Terra Billing Project. If you need to locate a Google Billing Account ID, navigate to the Google Developers Console and click on Billing. Look for the number below Billing Account ID.
(expand for tip) The relationship between Terra Billing Projects and Google Projects
When you create a Terra Billing project, Google automatically generates a Google Project in GCP with the same name, which you will see on the GCP Console. Sometimes, Terra Billing projects fail to get created if a project of the same name already exists in GCP.
When you look at the Google project that Terra has created, you will see that your permissions are restricted. For security reasons, this means you won't be able to create VMs or Google buckets in GCP directly using this Google project - only in Terra.
4. Accessing and managing a Terra Billing Project
Owners can add and remove access to Terra Billing Projects, once they exist, so you may be able to join one. This may apply to you, for example, if you are joining a research group that is already working in Terra. Click to expand the sections below for details about your use case.
How to access an existing Terra Billing Project (if you're not the owner)
You don't need to follow steps one to three above if you are collaborating with someone who has already done the work! Costs for your work in Terra will be billed to the Google Billing Account linked to their Billing Project. To gain access to a Billing Project, ask the Owner of an existing Terra Billing Project to add you to their Terra Billing Project using the steps below.
How to add or remove Billing Project users (Owners)
The instructions below assume all users have independently registered on Terra.
4.1. In the Terra UI, click on the User Profile drop-down from the main navigation menu at the top left and select Billing.
4.2. Click on the Terra Billing Project to which you want to add users. You must be an Owner of the Billing Project to add users.
4.3. To add a new user, click on Add User… Note that the user must first be registered for Terra.
4.4. In the pop-up window, enter the user’s Terra email address. The system will add the person as a User by default. if you want that person to have greater control, click the checkbox labeled "Owner". Owners can add additional users to the Terra Billing Project. Users can create workspaces using this Billing Project, but can not add other users to the Billing Project.
Owners can edit any users 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 from the main navigation menu at the top left).
The Billing Project will automatically appear as an option for all users when cloning or creating a workspace and you can continue to the final step (five).
How to change a project's Google Billing Account (Billing Project Owners)
There are times when you may need to change the Google billing account associated with a billing project in Terra (note that the Terra billing project can be used on many workspaces). An example would be if there was a change to the funding source for the project. If you have OWNER permissions for the project, you can follow the following steps to change the billing account:
- Go to the Billing page
- Select a billing project for which you are an owner from the list on the left hand side of the screen. You will see details.
- Click the "change account" button. You will see a list of all the google billing accounts you have access to. Select the one you want to use with the project and click OK.
Your project is now funded by the chosen account!
5. Create or Clone a workspace
Once you have access to a Billing Project, you should be able to create or clone a workspace using the Terra interface. The Billing Project should appear in the dropdown menu for Billing. For step-by-step instructions on cloning a workspace, see this article.
How to remove Terra from a Google Billing Account
If you discontinue working in Terra and want to ensure that Terra is. unable to bill for any additional charges, you can remove Terra as a User on the Google Billing Account.
Warning: If you remove Terra as a Billing Account User after you have created a Terra Billing Project, all data and job history data from any workspaces created under that Billing Project will be deleted. Be very cautious when doing this!
To remove the Terra Billing Account User from your account, click on the trash can icon next to terra-billing@terra.bio on your billing account page.
Using Terra without a Terra Billing Project
You do not need access to your own Terra Billing Project to use Terra. For example:
- Tutorial workspaces with open-access data will be available to view after your register. Note, however, that in order to run a workflow or interactive analysis, you will need to make your own copy of the tutorial under a Billing Project.
- Shared workspaces with WRITER (can compute) permission: 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.
Without a funding source (Billing Project), you will not be able to clone or create a workspace, store or access data, or run any analysis.
Comments
0 comments
Please sign in to leave a comment.