Accessing data from an external bucket

To launch an analysis on data stored in cloud storage buckets, your tools need to have 1) the data's location in the cloud (a complete file path) and 2) permission to access the storage bucket. Learn how to get the right permission to access data located in an external bucket (i.e., a Google Cloud bucket that is not a workspace bucket). 

To learn more about accessing external resources (such as Google Cloud buckets, or Virtual Machines (VMs) or machine-learning tools external to Terra), see Best practices for accessing external resources.

Best practices overview

If your workflows or notebooks use data files from an external bucket as input, you must give your Terra service accounts permission to access that bucket. Two ways to do this, with benefits and step-by-step instructions, are outlined below. 

Before you start: Only resource owners or admins can grant access permission If what you see on the console does not look like the screenshots below, or if you get an error message about permission, it is most likely because you are not the storage bucket or BigQuery dataset owner or admin. You need to ask the resource owner or admin to grant permission to your Terra group, following the directions below. 

Grant permission to a Terra managed group

Why use Terra groups?
You should always use Terra groups for accessing external resources, even for one user! Why?

• Terra groups are more human-friendly than service accounts. They include a user's service accounts as well as the user's account ID, but are much easier to identify and troubleshoot than random strings of numbers and letters.
• You can manage your Terra group within the Terra UI and Terra handles all the nonhuman-friendly back end.

Below are instructions for 1) creating a group - including a personal Terra group as well as a group of collaborators - and 2) granting permission for an external bucket to a Terra group. 

Step 1. Create your personal Terra group in four steps 

Example: Terra group for single user (User ID:  j_doe@someplace.org)
- Create a Terra Group: j_doe_at_someplace_org
- Don't add anyone else to this group
- Make grants to j_doe_at_someplace_org@firecloud.org

1. Go to your Groups page (Main menu > Groups from the top left of any page in Terra)

2. In the Create a New Group card, click on the blue + icon 

3. Enter your human-friendly user-ID in the field (can be the same as your Terra login) and click the Create Group button

Now, use your mirrored Terra group for accessing external resources (i.e.,  j_doe_at_someplace_org@firecloud.org)

Step 1. (alternative) Create a Terra group of collaborators in four steps

Example: Terra group for collaborators - Create a Terra Group: my_lab_at_someplace_org
- Add the Terra IDs of all collaborators to this group
- Make grants to my_lab_at_someplace_org@firecloud.org

1. Go to your Groups page (Main menu > Groups from the top left of any page in Terra)

2. In the Create a New Group card, click on the blue + icon 

3. Enter your collaborator group name in the field and click the Create Group button

4. Add or remove members in the Group management page in Terra.

Now, use this group (i.e.,  my_lab_at_someplace_org@firecloud.org) for granting permissions for external resources.

Step 2. Grant permission to the Group

