api-ref: os-volumes.inc
-Verified examples, parameters, body text. -Added snapshot status values, new force parameter for snapshots. Part of: bp/api-ref-in-rst Change-Id: I0c1d183c5aaf6fb796be30fa5627bd5644ea689f
This commit is contained in:
Karen Bradshaw
John Garbutt
parent
94c96f226a
commit
e551452d6c
@ -1,7 +1,4 @@
|
||||
.. -*- rst -*-
|
||||
.. needs:parameter_verification
|
||||
.. needs:example_verification
|
||||
.. needs:body_verification
|
||||
|
||||
=========================================================
|
||||
Volume extension (os-volumes, os-snapshots) (DEPRECATED)
|
||||
@ -16,6 +13,7 @@
|
||||
<http://developer.openstack.org/api-ref-blockstorage-v2.html#volumes-v2-volumes>`__.
|
||||
|
||||
Manages volumes and snapshots for use with the Compute API.
|
||||
Lists, shows details, creates, and deletes volumes and snapshots.
|
||||
|
||||
List Volumes
|
||||
============
|
||||
@ -26,12 +24,33 @@ Lists the volumes associated with the account.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
||||
Error response codes: unauthorized(401), forbidden(403)
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
**Example List Volumes: JSON response**
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- volumes: volumes
|
||||
- attachments: volumeAttachments
|
||||
- attachments.device: attachment_device_resp
|
||||
- attachments.id: attachment_id_resp
|
||||
- attachments.serverId: attachment_server_id_resp
|
||||
- attachments.volumeId: attachment_volumeId_resp
|
||||
- availabilityZone: OS-EXT-AZ:availability_zone
|
||||
- createdAt: created
|
||||
- displayDescription: display_description
|
||||
- displayName: display_name
|
||||
- id: volume_id_resp
|
||||
- metadata: metadata_set_required
|
||||
- size: size
|
||||
- snapshotId: snapshot_id
|
||||
- status: volume_status
|
||||
- volumeType: volume_type
|
||||
|
||||
|
|
||||
|
||||
**Example List Volumes**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-index-resp.json
|
||||
:language: javascript
|
||||
@ -41,12 +60,12 @@ Create Volume
|
||||
|
||||
.. rest_method:: POST /os-volumes
|
||||
|
||||
Creates a volume.
|
||||
Creates a new volume.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401),
|
||||
forbidden(403), itemNotFound(404)
|
||||
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
||||
itemNotFound(404)
|
||||
|
||||
Request
|
||||
-------
|
||||
@ -54,15 +73,15 @@ Request
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- volume: volume
|
||||
- display_name: display_name
|
||||
- display_description: display_description
|
||||
- size: size
|
||||
- volume_type: volume_type
|
||||
- availability_zone: OS-EXT-AZ:availability_zone_optional
|
||||
- display_name: display_name_optional
|
||||
- display_description: display_description_optional
|
||||
- metadata: metadata
|
||||
- availability_zone: availability_zone
|
||||
- snapshot_id: snapshot_id
|
||||
- volume_type: volume_type_optional
|
||||
- snapshot_id: snapshot_id_optional
|
||||
|
||||
**Example Create Volume: JSON request**
|
||||
**Example Create Volume**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-post-req.json
|
||||
:language: javascript
|
||||
@ -70,7 +89,28 @@ Request
|
||||
Response
|
||||
--------
|
||||
|
||||
**Example Create Volume: JSON response**
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- volume: volume
|
||||
- attachments: volumeAttachments
|
||||
- attachments.device: attachment_device_resp
|
||||
- attachments.id: attachment_id_resp
|
||||
- attachments.serverId: attachment_server_id_resp
|
||||
- attachments.volumeId: attachment_volumeId_resp
|
||||
- availabilityZone: OS-EXT-AZ:availability_zone
|
||||
- createdAt: created
|
||||
- displayName: display_name
|
||||
- displayDescription: display_description
|
||||
- id: volume_id_resp
|
||||
- metadata: metadata_set_required
|
||||
- size: size
|
||||
- snapshotId: snapshot_id
|
||||
- status: volume_status
|
||||
- volumeType: volume_type
|
||||
|
||||
|
|
||||
|
||||
**Example Create Volume**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-post-resp.json
|
||||
:language: javascript
|
||||
@ -84,12 +124,33 @@ Lists all volumes with details.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
||||
Error response codes: unauthorized(401), forbidden(403)
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
**Example List Volumes With Details: JSON response**
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- volumes: volumes
|
||||
- attachments: volumeAttachments
|
||||
- attachments.device: attachment_device_resp
|
||||
- attachments.id: attachment_id_resp
|
||||
- attachments.serverId: attachment_server_id_resp
|
||||
- attachments.volumeId: attachment_volumeId_resp
|
||||
- availabilityZone: OS-EXT-AZ:availability_zone
|
||||
- createdAt: created
|
||||
- displayName: display_name
|
||||
- displayDescription: display_description
|
||||
- id: volume_id_resp
|
||||
- metadata: metadata_set_required
|
||||
- size: size
|
||||
- snapshotId: snapshot_id
|
||||
- status: volume_status
|
||||
- volumeType: volume_type
|
||||
|
||||
|
|
||||
|
||||
**Example List Volumes With Details**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-detail-resp.json
|
||||
:language: javascript
|
||||
@ -99,24 +160,44 @@ Show Volume Details
|
||||
|
||||
.. rest_method:: GET /os-volumes/{volume_id}
|
||||
|
||||
Shows details for a volume.
|
||||
Shows details for a given volume.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401),
|
||||
forbidden(403), itemNotFound(404)
|
||||
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- volume_id: volume_id
|
||||
- volume_id: volume_id_path
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
**Example Show Volume Details: JSON response**
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- volume: volume
|
||||
- attachments: volumeAttachments
|
||||
- attachment.device: attachment_device_resp
|
||||
- attachments.id: attachment_id_resp
|
||||
- attachments.serverId: attachment_server_id_resp
|
||||
- attachments.volumeId: attachment_volumeId_resp
|
||||
- availabilityZone: OS-EXT-AZ:availability_zone
|
||||
- createdAt: created
|
||||
- displayName: display_name
|
||||
- displayDescription: display_description
|
||||
- id: volume_id_resp
|
||||
- metadata: metadata_set_required
|
||||
- size: size
|
||||
- snapshotId: snapshot_id
|
||||
- status: volume_status
|
||||
- volumeType: volume_type
|
||||
|
||||
|
|
||||
|
||||
**Example Show Volume Details**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/os-volumes-get-resp.json
|
||||
:language: javascript
|
||||
@ -130,19 +211,21 @@ Deletes a volume.
|
||||
|
||||
Normal response codes: 202
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401),
|
||||
forbidden(403), itemNotFound(404)
|
||||
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- volume_id: volume_id
|
||||
- volume_id: volume_id_path
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
No response body is returned on successful DELETE.
|
||||
|
||||
|
||||
List Snapshots
|
||||
==============
|
||||
|
||||
@ -152,12 +235,25 @@ Lists snapshots.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
||||
Error response codes: unauthorized(401), forbidden(403)
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
**Example List Snapshots: JSON response**
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- snapshots: snapshots
|
||||
- id: snapshot_id
|
||||
- createdAt: created
|
||||
- displayName: display_name
|
||||
- displayDescription: display_description
|
||||
- size: size
|
||||
- status: snapshot_status
|
||||
- volumeId: volume_id
|
||||
|
||||
|
|
||||
|
||||
**Example List Snapshots**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshots-list-resp.json
|
||||
:language: javascript
|
||||
@ -167,7 +263,7 @@ Create Snapshot
|
||||
|
||||
.. rest_method:: POST /os-snapshots
|
||||
|
||||
Creates a snapshot.
|
||||
Creates a new snapshot.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
@ -179,8 +275,12 @@ Request
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- snapshot: snapshot
|
||||
- volume_id: volume_id
|
||||
- display_description: display_description_optional
|
||||
- display_name: display_name_optional
|
||||
- force: force_snapshot
|
||||
|
||||
**Example Create Snapshot: JSON request**
|
||||
**Example Create Snapshot**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshot-create-req.json
|
||||
:language: javascript
|
||||
@ -188,7 +288,18 @@ Request
|
||||
Response
|
||||
--------
|
||||
|
||||
**Example Create Snapshot: JSON response**
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- snapshot: snapshot
|
||||
- id: snapshot_id
|
||||
- createdAt: created
|
||||
- displayName: display_name
|
||||
- displayDescription: display_description
|
||||
- volumeId: volume_id
|
||||
- size: size
|
||||
- status: snapshot_status
|
||||
|
||||
**Example Create Snapshot**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshot-create-resp.json
|
||||
:language: javascript
|
||||
@ -202,12 +313,25 @@ Lists all snapshots with details.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
|
||||
Error response codes: unauthorized(401), forbidden(403)
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
**Example List Snapshots With Details: JSON response**
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- snapshots: snapshots
|
||||
- id: snapshot_id
|
||||
- createdAt: created
|
||||
- displayName: display_name
|
||||
- displayDescription: display_description
|
||||
- volumeId: volume_id
|
||||
- size: size
|
||||
- status: snapshot_status
|
||||
|
||||
|
|
||||
|
||||
**Example List Snapshots With Details**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshots-detail-resp.json
|
||||
:language: javascript
|
||||
@ -217,24 +341,36 @@ Show Snapshot Details
|
||||
|
||||
.. rest_method:: GET /os-snapshots/{snapshot_id}
|
||||
|
||||
Shows details for a snapshot.
|
||||
Shows details for a given snapshot.
|
||||
|
||||
Normal response codes: 200
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401),
|
||||
forbidden(403), itemNotFound(404)
|
||||
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- snapshot_id: snapshot_id
|
||||
- snapshot_id: snapshot_id_path
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
**Example Show Snapshot Details: JSON response**
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- snapshot: snapshot
|
||||
- id: snapshot_id
|
||||
- createdAt: created
|
||||
- displayName: display_name
|
||||
- displayDescription: display_description
|
||||
- volumeId: volume_id
|
||||
- size: size
|
||||
- status: snapshot_status
|
||||
|
||||
|
|
||||
|
||||
**Example Show Snapshot Details**
|
||||
|
||||
.. literalinclude:: ../../doc/api_samples/os-volumes/snapshots-show-resp.json
|
||||
:language: javascript
|
||||
@ -250,15 +386,17 @@ This operation is asynchronous. You must list snapshots repeatedly to determine
|
||||
|
||||
Normal response codes: 202
|
||||
|
||||
Error response codes: badRequest(400), unauthorized(401),
|
||||
forbidden(403), itemNotFound(404)
|
||||
Error response codes: unauthorized(401), forbidden(403), itemNotFound(404)
|
||||
|
||||
Request
|
||||
-------
|
||||
|
||||
.. rest_parameters:: parameters.yaml
|
||||
|
||||
- snapshot_id: snapshot_id
|
||||
- snapshot_id: snapshot_id_path
|
||||
|
||||
|
||||
Response
|
||||
--------
|
||||
|
||||
No response body is returned on successful DELETE.
|
||||
|
||||
@ -273,7 +273,7 @@ tenant_id:
|
||||
in: path
|
||||
required: true
|
||||
type: string
|
||||
volume_id_1:
|
||||
volume_id_path:
|
||||
description: |
|
||||
The unique ID for a volume.
|
||||
in: path
|
||||
@ -888,11 +888,29 @@ associate_host:
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
attachment_device_resp:
|
||||
description: |
|
||||
Name of the device in the attachment object, such as, ``/dev/vdb``.
|
||||
in: body
|
||||
required: false
|
||||
type: string
|
||||
attachment_id_resp:
|
||||
description: |
|
||||
The UUID of the attachment.
|
||||
in: body
|
||||
required: true
|
||||
required: false
|
||||
type: string
|
||||
attachment_server_id_resp:
|
||||
description: |
|
||||
The UUID of the server.
|
||||
in: body
|
||||
required: false
|
||||
type: string
|
||||
attachment_volumeId_resp:
|
||||
description: |
|
||||
The UUID of the attached volume.
|
||||
in: body
|
||||
required: false
|
||||
type: string
|
||||
availability_zone:
|
||||
description: |
|
||||
@ -1363,12 +1381,24 @@ disk_over_commit:
|
||||
required: true
|
||||
type: boolean
|
||||
display_description:
|
||||
description: |
|
||||
The volume description.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
display_description_optional:
|
||||
description: |
|
||||
The volume description.
|
||||
in: body
|
||||
required: false
|
||||
type: string
|
||||
display_name:
|
||||
description: |
|
||||
The volume name.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
display_name_optional:
|
||||
description: |
|
||||
The volume name.
|
||||
in: body
|
||||
@ -1535,7 +1565,7 @@ flavor_access:
|
||||
flavor_cpus:
|
||||
in: body
|
||||
required: true
|
||||
type: int
|
||||
type: integer
|
||||
description: |
|
||||
The number of virtual CPUs that will be allocated to the server.
|
||||
flavor_disabled:
|
||||
@ -1548,7 +1578,7 @@ flavor_disabled:
|
||||
flavor_disk:
|
||||
in: body
|
||||
required: true
|
||||
type: int
|
||||
type: integer
|
||||
description: |
|
||||
The size of the root disk that will be created in GiB. If 0 the
|
||||
root disk will be set to exactly the size of the image used to
|
||||
@ -1556,7 +1586,7 @@ flavor_disk:
|
||||
flavor_ephem_disk:
|
||||
in: body
|
||||
required: true
|
||||
type: int
|
||||
type: integer
|
||||
description: |
|
||||
The size of the ephemeral disk that will be created, in
|
||||
GiB. Ephemeral disks may be written over on server state
|
||||
@ -1565,7 +1595,7 @@ flavor_ephem_disk:
|
||||
flavor_ephem_disk_in:
|
||||
in: body
|
||||
required: false
|
||||
type: int
|
||||
type: integer
|
||||
description: |
|
||||
The size of the ephemeral disk that will be created, in
|
||||
GiB. Ephemeral disks may be written over on server state
|
||||
@ -1603,7 +1633,7 @@ flavor_ram:
|
||||
The amount of RAM a flavor has, in MiB.
|
||||
in: body
|
||||
required: true
|
||||
type: int
|
||||
type: integer
|
||||
flavor_rxtx_factor:
|
||||
description: |
|
||||
The receive / transimit factor (as a float) that will be set on
|
||||
@ -1626,14 +1656,14 @@ flavor_swap:
|
||||
GiB. If 0 (the default), no dedicated swap disk will be created.
|
||||
in: body
|
||||
required: true
|
||||
type: int
|
||||
type: integer
|
||||
flavor_swap_in:
|
||||
description: |
|
||||
The size of a dedicated swap disk that will be allocated, in
|
||||
GiB. If 0 (the default), no dedicated swap disk will be created.
|
||||
in: body
|
||||
required: false
|
||||
type: int
|
||||
type: integer
|
||||
flavorRef:
|
||||
description: |
|
||||
The flavor reference, as a UUID or full URL, for the flavor for your server instance.
|
||||
@ -1701,6 +1731,12 @@ force_live_migrate:
|
||||
required: false
|
||||
type: boolean
|
||||
min_version: 2.30
|
||||
force_snapshot:
|
||||
description: |
|
||||
Indicates whether to create a snapshot, even if the volume is attached.
|
||||
in: body
|
||||
required: false
|
||||
type: boolean
|
||||
forced_down:
|
||||
description: |
|
||||
Whether or not this service was forced down manually by an
|
||||
@ -2508,6 +2544,8 @@ meta:
|
||||
in: body
|
||||
required: true
|
||||
type: object
|
||||
# TODO(karenb): Clean-up the various metadata object params.
|
||||
# See metadata, metadata_required, metadata_object, metadata_set_required ...
|
||||
metadata:
|
||||
description: |
|
||||
Metadata key and value pairs. The maximum size of the metadata key and value is
|
||||
@ -2564,8 +2602,7 @@ metadata_object:
|
||||
metadata_required:
|
||||
description: |
|
||||
Metadata key and value pairs. The maximum size of the metadata key and value is
|
||||
255 bytes each. This field is never used, always kept empty.
|
||||
The associated metadata key and value pairs.
|
||||
255 bytes each. The associated metadata key and value pairs.
|
||||
in: body
|
||||
required: true
|
||||
type: object
|
||||
@ -2754,6 +2791,12 @@ OS-EXT-AZ:availability_zone:
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
OS-EXT-AZ:availability_zone_optional:
|
||||
description: |
|
||||
The availability zone name.
|
||||
in: body
|
||||
required: false
|
||||
type: string
|
||||
OS-EXT-SRV-ATTR:host:
|
||||
description: |
|
||||
The host name. Appears in the response for administrative users only.
|
||||
@ -3570,10 +3613,34 @@ snapshot:
|
||||
type: object
|
||||
snapshot_id:
|
||||
description: |
|
||||
The snapshot ID.
|
||||
The UUID for a snapshot.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
snapshot_id_optional:
|
||||
description: |
|
||||
The UUID for a snapshot.
|
||||
in: body
|
||||
required: false
|
||||
type: string
|
||||
snapshot_status:
|
||||
description: |
|
||||
The status of the snapshot. Valid status values are:
|
||||
|
||||
- ``available``
|
||||
- ``creating``
|
||||
- ``deleting``
|
||||
- ``error``
|
||||
- ``error_deleting``
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
snapshots:
|
||||
description: |
|
||||
A list of snapshot objects.
|
||||
in: body
|
||||
required: true
|
||||
type: array
|
||||
source_type:
|
||||
description: |
|
||||
The source type of the volume. A valid value is ``blank``, ``snapshot``, ``volume``,
|
||||
@ -3780,7 +3847,7 @@ volume:
|
||||
description: |
|
||||
The ``volume`` object.
|
||||
in: body
|
||||
required: false
|
||||
required: true
|
||||
type: object
|
||||
volume_id:
|
||||
description: |
|
||||
@ -3788,7 +3855,25 @@ volume_id:
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
volume_id_resp:
|
||||
description: |
|
||||
The UUID of the volume.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
volume_status:
|
||||
description: |
|
||||
The status of the volume.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
volume_type:
|
||||
description: |
|
||||
The name or unique identifier for a volume type.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
volume_type_optional:
|
||||
description: |
|
||||
The unique identifier for a volume type.
|
||||
in: body
|
||||
@ -3796,13 +3881,14 @@ volume_type:
|
||||
type: string
|
||||
volumeAttachment:
|
||||
description: |
|
||||
A dictionary representation of a volume attachment.
|
||||
A dictionary representation of a volume attachment containing the fields,
|
||||
``device``, ``id``, ``serverId``, ``volumeId``.
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
type: object
|
||||
volumeAttachments:
|
||||
description: |
|
||||
List of the volume attachments.
|
||||
The list of volume attachments.
|
||||
in: body
|
||||
required: true
|
||||
type: array
|
||||
@ -3824,6 +3910,12 @@ volumeId_swap:
|
||||
in: body
|
||||
required: true
|
||||
type: string
|
||||
volumes:
|
||||
description: |
|
||||
The list of ``volume`` objects.
|
||||
in: body
|
||||
required: true
|
||||
type: array
|
||||
vpn_ip:
|
||||
description: |
|
||||
The VPN IP address.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user