Cloud Management API 1.5

Volumes

A Volume provides a highly reliable, efficient and persistent storage solution that can be mounted to a cloud instance (in the same datacenter / zone).

Actions

index
show
create
update
destroy

index

Lists volumes.

URLs: GET /api/clouds/:cloud_id/volumes
HTTP response code: 200 OK
Content-type: application/vnd.rightscale.volume;type=collection

Required roles

observer||instance

Parameters

name	required	type	values	regexp	blank?	description
filter	no	Array	*	*	no	See below for valid filter parameters.
view	no	String	default, extended	*	no	Specifies how many attributes and/or expanded nested relationships to include.

Filters

name	partial_match?	description
datacenter_href	no	The href of the Datacenter / Zone the Volume is in.
deployment_href	no	Deployment href to filter on.
description	yes	The description of the Volume to filter on.
name	yes	The name of the Volume to filter on.
parent_volume_snapshot_href	no	The href of the snapshot from which the volume was created.
resource_uid	no	Resource Unique IDentifier for the Volume to filter on.

Example Responses

Click on a format below to see an example response for the 'default' view:

JSON XML

[{
  "created_at": null,
  "updated_at": "2023/10/09 11:06:01 +0000",
  "name": "NAME_1978450230",
  "resource_uid": "RESOURCE_1166705757",
  "size": 1,
  "description": "DESCRIPTION_1978877528",
  "status": "in-use",
  "cloud_specific_attributes": null,
  "links": [
    {"rel":"self","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705"},
    {"rel":"cloud","href":"/api/clouds/888"},
    {"rel":"datacenter","href":"/api/clouds/888/datacenters/RESOURCE_2387280756;RAND"},
    {"rel":"volume_snapshots","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/volume_snapshots"},
    {"rel":"current_volume_attachment","href":"/api/clouds/888/volume_attachments/RESOURCE_2001687115;3956794654"},
    {"rel":"recurring_volume_attachments","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/recurring_volume_attachments"}
  ],
  "actions": [

  ]
},{
  "created_at": null,
  "updated_at": "2023/10/09 11:06:02 +0000",
  "name": "NAME_1267233762",
  "resource_uid": "RESOURCE_128588983",
  "size": 1,
  "description": "DESCRIPTION_715559168",
  "status": "in-use",
  "cloud_specific_attributes": null,
  "links": [
    {"rel":"self","href":"/api/clouds/888/volumes/RESOURCE_128588983;3087885902"},
    {"rel":"cloud","href":"/api/clouds/888"},
    {"rel":"datacenter","href":"/api/clouds/888/datacenters/RESOURCE_1950696832;RAND"},
    {"rel":"volume_snapshots","href":"/api/clouds/888/volumes/RESOURCE_128588983;3087885902/volume_snapshots"},
    {"rel":"current_volume_attachment","href":"/api/clouds/888/volume_attachments/RESOURCE_3206404625;2839410080"},
    {"rel":"recurring_volume_attachments","href":"/api/clouds/888/volumes/RESOURCE_128588983;3087885902/recurring_volume_attachments"}
  ],
  "actions": [

  ]
}]

