Create a volume (AWS IAM role)
Navigation
- Amazon Web Services Simple Storage Service (AWS S3) Volumes
- Attach an Amazon Web Services (AWS) volume volume using an IAM user
- Attach an Amazon Web Services (AWS) volume using an IAM role:
- Via the visual interface
- Via the API:
- Create a volume (AWS IAM role)
- Get details of a volume (AWS IAM role)
- Update a volume (AWS IAM role)
This call creates a new volume using the AWS IAM role connection method. Prior to connecting a volume, make sure you have set up the custom IAM policy and IAM role in the AWS Management Console.
Request
https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/volumes
POST /v2/storage/volumes HTTP/1.1
Host: api.sb.biodatacatalyst.nhlbi.nih.gov
X-SBG-Auth-Token: 3210a98c1db9304ea9d9273156740f74
Content-Type: application/json
curl - -data '@create-volume.json' -X POST -H "X-SBG-Auth-Token: 3210a98c1db9304ea9d9273156740f74" -H "Content-Type: application/json" 'https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/volumes'
Header Fields
| Key | Description of value |
|---|---|
X-SBG-Auth-Tokenrequired | Your Platform authentication token. |
Content-typerequired | application/json |
Request body
In the body, you should enter a list of key-value pairs. The keys and the values they take are described in the following table.
| Key | Data type | Description |
|---|---|---|
namerequired | String | The name of the volume. It must be unique from all other volumes for this user. |
access_mode | String | Signifies whether this volume should be used for read-write ("RW") or read-only ("RO") operations.The access mode is consulted independently of the credentials granted to Seven Bridges when the volume was created, so it is possible to use a read-write credentials to register both read-write and read-only volumes using it. default: "RW" |
description | String | An optional description of this volume. |
servicerequired | Object | This object should contain the information about the cloud service that this volume represents. See the service object section below for an explanation of its structure. |
| Key | Data type of value | Description of value |
|---|---|---|
type | string | The type of cloud service which is "s3" for Amazon Web Services. |
prefix | String | A service-specific prefix to prepend to all objects created in this volume. If the service supports folders, and this prefix includes them, the API will attempt to create any missing folders when it outputs a file. default: "" |
bucketrequired | String | The name of the AWS S3 bucket you wish to register as a volume. |
endpointdefault: s3.amazonaws.com | String | Cloud provider API endpoint to use when accessing this bucket. For a list of AWS-supported endpoints, see AWS Regions and Endpoints. |
credentials | Object | This object contains authentication parameters of your AWS IAM Role: - external_id (optional, used if an External ID is defined as required in for the role in the AWS console)- role_arn |
external_id | String | Optional information that you can use in an IAM role trust policy to designate who can assume the role. Must be provided if it is configured in your role trust policy on AWS. More info. |
role_arn | String | The ARN (Amazon Resource Name) of your role that is used to connect your S3 bucket. |
properties | Object | Contains the properties of a specific service. These values set the defaults for operations performed with this volume. Individual operations can override these defaults by providing a custom properties object. |
sse_algorithm | String | S3 server-side encryption to use when exporting to this bucket. (Support for SSE-KMS and SSE-C will be added in a later release.) Supported values: - AES256 (SSE-S3 encryption)- aws:kms- null (no server-side encryption).default: AES256 |
sse_aws_kms_key_id | String | Provide your AWS KMS ID here if you specify aws:kms as your sse_algorithm. Learn more about AWS KMS. |
aws_canned_acl | S3 canned ACL to apply on the object during export. Supported values: - any one of S3 canned ACLs; - null (does not apply canned ACLs).default: null |
{
"name": "my_s3_volume",
"service": {
"type": "s3",
"bucket": "input_files",
"credentials": {
"external_id": "external-volume-id-1234",
"role_arn": "arn:aws:iam::123456789012:role/test-volume-00"
}
},
"access_mode": "RO"
}
Response
See a list of Platform-specific response codes that may be contained in the body of the response.
{
"href": "https://api.sb.biodatacatalyst.nhlbi.nih.gov/v2/storage/volumes/rfranklin/my_volume",
"id": "rfranklin/my_volume",
"name": "my_s3_volume",
"access_mode": "RO",
"service": {
"type": "S3",
"bucket": "input_files",
"endpoint": "s3.amazonaws.com",
"credentials": {
"external_id": "external-volume-id-1234",
"role_arn": "arn:aws:iam::123456789012:role/test-volume-00"
},
"properties": {
"sse_algorithm": "aws:kms",
"sse_aws_kms_key_id": "test_kms_key_id"
}
},
"created_on": "2020-07-21T08:23:39Z",
"modified_on": "2020-07-21T08:23:39Z",
"active": true
}