Best practices for managing shared funding

Are you a Grant Administrator, a PI, or in charge of managing funding and monitoring spend in Terra? If so, read on to understand how costs are calculated and charged in Terra. This article will explain the conceptual background behind managing shared resources and two options for sharing a funding source - team workspaces or team billing projects. 

If you are looking for step-by-step instructions instead, see How to manage shared funding (team workspaces) or How to manage shared funding (team billing)

To learn more about sharing data resources, see Best practices for sharing and protecting data resources.

Overview: How costs are calculated in Terra

Working in Terra incurs Google Cloud fees based on how much storage, data transfer out (egress) and compute resources you use. These costs are accrued at the workspace level (bottom), billed to a Terra Billing project (middle), and ultimately paid for by the Google Cloud Billing account (top). Terra Billing projects can support many different workspaces, such as one for each member of a team. 

Note: All Terra components are gray and all Google Cloud components are blue.

Options for sharing funding

Generally, each funding source will be tied to a Google Cloud account. Teams working in Terra can share funding with shared workspaces (option 1) or shared Terra Billing projects (option 2).

To choose which option works best for you when setting up team billing in Terra, you will want to consider what each member of the team needs to be able to do, and how much control they should have.  

Option 1: Shared team workspace

• Sharing workspaces is a way to share costs that gives less control to colleagues. 
• The workspace owner controls exactly what each collaborator can do in the workspace (read, write, execute). 
  For a detailed description of shared workspace roles, see Sharing data and tools with workspace access controls.
• Collaborators can only accrue costs (run an analysis or store data) if the workspace owner gives sufficient workspace permission. 
• Colleagues cannot create workspaces of their own unless they are on the Terra Billing project.
• All workspace costs are paid through the associated Terra Billing project by the linked Google Cloud account.

Option 2: Shared Billing projects (when you might want to share billing)

• Allows team members to create workspaces
  A shared Terra billing project lets each person on your team create their own workspaces, which adds flexibility (collaborators don't have to ask for permission to work in your workspace) and avoids overwriting data and analysis tools in a shared workspace.
• Streamlines funding management
  Owners and administrators of Google Cloud Billing accounts can set up one Terra Billing project for the entire team or separate one for different collaborators or different work in Terra. It is easy to cut off spend by billing project (see How to disable billing for step-by-step instructions).
• Allows members to access cost reporting
  Terra Billing project owners with admin permission on the Cloud Billing account can enable in-app spend reporting and detailed cost reports on Google Cloud. See How much did my workflow cost and Terra expenses and breaking down a Google bill for more details.

A warning about controlling costs when using shared billingA Terra Billing project user can create their own workspaces. As the workspace owner, they will be able to store and analyze data (i.e., accrue cost) in these workspaces and the Google Cloud costs will be billed to the shared Terra Billing project. 

Workspaces: the source of spend

The workspace is where all work gets done in Terra, and this work has a cloud cost. Storing, moving, and analyzing data all cost money because they consume cloud resources. The cost for the resources you use get billed to the Terra Billing project assigned to the workspace.

Simply being on a Terra Billing project does not mean you can accrue costs. But if you work in a workspace, there will be a cost--and whoever owns the Cloud Billing associated with the workspace Billing project will pay. 

What's your role in your workspace?

Workspace permissions define who can incur cost in a workspace. Workspace owners grant roles to collaborators - including "can-compute" or "can share" as well as the traditional "Owner," "Reader," and "Writer" roles.

Workspace permissions can be tricky! See Managing access to shared data and tools for more detail about how to use workspace permissions to control what and with whom you share.

Owners

When you create a workspace, Terra automatically makes you the owner. Owners assign roles (permission levels) to their collaborators. Best practices: Assign minimum permission levels to your collaborators. The more you assign, the more complicated it becomes to manage workspace costs. Normally, only a Grant Administrator needs to access a Cloud Billing account! However, you may want to assign "viewer" roles to multiple collaborators, so they can stay current with billing account information.

Collaborators

When you share a workspace, you grant each collaborator a role with specific permission levels. Those workspace permissions establish who can perform operations that have a cloud cost!. A collaborator does not have to be a billing project user to incur costs.

Below is a list of workspace roles that allow users to incur costs. If you grant a collaborator one of these roles, all cloud fees are paid for by the Terra Billing project associated with that workspace.

• Reader
• Writer
• Owner
• Can share
• Can compute

Google Cloud Billing account and Terra Billing project roles

Roles on a Cloud Billing account or Terra Billing project determine who can create Terra Billing projects and workspaces (respectively). Google Cloud Billing account owners and admins can also access workflow spend reporting in Terra, detailed cost breakdowns in Google Cloud and set budget alerts (in Google Cloud console). Billing account viewers can see detailed cost breakdowns in Google Cloud console. 

Billing project roles don't directly affect who can work in a workspace Billing project roles determine who can create resources like Billing projects or workspaces. 

Administrator

Can see and manage all billing aspects, and add additional users to the billing. Can access and work in all workspaces created with the billing project.

Viewer

Can view Billing account information (on Google Cloud console).

User

Can create Terra Billing projects (Cloud Billing account user only) or clone/create workspaces (Terra billing project user). 

Billing case studies in Terra

Let's look at some examples of billing in Terra. Consider the case of several collaborators with the same funding source. The funding will be dispersed through a Google Cloud Billing account. Collaborators can access the shared funds at any level of the billing hierarchy. 

Having permission at the top of the hierarchy (i.e. Cloud Billing account or Terra Billing project) lets you create more resources. Roles at the bottom (in a workspace) are limited to operations in a workspace.

How you share resources depends on your group's needs. For more details on Terra's billing and resources structure, see Managing shared resources with groups and permissions. 

Shared Cloud Billing account 

Collaborators should not have this level of resource. Only a Grant Administrator  or a PI should use a Cloud Billing account to access costs, create billing projects, and create workspaces.

Shared Terra Billing project

At this level, collaborators can create their own workspaces.

Shared workspace

At this level, collaborators actively work together in the same project workspace.

Some tricky billing permission scenarios

1. A collaborator who is removed from a Google Cloud Billing account can still cost you money!
Removing someone from a shared Google Cloud Billing account means they cannot create Terra Billing projects. It does not impact their ability to accrue charges in a workspace where they already have "can-compute" permission.

What is the solution?
If you want to remove a colleague's ability to accrue costs, you must remove their workspace "can compute" permissions on every workspace that has been shared with them.

2. A collaborator who is removed from a Terra Billing project can still cost you money!
This is because removing collaborators from a Terra Billing project means they cannot create workspaces. But they can still accrue charges in a workspace where they already have "can-compute" permission.

What is the solution? 
If you want to remove a colleague's ability to accrue costs, you must remove their workspace "can compute" permissions on every workspace that has been shared with them.

3. A Billing project user might not have access to a workspace created by a collaborator who is also a Billing project user.
This is because when a workspace is created, only the creator (the owner) has access.

What's the solution?
To collaborate in a shared workspace, the workspace owner (or anyone with "can share" permission) would need to explicitly share the workspace with the colleague and give them permission. 

A caveat about Terra Billing project ownersNote: Billing project owners have access to all workspaces created under that billing project, regardless of whether or not it is explicitly shared with them.

If you don't want Billing project owners to have access to workspaces, protect them with an Authorization Domain (that the Billing project owner isn't part of).