Terraform provider examples

Prior reading: Get started with the Workbench Terraform provider

Purpose: This document provides various examples for using the Terraform provider within Verily Workbench.

Note: This document is relevant for customers using Amazon Web Services (AWS) with Workbench.

Introduction

This article provides you with examples for using the Terraform provider to create and manage workspaces, data collections, and groups.

In all examples below, replace any placeholder values in <> with relevant values.

Terraform resource syntax

You'll see that each example below follows this format:

resource "<resource_name>" "<label>" {
    ...
}

The resource_name value is the type of resource you're creating. You can see a list of available resources for the Workbench provider on the Terraform Registry.

The label value is an identifiable name you create for that particular resource.

Some of the examples below also include an output declaration:

output "<output_name>" {
    value = <resource_name>.<label>
}

An output allows you to call the declared output name to use its value elsewhere in your Terraform configuration.

Workspace usage examples

Create and manage workspaces with the Workbench provider.

Create a Workbench workspace

Creating a workspace requires specifying an organization UUID and a pod UUID. From the left sidebar of the Workbench web UI, click Organizations to see your org's UUID. Click Pods from the left sidebar and select the desired pod to see its UUID.

For display_name, user_facing_id, and description in the example below, enter your desired workspace name, user-facing ID (use only lowercase letters, numbers, dashes, and underscores), and description. location refers to the AWS Region (e.g., us-east-1).

resource "workbench_workspace" "my_workspace" {
  display_name    = "My workspace"
  user_facing_id  = "my-workspace"
  pod_id          = "<pod_uuid>"
  organization_id = "<org_uuid>"
  description     = "<workspace_description>"
  location        = "<region>"
}

output "my_workspace" {
  value = workbench_workspace.my_workspace.id
}

For details of workbench_workspace usage and to see an example of a workspace resource with a VPC-SC perimeter, see Terraform Registry. Refer to the policies block for service perimeter fields.

Grant a workspace role

This example applies the READER role to the specified user(s) listed in the members field.

resource "workbench_workspace_iam_member" "reader" {
  workspace_id = workbench_workspace.my_workspace.id
  role         = "READER"
  members      = ["<researcher_email_address>"]
}

You can verify that the user's role has been successfully granted by running wb workspace role list --workspace=<workspace_user-facing_id>.

Apply a workspace IAM policy

This example shows an IAM policy resource that's applied to the specified workspace.

resource "workbench_workspace_iam_policy" "pol" {
  workspace_id = workbench_workspace.my_workspace.id

  iams = [
    {
      role    = "OWNER"
      members = ["<user_email>"]
    },
    {
      role    = "WRITER"
      members = ["<user_email>"]
    },
  ]
}

output "workspace_policy" {
  value = workbench_workspace_iam_policy.pol.iams
}

Group usage examples

The Workbench provider allows you to create and manage Workbench groups.

Create a Workbench group

You can create a Workbench group within an organization. This group can be used for assigning permissions and managing access.

For group_name and description in the example below, enter your desired group name and description.

resource "workbench_group" "my_group" {
  group_name                  = "<group_name>"
  organization_user_facing_id = "<org_user-facing_id>"
  require_grant_reason        = false
  description                 = "<group_description>"
}

output "group_name" {
  value = workbench_group.my_group.group_name
}

Add or remove a group member

The example below adds the specified user(s) as a member to the named group.

Note that the organization name value must be preceded by a tilde (~).

resource "workbench_group_iam_member" "member" {
  group        = workbench_group.my_group.group_name
  organization = "~<org_user-facing_id>"
  role         = "MEMBER"

  principals = [
    {
      user = "<user_email>"
    }
  ]
}

To remove a group member, delete the Terraform resource that initially added the user to the group and run terraform apply. Alternatively, you can run terraform destroy.

Grant or revoke the Group Admin role

The example below grants the Group Admin role to the specified user(s).

Note that the organization name value must be preceded by a tilde (~).

resource "workbench_group_iam_member" "admin" {
  group        = workbench_group.my_group.group_name
  organization = "~<org_user-facing_name>"
  role         = "ADMIN"

  principals = [
    {
      user = "<user_email>"
    }
  ]
}

To revoke the Group Admin role, remove the resource and run terraform apply. Alternatively, you can run terraform destroy.

Data collection usage examples

You can use the Workbench provider to create a data collection and its versions.

Create a data collection

This example creates a data collection.

For display_name, user_facing_id, and description, enter your desired data collection name, user-facing ID, and description. The support_email value should be an email address of a user who will serve as the main point of contact for the data collection.

resource "workbench_data_collection" "dc" {
  display_name      = "<data_collection_display_name>"
  user_facing_id    = "<data-collection_user-facing_id>"
  description       = "<data_collection_description>"

  organization_id   = "<org_uuid>"
  organization_name = "<org_user-facing_id>"

  pod_id        = "<pod_uuid>"
  support_email = "<user_email>"
}

output "data_collection_id" {
  value = workbench_data_collection.dc.id
}

Create a version

Every data collection must have a version. In the example below, replace display_name and description with your desired version display name and description.

resource "workbench_data_collection_version" "ver" {
  display_name = "<version_name>"
  description  = "<version_description>"

  workspace_id = workbench_data_collection.dc.id
  published    = true
}

output "data_collection_version_id" {
  value = workbench_data_collection_version.ver.id
}

Publish a version

To publish a draft version, keep published = true in your Terraform configuration, then re-run Terraform:

terraform apply -auto-approve

Additional reference

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