Setting up Lab Accounts and Billing

A guide intended to help PIs and lab managers set up and configure the accounts and billing resources required for data analysts to run analyses in Terra.

This guide presents a recommended approach for labs new to cloud computing to set up billing on AnVIL. It enables detailed cloud cost accounting, provides users feedback on the costs of their analyses, and reduces the opportunity for unexpected cloud compute costs.

While there are many ways to configure a lab, the approach described here prioritizes fine-grained monitoring, reporting, and alerting over ease of setup and restricts who can create and share Terra workspaces with a lab manager or other trusted individual.

For additional information and approaches, see Best practices for managing shared team costs.

Goals of this Guide

Provide a conceptual overview of cloud billing in Terra and GCP.
Describe how to implement a recommended setup for lab billing.
Identify choices you can make to customize your lab setup to your needs.
Show you how to monitor cloud spending.
Capture Google’s promotional $300 getting started credits.

Prerequisites

Before working through the setup guide, it will be helpful to be familiar with Terra workspaces and permissions, the basics of cloud costs, and understand the basic billing concepts.

Knowledge of these concepts and how they interrelate will help you implement the suggested lab setup and customize it to your specific needs.

Critical concepts for review are:

Terra Workspaces and Permissions - For an overview of Terra workspaces, workspace permissions, and general billing information, see Getting Started with AnVIL.
Cloud Cost Basics - For an overview of cloud costs, see Understanding Cloud Costs.
Billing Concepts - For an overview of Google Cloud Platform and Terra billing concepts, see Overview of Billing Concepts.

Lab Setup Design

Lab Management Roles

The lab setup described here defines the following roles and responsibilities:

Data Analyst - A lab member who is granted write + can-compute access on one or more Terra workspaces by a Lab Manager and who will run analyses in Terra.

Lab Manager - A Lab Manager also creates or clones Terra workspaces and shares them with Data Analysts. The Lab Manager is also responsible for creating one or more Terra Billing Projects for each Data Analyst and configuring GCP budgets and alerts.

PI - The PI sets up the lab’s Google Cloud Account, creates its Google Billing Account(s), and Google Payment Method(s), links Terra with GCP, and invites Lab Managers to be GCP "Billing Account Users."

Lab Workspace Creation Workflow

Under this setup, Data Analysts will be able to configure analysis and launch workspaces but can not create or clone workspaces on their own or download data from workspaces with requester pays buckets. This setup also prevents Data Analysts from sharing workspaces.

To create a workspace:

The Data Analyst requests a Lab Manager to create or clone a new workspace.
The Lab Manager:
1. Decides if a new Terra Billing Project needs to be created to track expenses associated with the new workspace.
2. Sets up budgets and alerts for the new Terra Billing Project, if any, or adjusts the budget and alerts for the existing Terra Billing Project if required.
3. Creates or clones the workspace using the appropriate Terra Billing Project.
4. Adds and adds the Data Analyst as a "Writer" with "can-execute" but not "can-share" privileges on the new workspace.

Budgets, Alerting, and Reporting

The most important advice in this guide is monitor your spending so you can shut down unexpectedly expensive activities before they have time to accumulate unplanned costs.

The ability to monitor spending is accomplished by scoping GCP budgets and alerts to the level of a Terra Billing Project’s twin Google Billing Project and creating fine-grained Terra Billing Projects, i.e., one per Data Analyst or one per Data Analyst analysis.

As specified in the workflow above, whenever a new workspace is needed, the Lab Manager checks to see if a new Terra Billing Project is also required and, if so, creates it and sets or updates budgets and alerts.

Note

The Google Cloud billing interface does not provide an automatic way to cancel computations when spending reaches a given threshold.
Google Cloud reports compute costs with a delay of approximately one day.

Lab Setup Guide

Before you Start

Determine if your lab needs to create a Google Cloud Billing Account

You may not need to set up your lab’s own GCP Billing Account. It may be preferable for you to work with an account set up by your institution, your department, or a colleague. Additionally, some institutions may have existing relationships with Google Cloud third-party resellers who can assist you with your setup.

Check with your institutional procurement office for a preferred method to set up your Google Cloud Billing Accounts, such as a third-party reseller or an existing account. You can also work the NIH STRIDES initiative and their billing partners for discounts and support.

Plan out your configuration

Before you start, you will want to plan out your setup and:

Determine the Google ID to use to create your Terra account and log in to GCP.
Determine who will be a Lab Manager.
Determine who will be a Data Analyst.
Determine if you will need to create a new Google Payment Profile to associate with your Google Billing Account and decide what payment method to use.
Determine the set of Google Billing Accounts to create. This guide recommends one Google Billing Account per funding source (grant) to cleanly separate costs.
Determine the list of Terra Billing Projects to create - This guide recommends one per Data Analyst. If finer-grained reporting is desired, create on Terra Billing Project per each of a data analyst’s workspaces. Use a consistent naming convention that will help you identify the user and project the Terra Billing Project is for.
Determine the set of workspaces to create. This initially may be one per data analyst.
If you will be cloning a data workspace with controlled access data for data analysts, make sure each data analyst is a member of the workspace’s Authorization Domain. For more information, see Requesting Data Access.
Determine the expected costs, budget, and budget alerts you would like for each Terra Billing Project. See Controlling Cloud Costs - Sample Use Cases for a framework for estimating cloud costs. This guide recommends setting alerts at 50% and 90% of the expected budget.

1 - Create the Team’s Google Accounts

All Lab Members

All lab members who wish to use Terra will need a Google ID to create a Terra account.

A Google ID is an email address that may be:

a non-Google email that has been used to create a Google Account,
a Google email address in Gmail, Google Workspace, or Google Identity.

This email must also be the Google ID lab members will use to log in to Terra, the AnVIL Data Explorer, and associate with their ERA Commons ID for accessing controlled-access data.

If you already have a Google ID, you can skip this step. Lab members without Google IDs can see Create Your Google Account to register for a Gmail account or create an account with their current non-Google email address.

To create a Google ID with a non-Google email address, select "Use my current email address instead" on the signup form.

2 - Create the Team’s Terra Accounts

All Lab Members

Once lab members have a Google ID, they can use that email address to create a Terra account.

To create a Terra account:

Follow the instructions provided in the Account Setup Guide.

3 - Create Your Lab’s Google Billing Accounts

If this is your first Google Billing Account, see Creating a Google Billing Account for a walk-through of the first-time flow. Use the instructions below to add additional accounts.

PI or Account Administrator

For each Google Billing account required:

Sign in to the Manage billing accounts page in the Google Cloud Console. Sign in to GCP Manage Billing Accounts
Select your lab from the "Select an organization" dropdown if available.
Select the "ADD BILLING ACCOUNT" or "CREATE ACCOUNT" button.
Enter the name of your new Google Billing Account.
Select your country and, optionally, currency if applicable.
Select "CONTINUE" and follow the instructions to attach or create a Google Payments Profile to fund the new Google Billing Account.
Select "SUBMIT AND ENABLE BILLING".

For more information on creating billing accounts, see Create, modify, or close your Cloud Billing account.

4 - Link Terra to your Google Billing Accounts

PI or Account Administrator

To create and launch workspaces and consume Google Cloud resources, Terra needs to be linked to each of the Lab’s Google Billing Accounts. This is done in the Google Cloud console by adding Terra as a Billing Account User on each Google Billing Account.

To add Terra as Billing Account User to a Google Billing Account:

Sign in to the Manage billing accounts page in the Google Cloud Console. Sign in to GCP Manage Billing Accounts
Select your lab from the "Select an organization" dropdown.
On the right-hand side of the page, select "ADD MEMBER"
On the following screen:
Add terra-billing@terra.bio in the "New members" form field.
Under "Select a Role" select "Billing" and then "Billing Account User"
Select "MANAGE ROLES"

Linking Terra to Google Billing Account

5 - Add Lab Managers as Billing Account Users

PI or Account Administrator

Once a Lab Manager is added as a "Billing Account User" on a Google Billing account and the Google Billing Account is linked to Terra, the Lab Manager can create Terra Billing Projects using the linked Google Billing Account.

To add a Lab Manager as a Billing Account User to a Google Billing Account:

Sign in to the Manage billing accounts page in the Google Cloud Console. Sign in to GCP Manage Billing Accounts
Select your lab from the "Select an organization" dropdown.
On the right-hand side of the page, select "ADD MEMBER"
On the following screen:
Add the lab member’s Google ID (email address) in the "New members" form field.
Under "Select a Role" select "Billing" and then "Billing Account User"
Select "MANAGE ROLES"

