Synapse provides physical storage for files using Amazon S3, however, you can configure your own custom storage locations as well. For example, data files can physically reside in your own S3 bucket, SFTP serversGoogle Cloud Storage Bucket, or a local file server using a proxy servers. Creating a custom storage location allows you greater ownership and control of your files, especially when you have a large amount of data or when additional restrictions need to be set on the data.
...
This article will describe two ways to setup an External external AWS S3 Bucketbucket:
Setup with AWS Console: Manual setup using the AWS Console.
Setup with AWS Cloudformation: Automated setup using AWS Cloudformation.
...
To add files to Synapse that are already in your bucket, see Adding Files in Your S3 Bucket to Synapse belowsee below.
Read-
...
Write Permissions
To allow authorized Synapse users to upload data to your bucket, read-write permissions need to be set on that bucket so you can allow Synapse to upload and retrieve files:
| Code Block |
|---|
{
"Statement": [
{
"Action": [ "s3:ListBucket*", "s3:GetBucketLocation" ],
"Effect": "Allow",
"Resource": "arn:aws:s3:::thisisthenameofmybucket",
"Principal": { "AWS": "325565585839" }
},
{
"Action": [ "s3:GetObject", "s3:PutObject", "s3:*Object*DeleteObject", "s3:*MultipartUpload*AbortMultipartUpload" ],
"Effect": "Allow",
"Resource": "arn:aws:s3:::thisisthenameofmybucket/*",
"Principal": { "AWS": "325565585839" }
}
]
}
|
For read-write permissionsTo register the bucket with Synapse, you also need to create an object that proves to the Synapse service that you own this bucket. This can be done by creating a file named owner.txt that contains a line separated list a line or comma separated list of user identifiers that are allowed to register and upload to the bucket. Valid user identifiers are a numeric Synapse user ID or the numeric id ID of a team that you are a member of.
...
| Code Block |
|---|
# copy your owner.txt file to your s3 bucket aws s3 cp owner.txt s3://nameofmybucket/nameofmyfolder |
Read-
...
Only Permissions
If you do not want to allow authorized Synapse users to upload data to your bucket but provide read access instead, you can change the permissions to read-only:
| Code Block |
|---|
{
"Statement": [
{
"Action": [ "s3:ListBucket*", "s3:GetBucketLocation" ],
"Effect": "Allow",
"Resource": "arn:aws:s3:::synapse-share.yourcompany.com",
"Principal": { "AWS": "325565585839" }
},
{
"Action": [ "s3:GetObject*" ],
"s3:*MultipartUpload*" ],
"Effect": "Allow",
"Resource": "arn:aws:s3:::synapse-share.yourcompany.com/*",
"Principal": { "AWS": "325565585839" }
}
]
}
|
Enable
...
Cross-Origin Resource Sharing (CORS)
In Permissions, click CORS configuration. In the CORS configuration editor, edit the configuration so that Synapse is included in the AllowedOrigin tag. An example CORS configuration that would allow this is:
...
For convienance, AWS Cloudformation can be used to provision a custom AWS S3 bucket for use with Synapse. Using this approach will result in the exact same bucket as described in Setup with AWS Console.
Instructions:
Download the CF template.
Use the AWS Command Line or AWS Console to execute the template which will automatically provision the bucket.
Example using the the awscli:
...
| Code Block |
|---|
# (Optional) true for read-write, false (default) for read-only bucket AllowWriteBucket: 'true' # (Optional) true (default) to encrypt bucket, false for no encryption EncryptBucket: 'false' # (Optional) 'Enabled' to enable bucket versioning, default is 'Suspended' BucketVersioning: 'Enabled' # (Optional) 'Enabled' to enable bucket data life cycle rule, default is 'Disabled' EnableDataLifeCycle: 'Enabled' # (Optional) S3 bucket objects will transition into this storage class: GLACIER(default), STANDARD_IA, ONEZONE_IA LifecycleDataStorageClass: 'STANDARD_IA' # (Optional) Number of days until S3 objects are moved to the LifecycleDataStorageClass, default is 30 LifecycleDataTransition: '90' # (Optional) Number of days (from creation) when objects are deleted from S3 and LifecycleDataStorageClass, default is 365000 LifecycleDataExpiration: '1825' # (Optional) Restrict downloading files from this bucket to only AWS resources (e.g. EC2 , Lambda) within the same region as this bucket. default is false. SameRegionResourceAccessToBucket: 'true' |
After executing the cloudformation Cloudformation command, view the AWS cloudformation Cloudformation dashboard to verify whether the bucket was provisioned successfully.
Set S3 Bucket as Upload Location
By default, your Projectyour project/Folder uses folder uses Synapse’s default S3 storage location. You can use the external bucket configured above via the web or programmatic clients.
Web
Navigate to your Project/Folder -> Tools -> your project or folder of interest, then select Tools, and Change Storage Location. In the resulting pop-up, select the Amazon S3 Bucket option and fill in the relevant information, where Bucket is the name of your external bucket, the optional Base Key is the name of the folder in your bucket to upload to, and Banner is a short description such as who owns the storage location:
...
| Code Block | ||
|---|---|---|
| ||
#set storage location
library(synapser)
library(rjson)
synLogin()
projectId <- 'syn12345'
destination <- list(uploadType='S3',
concreteType='org.sagebionetworks.repo.model.project.ExternalS3StorageLocationSetting',
bucket='nameofyourbucket')
destination <- synRestPOST('/storageLocation', body=toJSON(destination))
projectDestination <- list(concreteType='org.sagebionetworks.repo.model.project.UploadDestinationListSetting',
settingsType='upload')
projectDestination$locations <- list(destination$storageLocationId)
projectDestination$projectId <- projectId
projectDestination <- synRestPOST('/projectSettings', body=toJSON(projectDestination))
|
Adding Files in
...
your S3 Bucket to Synapse
If your bucket is set for read-write access, files can be added to the bucket using the standard Synapse interface (web or programmatic).
...
See the REST docs for more information on setting external storage location settings using our REST API.
Setting
...
up an External Google Cloud Storage Bucket
Follow the documentation on Google Cloud’s site to Create a Bucket.
...
Select the newly created bucket and click the Permissions tab.
Select the Add members button and enter the member
synapse-svc-prod@uplifted-crow-246820.iam.gserviceaccount.com. This is Synapse’s service account. Give the account the permissions Storage Legacy Bucket Reader and Storage Object Viewer for read permission. To allow Synapse to upload files, additionally grant the Storage Legacy Bucket Writer permission.
For read-write permissionsTo register the bucket with Synapse, you also need to create an object that proves to the Synapse service that you own this bucket. This can be done by creating a file named owner.txt that contains a line or comma separated list of user identifiers that are allowed to register the bucket and uploading it to your bucket. Valid user identifiers are: a Synapse user ID or the ID of a team that you are a member of.
...
The ID of the user or the team can be obtained by navigating to the user profile or to the team page, the ID is the numeric value shown in the browser URL bar after the Profile: or Team: prefixes:
...
You can upload the file with the Google Cloud Platform Console, or using the command line gsutil application.
...
| Info |
|---|
Note: Files in an external bucket will not be automatically added to Synapse. |
To add files to Synapse that are already in your bucket, see Adding Files in Your S3 Bucket to Synapse below.
Command line
see below.
Command line
| Code Block |
|---|
# copy your owner.txt file to your s3 bucket gsutil cp owner.txt gs://nameofmybucket/nameofmyfolder |
...
Navigate to your bucket on the Google Cloud Console and select the Upload files button to upload your text file into the folder where you want your data.
Enable
...
Cross-Origin Resource Sharing (CORS)
Follow the instructions for Setting CORS on a bucket. You may have to install the gsutil application.
...
Set Google Cloud Bucket as Upload Location
By default, your Project project uses the Synapse default storage location. You can use the external bucket configured above via our programmatic clients or web client.
...
| Code Block |
|---|
#set storage location
library(synapser)
library(rjson)
synLogin()
projectId <- 'syn12345'
destination <- list(uploadType='GOOGLECLOUDSTORAGE',
concreteType='org.sagebionetworks.repo.model.project.ExternalGoogleCloudStorageLocationSetting',
bucket='nameofyourbucket',
baseKey='nameOfSubfolderInBucket' # optional, only necessary if using a subfolder in your bucket
}
)
destination <- synRestPOST('/storageLocation', body=toJSON(destination))
projectDestination <- list(concreteType='org.sagebionetworks.repo.model.project.UploadDestinationListSetting',
settingsType='upload')
projectDestination$locations <- list(destination$storageLocationId)
projectDestination$projectId <- projectId
projectDestination <- synRestPOST('/projectSettings', body=toJSON(projectDestination))
|
Web
Navigate to your Project/Folder -> Tools -> your project or folder of interest, then select Tools, and Change Storage Location. In the resulting pop-up, select the Google Cloud Storage Bucket option and fill in the relevant information, where Bucket is the name of your external bucket, Base Key is the name of the folder in your bucket to upload to, and Banner is a short description such as who owns the storage location.
...
Please see the REST docs for more information on setting external storage location settings using our REST API.
Using SFTP
To setup an SFTP as a storage location, the settings on the Project need to be changed, specifically the storageLocation needs to be set. This is best done using either R or Python but has alpha support in the web browser. Customize the code below to set the storage location as your SFTP server:
Python
| Code Block |
|---|
import synapseclient
import json
syn = synapseclient.login()
destination = { "uploadType":"SFTP",
"concreteType":"org.sagebionetworks.repo.model.project.ExternalStorageLocationSetting",
"description":"My SFTP upload location",
"supportsSubfolders":True,
"url":"sftp://your-sftp-server.com",
"banner":"A descriptive banner, tada!"}
destination = syn.restPOST('/storageLocation', body=json.dumps(destination))
project_destination = {"concreteType":"org.sagebionetworks.repo.model.project.UploadDestinationListSetting",
"settingsType":"upload"}
project_destination['projectId'] = PROJECT
project_destination['locations'] = [destination['storageLocationId']]
project_destination = syn.restPOST('/projectSettings', body = json.dumps(project_destination))
|
R
| Code Block |
|---|
library(synapseClient)
synapseLogin()
projectId <- 'syn12345'
destination <- list(uploadType='SFTP',
concreteType='org.sagebionetworks.repo.model.project.ExternalStorageLocationSetting',
description='My SFTP upload location',
supportsSubfolders=TRUE,
url='https://your-sftp-server.com',
banner='A descriptive banner, tada!')
destination <- synRestPOST('/storageLocation', body=destination)
projectDestination <- list(concreteType='org.sagebionetworks.repo.model.project.UploadDestinationListSetting',
settingsType='upload')
projectDestination$locations <- list(destination$storageLocationId)
projectDestination$projectId <- projectId
projectDestination <- synRestPOST('/projectSettings', body = projectDestination)
|
Using a Proxy to Access a Local File Server or SFTP Server
For files stored outside of Amazon, an additional proxy is needed to validate the pre-signed URL and then proxy the requested file contents. View more information here about the process as well as about creating a local proxy or a SFTP proxy.
Set Project Settings for a Local Proxy
You must have a key (“your_secret_key”) to allow Synapse to interact with the filesystem.
Python
| Code Block | ||
|---|---|---|
| ||
import synapseclient
import json
syn = synapseclient.login()
PROJECT = 'syn12345'
destination = {"uploadType":"PROXYLOCAL",
"secretKey":"your_secret_key",
"proxyUrl":"https://your-proxy.prod.sagebase.org",
"concreteType":"org.sagebionetworks.repo.model.project.ProxyStorageLocationSettings"}
destination = syn.restPOST('/storageLocation', body=json.dumps(destination))
project_destination ={"concreteType": "org.sagebionetworks.repo.model.project.UploadDestinationListSetting",
"settingsType": "upload"}
project_destination['locations'] = [destination['storageLocationId']]
project_destination['projectId'] = PROJECT
project_destination = syn.restPOST('/projectSettings', body = json.dumps(project_destination))
|
R
| Code Block | ||
|---|---|---|
| ||
library(synapser)
synLogin()
projectId <- 'syn12345'
destination <- list(uploadType='PROXYLOCAL',
secretKey='your_secret_key',
proxyUrl='https://your-proxy.prod.sagebase.org',
concreteType='org.sagebionetworks.repo.model.project.ProxyStorageLocationSettings')
destination <- synRestPOST('/storageLocation', body=toJSON(destination))
projectDestination <- list(concreteType='org.sagebionetworks.repo.model.project.UploadDestinationListSetting',
settingsType='upload')
projectDestination$locations <- list(destination$storageLocationId)
projectDestination$projectId <- projectId
projectDestination <- synRestPOST('/projectSettings', body=toJSON(projectDestination))
|
Set Project Settings for a SFTP Proxy
You must have a key (“your_secret_key”) to allow Synapse to interact with the filesystem.
Python
| Code Block |
|---|
import synapseclient
import json
syn = synapseclient.login()
PROJECT = 'syn12345'
destination = {"uploadType":"SFTP",
"secretKey":"your_secret_key",
"proxyUrl":"https://your-proxy.prod.sagebase.org",
"concreteType":"org.sagebionetworks.repo.model.project.ProxyStorageLocationSettings"}
destination = syn.restPOST('/storageLocation', body=json.dumps(destination))
project_destination ={"concreteType": "org.sagebionetworks.repo.model.project.UploadDestinationListSetting",
"settingsType": "upload"}
project_destination['locations'] = [destination['storageLocationId']]
project_destination['projectId'] = PROJECT
project_destination = syn.restPOST('/projectSettings', body = json.dumps(project_destination))
|
R
| Code Block |
|---|
library(synapser)
synLogin()
projectId <- 'syn12345'
destination <- list(uploadType='SFTP',
secretKey='your_secret_key',
proxyUrl='https://your-proxy.prod.sagebase.org',
concreteType='org.sagebionetworks.repo.model.project.ProxyStorageLocationSettings')
destination <- synRestPOST('/storageLocation', body=toJSON(destination))
projectDestination <- list(concreteType='org.sagebionetworks.repo.model.project.UploadDestinationListSetting',
settingsType='upload')
projectDestination$locations <- list(destination$storageLocationId)
projectDestination$projectId <- projectId
projectDestination <- synRestPOST('/projectSettings', body=toJSON(projectDestination))
|