Set up billing with pods in Verily Workbench

Purpose: This document describes how Verily Workbench admins can create pods for Workbench billing purposes.

Introduction

Verily Workbench enables users to take advantage of public cloud platforms for storage, compute, and other services. An important step in user setup is to enable Workbench to create resources and perform cloud operations that have cloud costs associated with them, with flexibility on who is billed. This document describes the steps to enable and manage the association between user profiles and how cloud services are paid for.

For more information about what Workbench operations lead to cloud charges and how to manage cloud costs, see Cloud cost management.

What is a pod?

Institutions can use pods to connect people and workspaces to cloud infrastructure and billing.

A pod organizes resources within an organization so that they share the same cloud platform and billing. With billing controls at a pod level, users within one organization can choose to use multiple billing accounts, and users across organizations can be allowed to collaborate in a given pod.

How pods work

Each pod is linked to a cloud account, which is used for billing. One pod can be used for many workspaces. Since pods are linked to cloud accounts, the pod specified upon workspace or data collection creation determines which cloud platform the workspace or data collection belongs to.

Pods are administered by organizations (“orgs”). An org may have a default pod associated with it, which means new workspaces and data collections created by org members will belong to that pod by default.

In order to create a pod a user must have the Organization Admin or Pod Manager role. For more information on organization level roles and permissions, see Organization roles and permissions.

When a Pod Manager creates a pod they are then able to administer it by automatically being granted the Pod Admin role on that pod. Pod Admins can grant permission to other users or groups to use the pod. Users can be granted permission to access as many pods as needed.

When a user creates a workspace or data collection, they pick the pod in which to allocate the workspace or data collection, chosen from the pods they have permission to access. (As with pods, workspaces can be shared with users from other organizations.)

Using Workbench without belonging to a pod

You don’t need to be a pod member to use some Workbench features. For example, you can:

• Browse read-only any workspaces to which you have been granted Reader
• Work read-write in any workspace to which you have been granted Owner or Writer

For more information about workspace permissions, see Access control and sharing.

Pod roles and permissions

The set of roles and permissions at the pod level is as follows. Note that Pod Manager is not on this list because it is an organization level role

How to create a pod

Step 1: Create a Cloud Billing account

If you don’t already have a Google Cloud Billing account set up that you want to use for this purpose, you’ll need to create one, as described below.

You may first want to talk to your institutional IT department or administration to determine if your organization has an existing account or a preferred account setup method with Google.

If you want to use an existing Cloud Billing account, your Google Cloud account will need to have access to the Billing account that you use, as the setup process will check that you have access permissions.

Otherwise, if you want to set up billing for yourself, you can follow Google’s instructions to create a new self-serve Cloud Billing account. Note that while you’ll need to set up some billing method, you may also be eligible for $300 in free credits from Google. Information and instructions for usage can be found at Free cloud features and trial offer.

Step 2: Grant permission to Workbench to use the Billing account

To grant permission to Workbench to use your Google Cloud Billing account, do the following:

Sign in to the billing accounts management page in the Google Cloud console at: https://console.cloud.google.com/billing. Check the box for the relevant account and click SHOW INFO PANEL.

You should see an info panel. Click the ADD PRINCIPAL button.

Then assign the role to Billing Account User.

Add billing@workbench.verily.com to New principals. Click SAVE.

Step 3: Install or access the Workbench CLI

You’ll need to use the Workbench command-line tool to create and manage pods. You can install the CLI on your own workstation, or you may find it convenient to install the Workbench CLI in a Google Cloud Shell. For a first time user Google Cloud Shell will likely be a smoother experience, as you will not need to install the required dependencies.

To open a Cloud Shell, click the Activate Cloud Shell icon () at the top of the Google Cloud console. Then follow the instructions for Installing and running the Workbench CLI.

Alternatively, if you’re already a member of an existing pod, you can create a Workbench workspace cloud environment, where the Workbench CLI is automatically installed, and run the commands there.

Step 4: Provide credentials to the Workbench CLI

Creating a Workbench pod for Google Cloud requires being logged in with Google Application Default Credentials. Run the following command in order to create credentials that will be used by the Workbench CLI in the next step.

If running on Cloud Shell you will be presented with a warning that this command is not necessary and could expose your credentials to other users on the VM. You can safely proceed in spite of this warning. The Cloud Shell runs on a Compute Engine Virtual Machine that is not a shared instance. Per How Cloud Shell works: “Cloud Shell instances are provisioned on a per-user, per-session basis.”

gcloud auth application-default login

Next, authorize the Workbench CLI using your application-default credentials:

wb auth login --mode=APP_DEFAULT_CREDENTIALS

Step 5: Create a pod

Determine the Org ID for the pod:

wb org list

Create a pod:

wb pod create gcp \
  --id ID \
  --description DESCRIPTION \
  --billing-account-id YOUR-BILLING-ACCOUNT-ID \
  --org YOUR-ORG-ID
  --group-name POD-GROUP-NAME

Where:

• ID is an identifier that you choose. The pod ID must be globally unique.
  • Tip: Choose an ID that will make sense to others you add to the pod. When you create workspaces, you can see the pods you’re a part of. It could be the name of your team, department, program, or something meaningful to you and others you work with.
• DESCRIPTION is a description of the pod. It should be something meaningful to you.
• YOUR-BILLING-ACCOUNT-ID is your 18-character Google Billing account ID.
• YOUR-ORG-ID is the identifier for the organization under which you want to place the new pod.
• POD-GROUP-NAME is the name of a new group that will be automatically created and synced with the set of users given access to the pod. (You will not be an ‘admin’ on this list). A suggested naming convention for the group is <pod_id>-pod.

You can optionally add the --set-default flag, which will set this pod as the default for the given organization. You must be an Organization Admin to do this.

You can now use the pod when creating new workspaces and data collections. See below for more details.

Troubleshooting

If you do not see an org listed in the above commands, or you are not able to otherwise create a pod, please contact Workbench Support for assistance.

How to update a pod (for pod admins)

Grant or revoke users’ access to and permissions on a pod

A pod admin may grant use of the pod to other Workbench users, or revoke that access.

wb pod role grant --email=<email> --org=<id> --pod=<id> --role=<role>
wb pod role revoke --email=<email> --org=<id> --pod=<id> --role=<role>

The valid --role values are ADMIN or USER.

Additional pod operations

See the wb pod reference documentation for a list of the available operations on pods including:

• List the pods that you are a member of, which you can use for new workspace creation (wb pod list)
• Describe a pod (wb pod describe --org=<id> --pod=<id>)
• Requires pod admin access: Update the Google Billing Account ID associated with a pod that you administer, or change its name or description (wb pod gcp update)
• Requires pod admin access: Delete a pod that you administer (wb pod delete --org=<id> --pod=<id>)
  • Note: You cannot delete a pod if it holds any workspaces; workspaces must be deleted first.

Obtaining admin access to a pod

As noted above, only Workbench Org Admins may initially create a pod. After it’s created, the Org Admin can grant pod users the admin role. They can then perform pod update actions including renaming the pod ID, changing the pod’s billing account, and adding additional users.

If you know who your Org Admins are, you can contact them and request to be added as a pod admin.

If you don’t know who your Org Admins are, please contact Verily Workbench support for help.

Using a pod when creating resources

When you create a new workspace or data collection, you can select which pod — and thus billing account — that you want to use for that resource.

Via the UI, select the pod from a dropdown in the workspace or data collection dialog:

You can also specify the pod for a new workspace via the Workbench CLI:

wb workspace create \
...
  [--org=<id>] [--pod=<id>]

If you don’t specify a pod, the default pod for your organization will be used.