The lab manager should now see the linked Google Billing Account when they attempt to create a Terra Billing Project in Terra.

6 - Create Terra Billing Projects

Lab Manager

To enable tracking of cloud costs for each Data Analyst, create each Data Analyst their own Terra Billing Project. Name the Terra Billing Project so that you can identify the Data Analyst by the Terra Billing Project name.

If you require finer-grained reporting and monitoring, you may wish to create a Terra Billing Project for each Data Analyst’s workspace if they have multiple workspaces.

To create a Terra Billing Project:

Log into the Terra manage billing page. Sign in to Terra Manage Billing
If prompted, select "Sign in with Google".
Select "CREATE" in the top left.
Enter a unique name for the Terra Billing Project that will help you identify the Data Analyst.
Select a Google Billing Account to link to the Terra Billing Project.
Select "CREATE BILLING PROJECT".

Note: During this step, if you can not see the desired Google Billing Account as an option for creating the Terra Billing Project, make sure the desired Google Billing Account is linked to Terra, and you have been added as a Billing Account User to the desired Google Billing Account.

Once the Terra Billing Project has been created, Lab Managers can see the new Terra Billing Project as an option when creating or cloning a workspace.

7 - Create Budgets and Alerts

Lab Manager

To monitor spending for each Data Analyst create a GCP Budget.

As discussed, when a Terra Billing Project is created, Terra creates a "twin" GCP Billing Project and associates it with the Terra Billing Project’s Google Billing Account. The "twin" GCP Billing Projects are used to scope individual budgets on their Google Billing Account.

You can create multiple budgets on a Google Billing Account. This guide recommends creating a budget for every "twin" Google Billing Project on the Google Billing Account.

To create a budget For each Terra Billing Project:

Sign in to the Manage billing accounts page in the Google Cloud Console. Sign in to GCP Manage Billing Accounts
Select your lab from the "Select an organization" dropdown.
In the list of billing accounts, select the account you wish to add alerts for.
In the left navigation, select "Budgets and Alerts"
Select "Create Budget" on the following page.
For the name of the budget, use the Terra Billing Project’s name.
In the "Projects" drop-down menu, select the GCP Billing Project with the same name as the Terra Billing Project you are creating a budget for and select "NEXT."
Select "Specified Amount" from the Budget Type dropdown menu.
Enter the target dollar amount of spending and select "FINISH".
By default, GCP will create alert thresholds at %50, %90, and %100 of the budget. Emails will be sent to the Billing Admins and Billing Users of the Google Billing Account when the thresholds are met. If desired, select the GCP Budget you just created from the "Budgets & Alerts" list, and add or remove thresholds and configure notifications.

Default budget alert thresholds in Google Cloud

See Set Budgets and Budget Alerts for additional instructions on creating, modifying, and deleting budgets and alerts.

8 - Create Workspaces

Lab Manager

To create workspaces for Data Analysts:

Log in to the Terra workspaces screen. Sign in to Terra Workspaces
If prompted, select "Sign in with Google".
Decide if you will create or clone a workspace:
To create a new workspace, select the "+" button on the top left of the workspaces screen.
To clone a workspace, find the workspace in your workspaces list, select the "three dots" icon on the right, and select "Clone".
Select a workspace name and Billing Project for the workspace, being careful to select the billing project created for the Data Analyst who will be computing with the workspace.
Select "CREATE WORKSPACE" or "CLONE WORKSPACE" as appropriate.

Next, to find the new workspace and share it with the Data Analyst:

Locate the workspace in the workspaces list by filtering on the workspace name.
On the "three dots" button on the workspace row and select "Share".
On the Share Workspace popup menu:
Search for the Google ID of the Data Analyst in the "User email" section.
Select the Data Analysts email address when it appears below the User email select box.
When the Data Analyst appears under the "Current Collaborators" section of the form, make the Data Analyst a "Writer" and select "Can compute". Do not select "Can share".

For additional information, see Cloning a Workspace in the Terra documentation. For additional information see How to Share a Workspace in the Terra documentation.

Providing Feedback

We would love to hear about your experiences attempting to implement this guide and discuss what worked or any omissions or points that need further clarification.

For questions, comments, pain points, or successes in following this guide, reach out to the AnVIL support from the AnVIL Help page.

Help us make these docs great!

All AnVIL docs are open source. See something that’s wrong or unclear? Submit a pull request.

Make a contribution