api-ref: add list manageable resource API

This patch did:
1. Add list manageable volumes API doc.
2. Add create and list manageable snapshots API doc.

Change-Id: Iccffb69b0ffb220f43258ee4c47d5d8964ae7836
Closes-bug: #1590977
This commit is contained in:
wangxiyuan 2017-05-18 16:38:51 +08:00
parent 07857fb572
commit 95115ae7ab
9 changed files with 392 additions and 2 deletions

View File

@ -25,6 +25,7 @@ Block Storage API V3 (CURRENT)
.. include:: os-vol-image-meta-v3.inc
.. include:: volume-manage.inc
.. include:: volumes-v3-snapshots.inc
.. include:: snapshot-manage.inc
.. include:: os-vol-transfer-v3.inc
.. Now the other random things in alphabetical order.

View File

@ -85,7 +85,7 @@ hostname:
The name of the host that hosts the storage back
end.
in: path
required: false
required: true
type: string
key_1:
description: |
@ -425,6 +425,12 @@ cgsnapshot_id:
in: body
required: false
type: string
cinder_id:
description: |
The UUID of the snapshot in Cinder.
in: body
required: false
type: string
cipher:
description: |
The encryption algorithm or mode. For example, aes-xts-plain64. The default
@ -696,6 +702,12 @@ event_id:
in: body
required: true
type: string
extra_info:
description: |
More information about the resource.
in: body
required: false
type: string
extra_specs:
description: |
A set of key and value pairs that contains the
@ -1047,6 +1059,18 @@ location:
in: body
required: true
type: string
manageable-snapshots:
description: |
A list of manageable snapshots.
in: body
required: true
type: list
manageable-volumes:
description: |
A list of manageable volumes.
in: body
required: true
type: list
maxTotalBackupGigabytes:
description: |
The maximum total amount of backups, in gibibytes
@ -1537,6 +1561,12 @@ rate:
in: body
required: true
type: array
reason_not_safe:
description: |
The reason why the resource can't be managed.
in: body
required: false
type: string
ref:
description: |
A reference to the existing volume. The internal
@ -1555,6 +1585,12 @@ ref_1:
in: body
required: true
type: object
reference:
description: |
Some information for the resource.
in: body
required: true
type: object
remove_volumes:
description: |
One or more volume UUIDs, separated by commas, to
@ -1632,6 +1668,12 @@ restore:
in: body
required: true
type: object
safe_to_manage:
description: |
If the resource can be managed or not.
in: body
required: true
type: boolean
security_group_rules:
description: |
The number of rules that are allowed for each
@ -1705,6 +1747,12 @@ snapshot_id_3:
in: body
required: true
type: string
source-name:
description: |
The resource's name.
in: body
required: true
type: string
source_cgid:
description: |
The UUID of the source consistency group.
@ -1717,6 +1765,12 @@ source_group_id:
in: body
required: false
type: string
source_reference:
description: |
The snapshot's origin volume information.
in: body
required: true
type: object
source_replica:
description: |
The UUID of the primary volume to clone.

View File

@ -0,0 +1,29 @@
{
"manageable-snapshots": [
{
"cinder_id": null,
"reason_not_safe": null,
"reference": {
"source-name": "lvol0"
},
"source_reference": {
"source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"},
"safe_to_manage": true,
"size": 1,
"extra_info": null
},
{
"cinder_id": "d0c84570-a01f-4579-9789-5e9f266587cd",
"reason_not_safe": "already managed",
"reference": {
"source-name":"_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
},
"source_reference": {
"source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
},
"safe_to_manage": false,
"size": 1,
"extra_info": null
}
]
}

View File

@ -0,0 +1,24 @@
{
"manageable-snapshots": [
{
"source_reference": {
"source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
},
"safe_to_manage": true,
"reference": {
"source-name": "lvol0"
},
"size": 1
},
{
"source_reference": {
"source-name": "volume-7c064b34-1e4b-40bd-93ca-4ac5a973661b"
},
"safe_to_manage": false,
"reference": {
"source-name": "_snapshot-d0c84570-a01f-4579-9789-5e9f266587cd"
},
"size": 1
}
]
}

View File

@ -0,0 +1,11 @@
{
"snapshot": {
"description": null,
"metadata": null,
"ref": {
"source-name": "lvol0"
},
"name": null,
"volume_id": "7c064b34-1e4b-40bd-93ca-4ac5a973661b"
}
}

View File

