From 95115ae7ab7903c889749be6f6584c1a78e3d1f0 Mon Sep 17 00:00:00 2001 From: wangxiyuan Date: Thu, 18 May 2017 16:38:51 +0800 Subject: [PATCH] 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 --- api-ref/source/v3/index.rst | 1 + api-ref/source/v3/parameters.yaml | 56 ++++++- .../snapshot-manage-list-detail-response.json | 29 ++++ .../snapshot-manage-list-response.json | 24 +++ .../v3/samples/snapshot-manage-request.json | 11 ++ .../volume-manage-list-detail-response.json | 24 +++ .../samples/volume-manage-list-response.json | 18 +++ api-ref/source/v3/snapshot-manage.inc | 139 ++++++++++++++++++ api-ref/source/v3/volume-manage.inc | 92 +++++++++++- 9 files changed, 392 insertions(+), 2 deletions(-) create mode 100644 api-ref/source/v3/samples/snapshot-manage-list-detail-response.json create mode 100644 api-ref/source/v3/samples/snapshot-manage-list-response.json create mode 100644 api-ref/source/v3/samples/snapshot-manage-request.json create mode 100644 api-ref/source/v3/samples/volume-manage-list-detail-response.json create mode 100644 api-ref/source/v3/samples/volume-manage-list-response.json create mode 100644 api-ref/source/v3/snapshot-manage.inc diff --git a/api-ref/source/v3/index.rst b/api-ref/source/v3/index.rst index ba210fb4c91..37ad9b33810 100644 --- a/api-ref/source/v3/index.rst +++ b/api-ref/source/v3/index.rst @@ -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. diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml index 0c02d1a02cf..aea40597789 100644 --- a/api-ref/source/v3/parameters.yaml +++ b/api-ref/source/v3/parameters.yaml @@ -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. diff --git a/api-ref/source/v3/samples/snapshot-manage-list-detail-response.json b/api-ref/source/v3/samples/snapshot-manage-list-detail-response.json new file mode 100644 index 00000000000..256e840c86e --- /dev/null +++ b/api-ref/source/v3/samples/snapshot-manage-list-detail-response.json @@ -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 + } + ] +} \ No newline at end of file diff --git a/api-ref/source/v3/samples/snapshot-manage-list-response.json b/api-ref/source/v3/samples/snapshot-manage-list-response.json new file mode 100644 index 00000000000..efc293977e0 --- /dev/null +++ b/api-ref/source/v3/samples/snapshot-manage-list-response.json @@ -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 + } + ] +} \ No newline at end of file diff --git a/api-ref/source/v3/samples/snapshot-manage-request.json b/api-ref/source/v3/samples/snapshot-manage-request.json new file mode 100644 index 00000000000..d341a1b3786 --- /dev/null +++ b/api-ref/source/v3/samples/snapshot-manage-request.json @@ -0,0 +1,11 @@ +{ + "snapshot": { + "description": null, + "metadata": null, + "ref": { + "source-name": "lvol0" + }, + "name": null, + "volume_id": "7c064b34-1e4b-40bd-93ca-4ac5a973661b" + } +} \ No newline at end of file diff --git a/api-ref/source/v3/samples/volume-manage-list-detail-response.json b/api-ref/source/v3/samples/volume-manage-list-detail-response.json new file mode 100644 index 00000000000..21c16bafaef --- /dev/null +++ b/api-ref/source/v3/samples/volume-manage-list-detail-response.json @@ -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 + } + ] +} \ No newline at end of file diff --git a/api-ref/source/v3/samples/volume-manage-list-response.json b/api-ref/source/v3/samples/volume-manage-list-response.json new file mode 100644 index 00000000000..5c2abcc9407 --- /dev/null +++ b/api-ref/source/v3/samples/volume-manage-list-response.json @@ -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 + } + ] +} \ No newline at end of file diff --git a/api-ref/source/v3/snapshot-manage.inc b/api-ref/source/v3/snapshot-manage.inc new file mode 100644 index 00000000000..37fb7be8b79 --- /dev/null +++ b/api-ref/source/v3/snapshot-manage.inc @@ -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 diff --git a/api-ref/source/v3/volume-manage.inc b/api-ref/source/v3/volume-manage.inc index 72c769e663f..c7386b719ab 100644 --- a/api-ref/source/v3/volume-manage.inc +++ b/api-ref/source/v3/volume-manage.inc @@ -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