<?xml version="1.0" encoding="UTF-8"?>
<volumes>
  <volume>
    <created_at/>
    <updated_at>2023/10/09 11:06:01 +0000</updated_at>
    <name>NAME_1978450230</name>
    <resource_uid>RESOURCE_1166705757</resource_uid>
    <size>1</size>
    <description>DESCRIPTION_1978877528</description>
    <status>in-use</status>
    <cloud_specific_attributes/>
    <links>
      <link rel="self" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705"/>
      <link rel="cloud" href="/api/clouds/888"/>
      <link rel="datacenter" href="/api/clouds/888/datacenters/RESOURCE_2387280756;RAND"/>
      <link rel="volume_snapshots" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/volume_snapshots"/>
      <link rel="current_volume_attachment" href="/api/clouds/888/volume_attachments/RESOURCE_2001687115;3956794654"/>
      <link rel="recurring_volume_attachments" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/recurring_volume_attachments"/>
    </links>
    <actions/>
  </volume>
  <volume>
    <created_at/>
    <updated_at>2023/10/09 11:06:02 +0000</updated_at>
    <name>NAME_1267233762</name>
    <resource_uid>RESOURCE_128588983</resource_uid>
    <size>1</size>
    <description>DESCRIPTION_715559168</description>
    <status>in-use</status>
    <cloud_specific_attributes/>
    <links>
      <link rel="self" href="/api/clouds/888/volumes/RESOURCE_128588983;3087885902"/>
      <link rel="cloud" href="/api/clouds/888"/>
      <link rel="datacenter" href="/api/clouds/888/datacenters/RESOURCE_1950696832;RAND"/>
      <link rel="volume_snapshots" href="/api/clouds/888/volumes/RESOURCE_128588983;3087885902/volume_snapshots"/>
      <link rel="current_volume_attachment" href="/api/clouds/888/volume_attachments/RESOURCE_3206404625;2839410080"/>
      <link rel="recurring_volume_attachments" href="/api/clouds/888/volumes/RESOURCE_128588983;3087885902/recurring_volume_attachments"/>
    </links>
    <actions/>
  </volume>
</volumes>

Click on a format below to see an example response for the 'extended' view:

JSON XML

[{
  "created_at": null,
  "updated_at": "2023/10/09 11:06:01 +0000",
  "name": "NAME_1978450230",
  "resource_uid": "RESOURCE_1166705757",
  "size": 1,
  "description": "DESCRIPTION_1978877528",
  "status": "in-use",
  "cloud_specific_attributes": null,
  "links": [
    {"rel":"self","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705"},
    {"rel":"cloud","href":"/api/clouds/888"},
    {"rel":"datacenter","href":"/api/clouds/888/datacenters/RESOURCE_2387280756;RAND"},
    {"rel":"volume_snapshots","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/volume_snapshots"},
    {"rel":"current_volume_attachment","href":"/api/clouds/888/volume_attachments/RESOURCE_2001687115;3956794654"},
    {"rel":"recurring_volume_attachments","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/recurring_volume_attachments"}
  ],
  "actions": [

  ]
},{
  "created_at": null,
  "updated_at": "2023/10/09 11:06:02 +0000",
  "name": "NAME_1267233762",
  "resource_uid": "RESOURCE_128588983",
  "size": 1,
  "description": "DESCRIPTION_715559168",
  "status": "in-use",
  "cloud_specific_attributes": null,
  "links": [
    {"rel":"self","href":"/api/clouds/888/volumes/RESOURCE_128588983;3087885902"},
    {"rel":"cloud","href":"/api/clouds/888"},
    {"rel":"datacenter","href":"/api/clouds/888/datacenters/RESOURCE_1950696832;RAND"},
    {"rel":"volume_snapshots","href":"/api/clouds/888/volumes/RESOURCE_128588983;3087885902/volume_snapshots"},
    {"rel":"current_volume_attachment","href":"/api/clouds/888/volume_attachments/RESOURCE_3206404625;2839410080"},
    {"rel":"recurring_volume_attachments","href":"/api/clouds/888/volumes/RESOURCE_128588983;3087885902/recurring_volume_attachments"}
  ],
  "actions": [

  ]
}]

