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://cavatica-api.sbgenomics.com/v2/storage/volumes

Example request

POST /v2/storage/volumes HTTP/1.1
Host: cavatica-api.sbgenomics.com
X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74
Content-Type: application/json

curl - -data '@create-volume.json' -X POST -H "X-SBG-Auth-Token: 3210a98c1db9318fa9d9273156740f74" -H "Content-Type: application/json" 'https://cavatica-api.sbgenomics.com/v2/storage/volumes'

Header Fields

Key	Description of value
`X-SBG-Auth-Token` required	Your Cavatica 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.

Key	Data type	Description
`name` required	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.
`service` required	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.

###AWS service object

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:_ `""`
`bucket` required	String	The name of the AWS S3 bucket you wish to register as a volume.
`endpoint` default_: 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 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 Cavatica-specific response codes that may be contained in the body of the response.

Example response body

{
  "href": "https://cavatica-api.sbgenomics.com/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
}