Get started with the Workbench Terraform provider

Purpose: This document provides detailed instructions managing Workbench resources with a Terraform provider.

Introduction

Hashicorp Terraform is an Infrastructure as Code (IaC) tool that lets you provision and manage cloud infrastructure. Terraform provides plugins called providers that let you interact with cloud providers and other APIs. As a data steward or an organization admin, you can use the Workbench Terraform provider to provision and manage Workbench resources such as workspaces, data collections, and groups.

Benefits of using Terraform

This section explains some of the benefits of using Terraform to provision and manage Workbench infrastructure.

• Terraform lets you specify your preferred end state for your infrastructure. This provider empowers teams to enforce consistency, reduce manual errors, and track changes through version control.

• Terraform records the current state of your infrastructure and lets you manage state effectively. The Terraform state file keeps track of all resources in a deployment.

• By using this provider, platform teams can automate the lifecycle of core components like workspaces, groups, data collections, and IAM policies, significantly improving scalability.

We recommend the Workbench Terraform provider to organizations that require administrative oversight, particularly for managing data pipelines and data access in Workbench workspaces.

Getting started

Terraform has a declarative and configuration-oriented syntax, which you can use to author the infrastructure that you want to provision. Using this syntax, you'll define your preferred end-state for your infrastructure in a Terraform configuration file. You'll then use the Terraform CLI to provision infrastructure based on the configuration file.

First, the Terraform provider must authenticate to Workbench before it can manage resources. The recommended way to run the provider locally is to use credentials from the Workbench CLI.

Install the Workbench CLI and authenticate:

wb auth login

Then, add the provider to your Terraform configuration:

terraform {
  required_providers {
    workbench = {
      source  = "verily-src/workbench"
      version = ">= 0.0.1"
    }
  }
}

provider "workbench" {
  host                = "https://workbench.verily.com"
  use_cli_credentials = true
}

By setting use_cli_credentials = true, the provider will call wb auth print-access-token to obtain your access token and refresh it automatically before it expires.

Example usage

Create a Workbench workspace

Creating a workspace requires specifying an organization ID and a pod ID. These two IDs are the UUIDs and they can be found by visiting https://workbench.verily.com/pods. From there, select the pod you want to use. This should open the pod details page. Open your browser's developer tools. Under the Network tab, select the request to that pod. You can find the podId and orgId values in the Response tab.

Alternatively, you can use the Workbench CLI:

wb pod describe --pod=<my-pod> --org=<my-org> --format=json

This is an example of a workspace that has a VPC-SC perimeter constraint. Policies can be omitted if your workspace does not need to be in a service perimeter.

For details of workbench_workspace usage, see Terraform Registry.

resource "workbench_workspace" "my_workspace" {
  display_name    = "My Workspace"
  user_facing_id  = "my-workspace"
  pod_id          = "12345678-9012-3456-7890-123456789012"
  organization_id = "23456789-0123-4567-8901-234567890123"
  description     = "terraform-managed"

  policies = [
    {
      namespace = "terra"
      name      = "exfil-perimeter-constraint"
      additional_data = [
        {
          key   = "perimeter-id"
          value = "my-vpc-sc-perimeter"
        }
      ]
    }
  ]

  location = "us-east1"
}

output "my_workspace" {
  value = workbench_workspace.my_workspace
}

Create a Workbench group

resource "workbench_group" "my_group" {
  group_name                   = "my-group"
  organization_user_facing_id = "my-org"
  require_grant_reason        = false
  description                 = "terraform managed group"
}

output "my_group" {
  value = workbench_group.my_group
}

This defines a group within the organization that can be used for assigning permissions and managing access. You must be an admin of the organization to create groups.

Next steps

Once your resources are created, you can:

• Attach IAM policies using workbench_workspace_iam_binding and workbench_group_iam_binding.
• Manage GCS buckets and folders using workbench_controlled_gcs_bucket and workbench_folder.
• Query existing resources using data sources.

For more examples and full resource documentation, visit the Terraform Registry.