2.1. From the Google Cloud console, select the resource to be shared (i.e., a particular bucket in https://console.cloud.google.com/storage/browser).

2.2. Go to Permissions.

2.3. View by Principals and select the Add icon.

2.4. Add the full name of your Terra group (i.e., j_doe_at_someplace_org@firecloud.org) as a New Member and select the resource type (left column - i.e., Cloud Storage) and the appropriate roles.

1. Storage Object Viewer to read from the bucket.
2. Storage Object Creator to write to the bucket.

You will see your Terra group and role in the Members Permissions

Make external bucket permissions match workspace permissions (advanced)

Each workspace has behind-the-scenes groups for Owners, Writers, and Readers.

These groups are automatically updated when a workspace is shared. For example, if a user is added to the workspace with Owner level permissions, they will be in the Owner group. You can take advantage of these predefined Terra managed groups to give permissions to external resources, such as an external private bucket.

Using this option, the external bucket mirrors the workspace sharing: whenever the workspace is shared with a new user, that user also gets access to the external bucket. See step-by-step instructions below to set up those permissions. 

The steps to do this depend on the age of the workspace.  If you follow the process for “Older Workspaces” below and it doesn’t work, try the “Newer Workspaces” guide.  

Newer workspaces (after mid-December 2018)

Step 1. Find workspace permission groups (newer workspaces)

Go to the Swagger page and run the following API call:
https://sam.dsde-prod.broadinstitute.org/#/Resources/listResourcePolicies

1.1. First, go to the top of that page and click the Authorize button.

1.2. Check all of the boxes under Scopes (1), and click Authorize (2).

1.3. Then scroll down to the GET resource policies API  and check the Try it out button. 
Note: If you click refresh instead of scrolling to the right place, your authorization will be lost!!

1.4. Fill out the resourceTypeName field with "workspace".

1.5. Fill out the resourceid field with the unique workspace ID.
The workspace ID is the workspace bucket ID minus the "fc-” (e.g., fc-d5eb5311-1cba-4c8f-84c5-27de52d2efbf). 

The bucket name can be found in the workspace Dashboard tab on the right. You can use the clipboard icon to copy the bucket name (see screenshot below), and remove the “fc-” from the beginning to get the workspace ID.

1.5. Click Execute.

1.6. Get the email corresponding to the right workspace role.

The response section lists the "emails" that Terra assigns to each workspace role. You want to get the “email” for the appropriate workspace role. You will grant authorization to that "email" in the next step.
Workspace Owner: policyName: “owner” - take the “email” value

Workspace Writer: policyName: “writer”: - take the “email” value

Workspace Reader: policyName: “reader”: - take the “email” value

Step 2. Grant permission to the workspace groups (newer workspaces)

2.1. From the Google Cloud console, select the resource to be shared (i.e., a particular bucket in https://console.cloud.google.com/storage/browser).

2.2. Go to Permissions.

2.3. View by Members and select the Add icon.

2.4. Add the three workspace groups (i.e., workspace Owner, Writer and Reader from step 1 above) as New Members, selecting the resource type (left column - i.e., "Cloud Storage") and the appropriate roles.

Selecting the right roles If you only want members of this workspace to read from the bucket

Add the three groups as Storage Object Viewer to that external bucket

If you want readers to read from the bucket, and writers/owners to read from the bucket, as well as write to the bucket

- Add all three workspace groups as Storage Object Viewer to the external bucket (all members need to be able to read from the bucket)
- Add the Owner and Writer groups as Storage Object Admin or Storage Object Creator

To find out which permission might be correct, please see  Google documentation about IAM roles.

You will see your workspace group and role in the Members Permissions.

Older workspaces (before mid December, 2018)

Step 1. Find workspace permission groups (older workspaces)

Workspace permission group formatting Owner:    GROUP_d5eb5311-1cba-4c8f-84c5-27de52d2efbf-OWNER@firecloud.org
Writer:     GROUP_d5eb5311-1cba-4c8f-84c5-27de52d2efbf-WRITER@firecloud.org
Reader:   GROUP_d5eb5311-1cba-4c8f-84c5-27de52d2efbf-READER@firecloud.org

1.1  Prepend GROUP_

1.2. Insert the unique workspace ID.The workspace ID is the workspace bucket ID minus the "fc-” (e.g. d5eb5311-1cba-4c8f-84c5-27de52d2efbf). 

The bucket name can be found in the workspace Dashboard tab on the right. You can use the clipboard icon to copy the bucket name (see screenshot below), and remove the “fc-” from the beginning to get the workspace ID.

1.3. Add the appropriate ending.
    Owners group: add -OWNER@firecloud.org to the end  
    Writers group: add -WRITER@firecloud.org to the end
    Readers group: add -READER@firecloud.org to the end

Note: You will need all three workspace groups in the next step.

Step 2. Grant permission to the workspace groups (older workspaces)

2.1. From the Google Cloud console, select the resource to be shared (i.e., a particular bucket in https://console.cloud.google.com/storage/browser).

2.2. Go to Permissions.

2.3. View by Members and select the Add icon.

2.4. Add the three workspace groups (i.e., GROUP_<long string>-WRITER@firecloud.org) as New Members, selecting the resource type (left column - i.e., "Cloud Storage") and the appropriate roles.

Selecting the right roles If you only want members of this workspace to be able to read from the bucket

• Add the three groups as Storage Object Viewer to that external bucket

If you want readers to read from the bucket, and writers/owners to read from the bucket, as well as write to the bucket

• Add all three workspace groups as Storage Object Viewer to the external bucket (if all members need to read from the bucket)
• Add the Owner and Writer groups as Storage Object Admin or Storage Object Creator

To find out which permission might be correct, please see the documentation here.

Storage object roles/permissions Storage Object Viewer: Grants access to view objects and their metadata, excluding ACLs. Can also list the objects in a bucket. Storage Object Admin:Grants full control over objects, including listing, creating, viewing, and deleting objects. Storage Object Creator: Allows users to create objects. Does not give permission to view, delete, or replace objects.

If you get an error like this (screenshot below), it is likely a newer workspace. Please see the instructions above. 

You will see your workspace group and role in the Members Permissions.