Accessing data from an external bucket
FollowTo launch an analysis on data in the cloud, your workspace tools need to have 1) the data's URL (i.e. complete file path) as well as 2) permission to access the bucket. This article covers how to make sure you have the right permission to access data located in an external bucket (i.e. a GCP bucket that is not a workspace bucket).
To learn best practices for accessing external resources (like GCP buckets, VMs or machine-learning tools external to Terra), see this article.
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 the bucket. There are several options for granting permission to Terra:
- Grant permission to a Terra managed group
- Make permissions on an external bucket match workspace permissions
- Grant permission to a Terra proxy
The benefits of each use-case, and step-by-step instructions, are outlined below.
|
|
---|---|
If what you see on the console does not look like the screenshots, 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 will need to ask the resource owner or admin to grant permission to your Terra group. |
Grant permission to a Terra managed group
You should always use Terra groups for accessing external resources, even for one user!
- You can manage your Terra group within the Terra UI and Terra handles all the non-human-friendly back-end
- Terra groups include a user's service accounts as well as the user's account ID, an are more human-friendly than the service accounts themselves.
Below are instructions for creating a personal Terra group as well as granting permission to a Terra group.
1. Create your personal Terra group in four steps (expand for step-by-step instructions)
|
|
---|---|
- Create a Terra Group: j_doe_at_someplace_org |
- Go to your Groups page ("Main menu" --> "Groups" from the top left of any page in Terra)
- In the "Create a New Group" card, click on the blue "+" icon
- Enter your human-friendly user-ID (can be the same as your Terra login) and click the "Create Group" button
- You can now use your mirrored Terra group for accessing external resources (i.e. j_doe_at_someplace_org@firecloud.org)
2. Grant permission to a Terra Group (expand for step-by-step instructions)
- From the GCP console select the resource to be shared (i.e. a particular bucket in https://console.cloud.google.com/storage/browser)
- Go to Permissions
- View by "Members" and select the "Add" icon
- 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.
- "Storage Object Viewer" if you want to read from the bucket
- "Storage Object Creator" if you want to write to the bucket
You will see your Terra group and role in the Members Permissions
Make permissions on an external bucket match workspace permissions
Each workspace has behind-the-scenes groups for Owners, Writers, and Readers.
These groups are automatically updated when a workspace is shared - for instance 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 pre-defined Terra managed groups to give permissions to external resources, such as an external private bucket. The advantage of this option is the external bucket will mirror 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.
1. Find the workspace permission groups (expand for step-by-step instructions
|
|
---|---|
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. 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.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 that you will need all three workspace groups in the next step.
2. Grant permission to the workspace groups (expand for step-by-step instructions)
- From the GCP console select the resource to be shared (i.e. a particular bucket in https://console.cloud.google.com/storage/browser)
- Go to Permissions
- View by "Members" and select the "Add" icon
- Grant permissions to 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 rolesIf 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 be able 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 the documentation here.
Storage object roles/permissionsStorage 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.
Grant permission to a Terra proxy
You can use your pre-defined proxy to grant the appropriate type of permission for your desired use. The downside of this approach is that the proxy (found in your profile page) is not human-friendly. It will be difficult to identify which Terra user is associated with the proxy when looking at the list of who has access permission for an external bucket.
For this reason, we recommend using a personal Terra user group with a meaningful name instead of your proxy.
1. Find your Proxy group
You'll see your proxy group listed near the bottom:
2. Grant permission to your proxy group

Comments
0 comments
Please sign in to leave a comment.