<?xml version="1.0" encoding="UTF-8"?>
<volumes>
  <volume>
    <created_at/>
    <updated_at>2023/10/09 11:06:01 +0000</updated_at>
    <name>NAME_1978450230</name>
    <resource_uid>RESOURCE_1166705757</resource_uid>
    <size>1</size>
    <description>DESCRIPTION_1978877528</description>
    <status>in-use</status>
    <cloud_specific_attributes/>
    <links>
      <link rel="self" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705"/>
      <link rel="cloud" href="/api/clouds/888"/>
      <link rel="datacenter" href="/api/clouds/888/datacenters/RESOURCE_2387280756;RAND"/>
      <link rel="volume_snapshots" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/volume_snapshots"/>
      <link rel="current_volume_attachment" href="/api/clouds/888/volume_attachments/RESOURCE_2001687115;3956794654"/>
      <link rel="recurring_volume_attachments" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/recurring_volume_attachments"/>
    </links>
    <actions/>
  </volume>
  <volume>
    <created_at/>
    <updated_at>2023/10/09 11:06:02 +0000</updated_at>
    <name>NAME_1267233762</name>
    <resource_uid>RESOURCE_128588983</resource_uid>
    <size>1</size>
    <description>DESCRIPTION_715559168</description>
    <status>in-use</status>
    <cloud_specific_attributes/>
    <links>
      <link rel="self" href="/api/clouds/888/volumes/RESOURCE_128588983;3087885902"/>
      <link rel="cloud" href="/api/clouds/888"/>
      <link rel="datacenter" href="/api/clouds/888/datacenters/RESOURCE_1950696832;RAND"/>
      <link rel="volume_snapshots" href="/api/clouds/888/volumes/RESOURCE_128588983;3087885902/volume_snapshots"/>
      <link rel="current_volume_attachment" href="/api/clouds/888/volume_attachments/RESOURCE_3206404625;2839410080"/>
      <link rel="recurring_volume_attachments" href="/api/clouds/888/volumes/RESOURCE_128588983;3087885902/recurring_volume_attachments"/>
    </links>
    <actions/>
  </volume>
</volumes>

show

Displays information about a single volume.

URLs: GET /api/clouds/:cloud_id/volumes/:id
HTTP response code: 200 OK
Content-type: application/vnd.rightscale.volume

Required roles

observer||instance

Parameters

name	required	type	values	regexp	blank?	description
view	no	String	default, extended	*	no	Specifies how many attributes and/or expanded nested relationships to include.

Example Responses

Click on a format below to see an example response for the 'default' view:

JSON XML