@ -0,0 +1,24 @@
{
"manageable-volumes": [
{
"cinder_id": "9ba5bb53-4a18-4b38-be06-992999da338d",
"reason_not_safe": "already managed",
"reference": {
"source-name": "volume-9ba5bb53-4a18-4b38-be06-992999da338d"
},
"safe_to_manage": false,
"size": 1,
"extra_info": null
},
{
"cinder_id": null,
"reason_not_safe": null,
"reference": {
"source-name": "lvol0"
},
"safe_to_manage": true,
"size": 1,
"extra_info": null
}
]
}

View File

@ -0,0 +1,18 @@
{
"manageable-volumes": [
{
"safe_to_manage": false,
"reference": {
"source-name": "volume-3a81fdac-e8ae-4e61-b6a2-2e14ff316f19"
},
"size": 1
},
{
"safe_to_manage": true,
"reference": {
"source-name": "lvol0"
},
"size": 1
}
]
}

View File

@ -0,0 +1,139 @@
.. -*- rst -*-
Snapshot manage extension (os-snapshot-manage)
==============================================
Creates or lists snapshots by using existing storage instead of allocating new
storage.
Manage an existing snapshot
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/os-snapshot-manage
Creates a snapshot by using existing storage rather than allocating new storage.
The caller must specify a reference to an existing storage volume
in the ref parameter in the request. Although each storage driver
might interpret this reference differently, the driver should
accept a reference structure that contains either a source-id
or source-name element, if possible.
The API chooses the size of the snapshot by rounding up the size of
the existing snapshot to the next gibibyte (GiB).
Normal response codes: 202
Request
-------
.. rest_parameters:: parameters.yaml
- description: description
- name: name
- ref: ref
- volume_id: volume_id
- metadata: metadata
- project_id: project_id_path
Request Example
---------------
.. literalinclude:: ./samples/snapshot-manage-request.json
:language: javascript
List summary of snapshots available to manage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/os-snapshot-manage
Search a volume backend and list summary of snapshots which are available to
manage.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- sort: sort
- offset: offset
- limit: limit
- marker: marker
- project_id: project_id_path
- host: hostname
Response
--------
.. rest_parameters:: parameters.yaml
- manageable-snapshots: manageable-snapshots
- source_reference: source_reference
- safe_to_manage: safe_to_manage
- reference: reference
- source-name: source-name
- size: size
Response Example
----------------
.. literalinclude:: ./samples/snapshot-manage-list-response.json
:language: javascript
List detail of snapshots available to manage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/os-snapshot-manage/detail
Search a volume backend and list detail of snapshots which are available to
manage.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- sort: sort
- offset: offset
- limit: limit
- marker: marker
- project_id: project_id_path
- host: hostname
Response
--------
.. rest_parameters:: parameters.yaml
- manageable-snapshots: manageable-snapshots
- cinder_id: cinder_id
- source_reference: source_reference
- safe_to_manage: safe_to_manage
- reason_not_safe: reason_not_safe
- reference: reference
- source-name: source-name
- size: size
- extra_info: extra_info
Response Example
----------------
.. literalinclude:: ./samples/snapshot-manage-list-detail-response.json
:language: javascript

View File

@ -3,7 +3,7 @@
Volume manage extension (os-volume-manage)
==========================================
Creates volumes by using existing storage instead of allocating new
Creates or lists volumes by using existing storage instead of allocating new
storage.
@ -55,3 +55,93 @@ Request Example
.. literalinclude:: ./samples/volume-manage-request-cluster.json
:language: javascript
List summary of volumes available to manage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/os-volume-manage
Search a volume backend and list summary of volumes which are available to
manage.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- sort: sort
- offset: offset
- limit: limit
- marker: marker
- project_id: project_id_path
- host: hostname
Response
--------
.. rest_parameters:: parameters.yaml
- manageable-volumes: manageable-volumes
- safe_to_manage: safe_to_manage
- reference: reference
- source-name: source-name
- size: size
Response Example
----------------
.. literalinclude:: ./samples/volume-manage-list-response.json
:language: javascript
List detail of volumes available to manage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/os-volume-manage/detail
Search a volume backend and list detail of volumes which are available to
manage.
Normal response codes: 200
Request
-------
.. rest_parameters:: parameters.yaml
- sort: sort
- offset: offset
- limit: limit
- marker: marker
- project_id: project_id_path
- host: hostname
Response
--------
.. rest_parameters:: parameters.yaml
- manageable-volumes: manageable-volumes
- cinder_id: cinder_id
- safe_to_manage: safe_to_manage
- reason_not_safe: reason_not_safe
- reference: reference
- source-name: source-name
- size: size
- extra_info: extra_info
Response Example
----------------
.. literalinclude:: ./samples/volume-manage-list-detail-response.json
:language: javascript