{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Volumes","type":"basic","slug":"volumes","excerpt":"","body":"##What is a volume?\n\nCloud storage providers come with their own interfaces, features and terminology. At a certain level, though, they all view resources as data objects organized in repositories. Authentication and operations are commonly defined on those objects and repositories, and while each cloud provider might call these things different names and apply different parameters to them, their basic behavior is the same.\n\nCavatica mediates access to these repositories using volumes. A volume is associated with a particular cloud storage repository that you have enabled Seven Bridges to read from (and, optionally, to write to).\n\nCurrently, volumes may be created using three types of cloud storage repository: \n* Amazon Web Services' (AWS) S3 buckets\n* Google Cloud Storage (GCS) buckets\n* Other types of cloud storage, through an S3-compatible API (read-only). This cloud storage type requires an additional API layer that the storage employs, which must use the same \"language\" as the AWS S3 API. \n\nA volume enables you to treat the cloud repository associated with it as external storage for Cavatica.\n\n##What information should I provide?\nTo create a volume on Cavatica, you should provide the following information:\n \n###Volume name\nA volume name consists of 3-32 letters of the English alphabet, numbers, and underscores (_). Each of your volumes must have a unique name.\n\n###Access mode\nThe access mode of a volume is either read-only (`RO`) or read-write (`RW`).\nEach volume will have its access mode set by default to read-only. Volumes from cloud providers other than AWS S3 and Google Cloud Storage can be connected in read-only mode.\n\nRead-only volumes can only be used to make files available to Cavatica for reading; for example, by importing files into projects. Read-write volumes' contents can be modified by operations performed with the Volumes API. Note that regardless of access mode, the owner of the volume is still the only Cavatica account that can issue operations on that volume. However, it is a good practice to avoid configuring your input buckets as read-write, as a safeguard against honest mistakes.\n \n###Cloud service configuration\nTo access the cloud storage provider on your behalf, Cavatica needs to know the type of storage provider it should talk to, and be configured to interface with it.\n\nAs each cloud storage provider supports slightly different features and authorization schemas, the configuration will be different for each storage type. Depending on your selected storage provider and your intended use of the volume, there might be additional properties you may want to set to further modify the way Cavatica accesses it.\n\nFor more details on each supported storage type and its corresponding configuration, see the following pages:\n\n* [Amazon Web Services' Simple Storage Service (AWS S3) Volumes](doc:attach-an-amazon-web-services-s3-volume) \n* [Google Cloud Storage (GCS) Volumes](doc:attach-a-google-cloud-storage-volume) \n* [Attach a volume from other cloud providers through an S3-compatible endpoint](doc:attach-a-volume-from-another-cloud-provider-through-an-s3-compatible-api)\n\n \n<a name=\"prefix\"></a>\n<h3>Prefix <span style=\"font-size:10px\">(optional)</span></h3>\n\nA prefix is a string that can be set on a volume to refer to a specific location on a single bucket. This feature can be used to replicate the folder or grouping structure inside a bucket in your cloud storage account. As such, a prefix is useful if you have grouped files devoted to distinct projects within a single bucket.\n\nFor example, on Amazon S3, folders can also be assigned specific access permissions in the bucket policy itself, or an IAM user can be configured to have read-only or read-write access per each folder. When you assign your volume a prefix as well as a bucket, you limit the volume's operations within the specified folder on the bucket.\n\nFor example, if you set the `prefix` for a volume to `\"a10\"`, and import a file with `location` set to `\"test.fastq\"` from the volume to Cavatica, then the object that will be referred to by the newly-created alias will be `\"a10/test.fastq\"`.\n\n \n##What can I do with a volume?\nOnce a volume has been configured, you can make its data objects available for computation on Cavatica, and, conversely, and copy files to the volume from Cavatica. \n\nThese operations can be carried out through the visual interface or using the Volumes API. All API calls are listed in the Volumes section of the API documentation.\n\n###Operations on volumes\n  * [Create a volume](doc:create-a-volume-v2) \n  * [List volumes](doc:list-volumes-v2) \n  * [Get details of a volume](doc:get-details-of-a-volume-v2)\n  * [Update a volume](doc:update-a-volume-v2) \n  * [Delete a volume](doc:delete-a-volume-v2) \n  * [Start an import job](doc:start-an-import-job-v2) \n  * [Get details of an import job](doc:get-details-of-an-import-job-v2) \n  * [Start an export job](doc:start-an-export-job-v2) \n  * [List export jobs](doc:list-export-jobs-v2) \n  * [List import jobs](doc:list-import-jobs-v2)","updates":[],"order":0,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"60423a32bc05b80071b10758","createdAt":"2021-03-05T14:03:30.969Z","user":"5767bc73bb15f40e00a28777","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Connect cloud storage","slug":"connect-cloud-storage","order":20,"from_sync":false,"reference":false,"_id":"5f0839d3f4b24e005ebbbc29","createdAt":"2020-07-10T09:50:11.713Z","version":"5773dcfc255e820e00e1cd50","project":"5773dcfc255e820e00e1cd4d","__v":0},"version":{"version":"1.0","version_clean":"1.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["5773dcfc255e820e00e1cd51","5773df36904b0c0e00ef05ff","577baf92451b1e0e006075ac","577bb183b7ee4a0e007c4e8d","577ce77a1cf3cb0e0048e5ea","577d11865fd4de0e00cc3dab","578e62792c3c790e00937597","578f4fd98335ca0e006d5c84","578f5e5c3d04570e00976ebb","57bc35f7531e000e0075d118","57f801b3760f3a1700219ebb","5804d55d1642890f00803623","581c8d55c0dc651900aa9350","589dcf8ba8c63b3b00c3704f","594cebadd8a2f7001b0b53b2","59a562f46a5d8c00238e309a","5a2aa096e25025003c582b58","5a2e79566c771d003ca0acd4","5a3a5166142db90026f24007","5a3a52b5bcc254001c4bf152","5a3a574a2be213002675c6d2","5a3a66bb2be213002675cb73","5a3a6e4854faf60030b63159","5c8a68278e883901341de571","5cb9971e57bf020024523c7b","5cbf1683e2a36d01d5012ecd","5dc15666a4f788004c5fd7d7","5eaff69e844d67003642a020","5eb00899b36ba5002d35b0c1","5eb0172be179b70073dc936e","5eb01b42b36ba5002d35ebba","5eb01f202654a20136813093","5eb918ef149186021c9a76c8","5f0839d3f4b24e005ebbbc29","5f893e508c9862002d0614a9","6024033e2b2f6f004dfe994c"],"_id":"5773dcfc255e820e00e1cd50","__v":36,"createdAt":"2016-06-29T14:36:44.812Z","releaseDate":"2016-06-29T14:36:44.812Z","project":"5773dcfc255e820e00e1cd4d"},"project":"5773dcfc255e820e00e1cd4d","__v":0,"parentDoc":null}
##What is a volume? Cloud storage providers come with their own interfaces, features and terminology. At a certain level, though, they all view resources as data objects organized in repositories. Authentication and operations are commonly defined on those objects and repositories, and while each cloud provider might call these things different names and apply different parameters to them, their basic behavior is the same. Cavatica mediates access to these repositories using volumes. A volume is associated with a particular cloud storage repository that you have enabled Seven Bridges to read from (and, optionally, to write to). Currently, volumes may be created using three types of cloud storage repository: * Amazon Web Services' (AWS) S3 buckets * Google Cloud Storage (GCS) buckets * Other types of cloud storage, through an S3-compatible API (read-only). This cloud storage type requires an additional API layer that the storage employs, which must use the same "language" as the AWS S3 API. A volume enables you to treat the cloud repository associated with it as external storage for Cavatica. ##What information should I provide? To create a volume on Cavatica, you should provide the following information: ###Volume name A volume name consists of 3-32 letters of the English alphabet, numbers, and underscores (_). Each of your volumes must have a unique name. ###Access mode The access mode of a volume is either read-only (`RO`) or read-write (`RW`). Each volume will have its access mode set by default to read-only. Volumes from cloud providers other than AWS S3 and Google Cloud Storage can be connected in read-only mode. Read-only volumes can only be used to make files available to Cavatica for reading; for example, by importing files into projects. Read-write volumes' contents can be modified by operations performed with the Volumes API. Note that regardless of access mode, the owner of the volume is still the only Cavatica account that can issue operations on that volume. However, it is a good practice to avoid configuring your input buckets as read-write, as a safeguard against honest mistakes. ###Cloud service configuration To access the cloud storage provider on your behalf, Cavatica needs to know the type of storage provider it should talk to, and be configured to interface with it. As each cloud storage provider supports slightly different features and authorization schemas, the configuration will be different for each storage type. Depending on your selected storage provider and your intended use of the volume, there might be additional properties you may want to set to further modify the way Cavatica accesses it. For more details on each supported storage type and its corresponding configuration, see the following pages: * [Amazon Web Services' Simple Storage Service (AWS S3) Volumes](doc:attach-an-amazon-web-services-s3-volume) * [Google Cloud Storage (GCS) Volumes](doc:attach-a-google-cloud-storage-volume) * [Attach a volume from other cloud providers through an S3-compatible endpoint](doc:attach-a-volume-from-another-cloud-provider-through-an-s3-compatible-api) <a name="prefix"></a> <h3>Prefix <span style="font-size:10px">(optional)</span></h3> A prefix is a string that can be set on a volume to refer to a specific location on a single bucket. This feature can be used to replicate the folder or grouping structure inside a bucket in your cloud storage account. As such, a prefix is useful if you have grouped files devoted to distinct projects within a single bucket. For example, on Amazon S3, folders can also be assigned specific access permissions in the bucket policy itself, or an IAM user can be configured to have read-only or read-write access per each folder. When you assign your volume a prefix as well as a bucket, you limit the volume's operations within the specified folder on the bucket. For example, if you set the `prefix` for a volume to `"a10"`, and import a file with `location` set to `"test.fastq"` from the volume to Cavatica, then the object that will be referred to by the newly-created alias will be `"a10/test.fastq"`. ##What can I do with a volume? Once a volume has been configured, you can make its data objects available for computation on Cavatica, and, conversely, and copy files to the volume from Cavatica. These operations can be carried out through the visual interface or using the Volumes API. All API calls are listed in the Volumes section of the API documentation. ###Operations on volumes * [Create a volume](doc:create-a-volume-v2) * [List volumes](doc:list-volumes-v2) * [Get details of a volume](doc:get-details-of-a-volume-v2) * [Update a volume](doc:update-a-volume-v2) * [Delete a volume](doc:delete-a-volume-v2) * [Start an import job](doc:start-an-import-job-v2) * [Get details of an import job](doc:get-details-of-an-import-job-v2) * [Start an export job](doc:start-an-export-job-v2) * [List export jobs](doc:list-export-jobs-v2) * [List import jobs](doc:list-import-jobs-v2)