Structure of Permissions, Groups, and Billing

To manage access to resources (such as billing projects, workspaces and data, and workflow collections), resource owners will assign permissions (roles) to individuals or groups. This article gives an overview of the structure of permissions in Terra, and includes an example, with a diagram, of how permissions propagate.

Permissions - Enabling access to resources with roles and policies
Groups - Enabling large sets of users to access resources
Billing Projects and Billing Project roles
Evolution of permissions - a lab scenario

Permissions - Enabling access to resources with roles and policies

Access to resources is managed through a permission system based on resources, users, and policies (roles). A policy governs what sort of action (e.g. read, edit, share) can be performed on a given resource (e.g. workspace, dataset), and which users are allowed to perform those actions. When someone creates a resource, the system automatically generates a policy, and adds the resource creator as "Owner" to the policy. The level of access is dictated by the role on a policy. Each role has its own set of actions that it permits.

Examples of resources:

Terra Billing Projects
Workspaces (including data stored in the workspace bucket)
Workflow collections

Examples of roles that a policy can assign to a user for a workspace:

Owner - may add/remove users (grant access), lock workspace, etc.
Writer - may write to the metadata, method configs, etc.
Reader - may read the metadata, method configs, etc.
Can-compute - able to launch batch compute and interactive analyses (notebooks)
Share-writer - able to grant others write access
Share-reader - able to grant others read access

Policies can be public (apply to all authenticated users), such as policies of public workspaces, and a policy that allows all authenticated users to request access to a group.

Groups - Enabling large sets of users to access resources

To streamline resource management, owners can assign roles to managed groups as well as individuals. A group could be everyone in a research lab, for example, who might need access to the same resources.

Possible roles for managed groups:

Member - any individual in the group. When any form of access is granted to a group, the members include all who have that access.
Admin - may add or remove members or other admins to or from the group. Admins are also members of the group.
Admin-notifier - users who are allowed to send notifications to the admins of a group. When a group is created, this access policy is set to public - meaning all users are able to request access to a group.

Groups can access a particular resource when the resource owner adds the group to an access policy (i.e. assigns a role to the group). Group members connect to the resource via the policy that connects them to their group.

Permissions for managed groups are not the same as permissions for other resources. If a group is given access to a workspace, the workspace owner controls the role of the group with respect to the workspace (i.e. reader or writer), but the group's owner controls role of the user in the group. For example, if a group has the role of "writer" (not owner) in a workspace, even group admins will only have writer access.

Billing Projects and Roles

Billing roles determine who can incur costs in Terra. Roles are hierarchical, and the highest role is "Billing Project Owner". As with other owner policies, creating a new Billing Project will assign the role of owner to the creator.

Roles/policies for Billing Projects

Owner - full access, including adding and removing users to policies. Billing Project Owners can add other users as workspace creators, who become owners of whatever resources they create.
Workspace Creator - may create workspaces. Workspace creators become owners of the workspaces they create and can incur costs and assign roles for other users, including "can compute" roles, in the workspace
Workspace Reader - may not change documentation or incur charges in a workspace
Workspace Writer - may launch batch jobs and notebooks, and incur any costs associated with those, in a workspace
Notebook-user - may launch a virtual runtime for doing interactive analysis (i.e. notebook) and incur virtual runtime costs for that analysis
Batch-compute-user - may create a bulk analysis (batch) job (i.e. workflow) and incur costs for running the workflow

Evolution of permissions and groups and access to resources and billing - a lab scenario

Follow the story diagram below to see how permissions, groups and billing might affect access to resources in a cartoon lab scenario:

The head of a research laboratory (User #1) creates a billing project, generating an "Owner" policy for themselves
User #1 generates a "Workspace Creator" policy for one of their post-doctoral fellows (User #2), charging them with the task of creating a fresh workspace to be shared with potential collaborators. The workspace will include shared data resources uploaded to the workspace Google bucket.
The post doc creates the workspace (they are automatically the Owner of the workspace), adds some content, and then invites another coworker (User #3) to help edit the content.
User #3 is can now edit and run code in the workspace, but cannot give other new users access. Can you guess what role they have with respect to the workspace resource?
In the meantime, a researcher from an unrelated group (User #4) - who wants to introduce a team of students to Terra - creates a group, generating an "Owner" policy for themselves, and as many "Member" policies as they need.
In order for the students (User #5, User #6) to access the workspace, User #2 (workspace owner) must add the group created by User #4 to a policy for that workspace. In this case, the policy assigns the group a "Reader" role. All the group's members, including the group's owner, will have "read" permissions on the workspace.
When the invitation for access is sent, this generates a "Reader" policy to which the group (users #4, 5 and 6) are added.