GuidesAPI ReferenceRelease NotesTutorials
Create a volume (AWS IAM role)

Create a volume (AWS IAM role)

📘

Navigation

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

Example request

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

KeyDescription of value
X-SBG-Auth-Token
required		Your Platform authentication token.
Content-type
required		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.

KeyData typeDescription
name
required		StringThe name of the volume. It must be unique from all other volumes for this user.
access_modeStringSignifies 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"
descriptionStringAn optional description of this volume.
service
required		ObjectThis 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.


###AWS service object

KeyData type of valueDescription of value
typestringThe type of cloud service which is "s3" for Amazon Web Services.
prefixStringA 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: ""
bucket
required		StringThe name of the AWS S3 bucket you wish to register as a volume.
endpoint

default: s3.amazonaws.com		StringCloud provider API endpoint to use when accessing this bucket.

For a list of AWS-supported endpoints, see AWS Regions and Endpoints.
credentials    ObjectThis 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_idStringOptional 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_arnStringThe ARN (Amazon Resource Name) of your role that is used to connect your S3 bucket.
propertiesObjectContains 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_algorithmStringS3 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_idStringProvide your AWS KMS ID here if you specify aws:kms as your sse_algorithm. Learn more about AWS KMS.
aws_canned_aclS3 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

Example request body

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

Example response body

{
  "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
}