{
  "created_at": null,
  "updated_at": "2023/10/09 11:06:01 +0000",
  "name": "NAME_1978450230",
  "resource_uid": "RESOURCE_1166705757",
  "size": 1,
  "description": "DESCRIPTION_1978877528",
  "status": "in-use",
  "cloud_specific_attributes": null,
  "links": [
    {"rel":"self","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705"},
    {"rel":"cloud","href":"/api/clouds/888"},
    {"rel":"datacenter","href":"/api/clouds/888/datacenters/RESOURCE_2387280756;RAND"},
    {"rel":"volume_snapshots","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/volume_snapshots"},
    {"rel":"current_volume_attachment","href":"/api/clouds/888/volume_attachments/RESOURCE_2001687115;3956794654"},
    {"rel":"recurring_volume_attachments","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/recurring_volume_attachments"}
  ],
  "actions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<volume>
  <created_at/>
  <updated_at>2023/10/09 11:06:01 +0000</updated_at>
  <name>NAME_1978450230</name>
  <resource_uid>RESOURCE_1166705757</resource_uid>
  <size>1</size>
  <description>DESCRIPTION_1978877528</description>
  <status>in-use</status>
  <cloud_specific_attributes/>
  <links>
    <link rel="self" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705"/>
    <link rel="cloud" href="/api/clouds/888"/>
    <link rel="datacenter" href="/api/clouds/888/datacenters/RESOURCE_2387280756;RAND"/>
    <link rel="volume_snapshots" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/volume_snapshots"/>
    <link rel="current_volume_attachment" href="/api/clouds/888/volume_attachments/RESOURCE_2001687115;3956794654"/>
    <link rel="recurring_volume_attachments" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/recurring_volume_attachments"/>
  </links>
  <actions/>
</volume>

Click on a format below to see an example response for the 'extended' view:

JSON XML

{
  "created_at": null,
  "updated_at": "2023/10/09 11:06:01 +0000",
  "name": "NAME_1978450230",
  "resource_uid": "RESOURCE_1166705757",
  "size": 1,
  "description": "DESCRIPTION_1978877528",
  "status": "in-use",
  "cloud_specific_attributes": null,
  "links": [
    {"rel":"self","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705"},
    {"rel":"cloud","href":"/api/clouds/888"},
    {"rel":"datacenter","href":"/api/clouds/888/datacenters/RESOURCE_2387280756;RAND"},
    {"rel":"volume_snapshots","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/volume_snapshots"},
    {"rel":"current_volume_attachment","href":"/api/clouds/888/volume_attachments/RESOURCE_2001687115;3956794654"},
    {"rel":"recurring_volume_attachments","href":"/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/recurring_volume_attachments"}
  ],
  "actions": [

  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<volume>
  <created_at/>
  <updated_at>2023/10/09 11:06:01 +0000</updated_at>
  <name>NAME_1978450230</name>
  <resource_uid>RESOURCE_1166705757</resource_uid>
  <size>1</size>
  <description>DESCRIPTION_1978877528</description>
  <status>in-use</status>
  <cloud_specific_attributes/>
  <links>
    <link rel="self" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705"/>
    <link rel="cloud" href="/api/clouds/888"/>
    <link rel="datacenter" href="/api/clouds/888/datacenters/RESOURCE_2387280756;RAND"/>
    <link rel="volume_snapshots" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/volume_snapshots"/>
    <link rel="current_volume_attachment" href="/api/clouds/888/volume_attachments/RESOURCE_2001687115;3956794654"/>
    <link rel="recurring_volume_attachments" href="/api/clouds/888/volumes/RESOURCE_1166705757;2332079705/recurring_volume_attachments"/>
  </links>
  <actions/>
</volume>

create

Creates a new volume.

URLs: POST /api/clouds/:cloud_id/volumes
HTTP response code: 201 Created
Location: Href of created Volume.

Required roles

actor||instance

Parameters

name	required	type	values	regexp	blank?	description
volume	yes	Hash	*	*	no
volume[datacenter_href]	no	String	*	*	no	The href of the Datacenter / Zone that the Volume will be in. This parameter is required for non-OpenStack clouds.
volume[deployment_href]	no	String	*	*	no	The href of the Deployment that owns this Volume.
volume[description]	no	String	*	*	no	The description of the Volume to be created.
volume[encrypted]	no	String	true, false	*	no	A flag indicating whether Volume should be encrypted. Only available on clouds supporting volume encryption.
volume[image_href]	no	String	*	*	no	The href of the Image that should be used as a source
volume[iops]	no	String	*	^\d+$	no	The number of IOPS (I/O Operations Per Second) this Volume should support. Only available on clouds supporting performance provisioning.
volume[name]	yes	String	*	*	no	The name for the Volume to be created.
volume[parent_volume_snapshot_href]	no	String	*	*	no	The href of the snapshot from which the volume will be created.
volume[placement_group_href]	no	String	*	*	no	The href of the Placement Group. This option can not be used in combination with parent_volume_snapshot_href.
volume[size]	no	String	*	^\d+$	no	The size of a Volume to be created in gigabytes (GB). Some Volume Types have predefined sizes and do not allow selecting a custom size on Volume creation.
volume[volume_type_href]	no	String	*	*	no	The href of the volume type. A Name, Resource UID and optional Size is associated with a Volume Type.

update

URLs: PUT /api/clouds/:cloud_id/volumes/:id
HTTP response code: 204 No Content

Required roles

actor||instance

Parameters

name	required	type	values	regexp	blank?	description
volume	yes	Hash	*	*	no
volume[allowed_instance_hrefs]	no	Hash	*	*	no	Used to update instances which are allowed to connect to this volume.
volume[allowed_instance_hrefs][add]	no	Array	*	*	no	Hrefs for instances to add into allowed list.
volume[allowed_instance_hrefs][remove]	no	Array	*	*	no	Hrefs for instances to remove from allowed list.
volume[name]	no	String	*	*	no	The new name for the Volume.

destroy

Deletes a given volume.

URLs: DELETE /api/clouds/:cloud_id/volumes/:id
HTTP response code: 204 No Content

Required roles

actor||instance

MediaTypes:

Resources:

Volumes

Actions

index

Required roles

Parameters

Filters

Example Responses

Click on a format below to see an example response for the 'default' view:

Click on a format below to see an example response for the 'extended' view:

show

Required roles

Parameters

Example Responses

Click on a format below to see an example response for the 'default' view:

Click on a format below to see an example response for the 'extended' view:

create

Required roles

Parameters

update

Required roles

Parameters

destroy

Required roles