Need Help?

Search our documentation and community forum

Terra is a cloud-native platform for biomedical researchers to access data, run analysis tools, and collaborate.
Terra powers important scientific projects like FireCloud, AnVIL, and BioData Catalyst. Learn more.

Articles in this section

See more

Accessing data from an external bucket

Avatar
Anton Kovalsky
  • Updated
Follow

To 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. 

icon-warning2.png

 
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, 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)


G0_tip-icon.png


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)
    Create-Terra-Group_Step-1_Screen_shot.png

  2. In the "Create a New Group" card, click on the blue "+" icon 
    Create-Terra-group_Step-2_Screen_shot.png

  3. Enter your human-friendly user-ID (can be the same as your Terra login) and click the "Create Group" button
    Create-Terra-Group_Step-3_Scren_shot.png

  4. You can now use your mirrored Terra group for accessing external resources (i.e.  j_doe_at_someplace_org@firecloud.org)
    Create-Terra-Group_Step-4_Screen_shot.png

2. Grant permission to a Terra Group (expand for step-by-step instructions)

  1. From the GCP console select the resource to be shared (i.e. a particular bucket in https://console.cloud.google.com/storage/browser)
    Grant-access-to-external-resource_Step-1_Screen_shot.png

  2. Go to Permissions
    Grant-access-to-external-resources_Step-2_Screen_shot.png
  3. View by "Members" and select the "Add" icon
    Grant-access-to-external-resources_Step-3_Screen_shot.png

  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" if you want to read from the bucket
    2. "Storage Object Creator" if you want to write to the bucket
      Grant-access-to-external-resources_Step-4_Screen_shot.png

You will see your Terra group and role in the Members Permissions
Grant-access-to-external-resources_Step-5_Screen_shot.png

 

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

G0_tip-icon.png


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. 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.

Accessing-external-resources_Google-bucket-on-dashboard_Screen_shot.png

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)

  1. From the GCP console select the resource to be shared (i.e. a particular bucket in https://console.cloud.google.com/storage/browser)
    Grant-access-to-external-resource_Step-1_Screen_shot.png

  2. Go to Permissions
    Grant-access-to-external-resources_Step-2_Screen_shot.png
  3. View by "Members" and select the "Add" icon
    Grant-access-to-external-resources_Step-3_Screen_shot.png

  4. 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.
    G0_tip-icon.png


    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 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.

     

      • Grant-access-to-external-resources_Step-4_Screen_shot.png
    G0_tip-icon.png


    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.

     

    You will see your Terra group and role in the Members Permissions
    Grant-access-to-external-resources_Step-5_Screen_shot.png

     

 

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

Go to "Profiles" from the main navigation menu (three lines at the top of any page on Terra).

Access-profile-page_Screen_shot.png

You'll see your proxy group listed near the bottom:

Advanced-GCP-features_Add-proxy-group-Step2-Find-proxy.png

2. Grant permission to your proxy group

To do this, you'll just need to add your proxy group email to the access list of your external bucket:

TPHPDc2aofOdVnJ697NHbA.png

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk