From 3fe22863dba723ee189520c248a36587371b0275 Mon Sep 17 00:00:00 2001 From: silvacarloss Date: Tue, 19 Feb 2019 09:38:52 -0300 Subject: [PATCH] Add api-ref for manage/unmanage with DHSS=True This patch updates the manila api-ref adding content to the manage/unmanage of share servers with DHSS=True feature. Partial-Bug: #1818758 Change-Id: Ia63762df5cfb2c4b47cf59186ceb571b4c79c31b --- api-ref/source/parameters.yaml | 108 +++++++++-- .../source/samples/share-manage-request.json | 3 +- .../source/samples/share-manage-response.json | 4 +- .../samples/share-server-manage-request.json | 10 ++ .../samples/share-server-manage-response.json | 15 ++ .../share-server-reset-state-request.json | 5 + .../share-server-unmanage-request.json | 5 + api-ref/source/share-servers.inc | 167 ++++++++++++++++++ api-ref/source/shares.inc | 7 + 9 files changed, 307 insertions(+), 17 deletions(-) create mode 100644 api-ref/source/samples/share-server-manage-request.json create mode 100644 api-ref/source/samples/share-server-manage-response.json create mode 100644 api-ref/source/samples/share-server-reset-state-request.json create mode 100644 api-ref/source/samples/share-server-unmanage-request.json diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 65a23d72eb..fc23ecc1ce 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -46,6 +46,12 @@ metadata_key_path: in: path required: false type: string +project_id_path: + description: | + The ID of the project what owns the resource. + in: path + required: true + type: string quota_class_name: description: The name of the quota class for which to set quotas. @@ -383,12 +389,6 @@ share_group_type_id_query: in: query required: false type: string -share_network_id_5: - description: | - The UUID of the share network. - in: query - required: false - type: string share_network_id_query: description: | The UUID of the share network. @@ -986,13 +986,6 @@ created_at_5: in: body required: true type: string -created_at_8: - description: | - The date and time stamp when the member was - created. - in: body - required: true - type: string created_at_9: description: | The date and time stamp when the share instance was created. @@ -1013,7 +1006,7 @@ created_at_9: type: string created_at_share_server_body: description: | - The date and time stamp when the share server was created. + The date and time stamp when the share server was created or managed. The date and time stamp format is `ISO 8601 `_: @@ -1621,6 +1614,12 @@ id_8: in: body required: true type: string +identifier: + description: | + The identifier of the share server in the back-end storage system. + in: body + required: true + type: string ip_version: description: | The IP version of the network. A valid value is @@ -1645,6 +1644,15 @@ is_admin_only: in: body required: true type: boolean +is_auto_deletable: + description: | + Defines if a share server can be deleted automatically by the service. + Share server deletion can be automated with configuration. However, Share + servers that have ever had a share removed from service management cannot + be automatically deleted by the service. + in: body + required: true + type: boolean is_default_type: description: | Defines the share type created is default or not. If the returning @@ -1696,6 +1704,21 @@ links_2: in: body required: true type: array +manage_host: + description: | + The host of the destination back end, in this format: ``host@backend``. + - ``host``. The host name for the destination back end. + - ``backend``. The name of the destination back end. + in: body + required: true + type: string +manage_share_server_id: + description: | + The UUID of the share server. + in: body + required: true + type: string + min_version: 2.49 maxTotalShareGigabytes: description: | The total maximum number of share gigabytes that @@ -2101,6 +2124,12 @@ project_id_share_server_body: in: body required: true type: string +project_id_share_server_manage: + description: | + The ID of the project that owns the share server. + in: body + required: true + type: string protocol: description: | The Shared File Systems protocol of the share to @@ -3092,6 +3121,57 @@ share_server_id: in: body required: true type: string +share_server_show_identifier: + description: | + The identifier of the share server in the back-end storage system. + in: body + required: true + type: string + min_version: 2.49 +share_server_show_is_auto_deletable: + description: | + Defines if a share server can be deleted automatically by the service. + Share server deletion can be automated with configuration. However, Share + servers that have ever had a share removed from service management cannot + be automatically deleted by the service. + in: body + required: true + type: boolean + min_version: 2.49 +share_server_status: + description: | + The share server status, which can be ``active``, + ``error``, ``creating``, ``deleting``, ``manage_starting``, + ``manage_error``, ``unmanage_starting``, ``unmanage_error`` or + ``error_deleting``. + in: body + required: true + type: string +share_server_unmanage: + description: | + To unmanage a share server, either set this value to ``null`` or {}. + Optionally, the ``force`` attribute can be included in this object. + in: body + required: true + type: object +share_server_updated_at: + description: | + The date and time stamp when the share server was updated. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + The ``±hh:mm`` value, if included, returns the time zone as an + offset from UTC. + + For example, ``2015-08-27T09:49:58-05:00``. + in: body + required: true + type: string share_size_1: description: | The size of a source share, in GBs. diff --git a/api-ref/source/samples/share-manage-request.json b/api-ref/source/samples/share-manage-request.json index 291c34469e..a8220bc187 100644 --- a/api-ref/source/samples/share-manage-request.json +++ b/api-ref/source/samples/share-manage-request.json @@ -10,6 +10,7 @@ "export_path": "192.162.10.6:/shares/share-accounting_p8787", "service_host": "manila2@openstackstor01#accountingpool", "is_public": true, - "description": "Common storage for spreadsheets and presentations. Please contact John Accessman to be added to the users of this drive." + "description": "Common storage for spreadsheets and presentations. Please contact John Accessman to be added to the users of this drive.", + "share_server_id": "00137b40-ca06-4ae8-83a3-2c5989eebcce" } } diff --git a/api-ref/source/samples/share-manage-response.json b/api-ref/source/samples/share-manage-response.json index a3fbbdb850..4e65a7f7ef 100644 --- a/api-ref/source/samples/share-manage-response.json +++ b/api-ref/source/samples/share-manage-response.json @@ -13,7 +13,7 @@ "availability_zone": null, "share_network_id": null, "export_locations": [], - "share_server_id": null, + "share_server_id": "00137b40-ca06-4ae8-83a3-2c5989eebcce", "share_group_id": null, "snapshot_id": null, "id": "00137b40-ca06-4ae8-83a3-2c5989eebcce", @@ -32,7 +32,7 @@ "is_public": false, "snapshot_support": true, "name": "share_texas1", - "created_at": "2015-09-17T16:21:12.000000", + "created_at": "2019-03-05T10:00:00.000000", "share_proto": "NFS", "volume_type": "d", } diff --git a/api-ref/source/samples/share-server-manage-request.json b/api-ref/source/samples/share-server-manage-request.json new file mode 100644 index 0000000000..8b33332532 --- /dev/null +++ b/api-ref/source/samples/share-server-manage-request.json @@ -0,0 +1,10 @@ +{ + "share_server": { + "host": "myhost@mybackend", + "share_network_id": "78cef6eb-648a-4bbd-9ae1-d2eaaf594cc0", + "identifier": "4ef3507e-0513-4140-beda-f619ab30d424", + "driver_options": { + "opt1": "opt1_value" + } + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-server-manage-response.json b/api-ref/source/samples/share-server-manage-response.json new file mode 100644 index 0000000000..12ae3d068e --- /dev/null +++ b/api-ref/source/samples/share-server-manage-response.json @@ -0,0 +1,15 @@ +{ + "share_server": { + "id": "dd218d97-6b16-45b7-9b23-19681ccdec3a", + "project_id": "5b23075b4b504261a5987b18588f86cf", + "updated_at": null, + "status": "manage_starting", + "host": "myhost@mybackend", + "share_network_name": "share-net-name", + "share_network_id": "78cef6eb-648a-4bbd-9ae1-d2eaaf594cc0", + "created_at": "2019-03-06T11:59:41.000000", + "backend_details": {}, + "is_auto_deletable": false, + "identifier": "4ef3507e-0513-4140-beda-f619ab30d424" + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-server-reset-state-request.json b/api-ref/source/samples/share-server-reset-state-request.json new file mode 100644 index 0000000000..b364293db6 --- /dev/null +++ b/api-ref/source/samples/share-server-reset-state-request.json @@ -0,0 +1,5 @@ +{ + "reset_status": { + "status": "active" + } +} \ No newline at end of file diff --git a/api-ref/source/samples/share-server-unmanage-request.json b/api-ref/source/samples/share-server-unmanage-request.json new file mode 100644 index 0000000000..2dc4331530 --- /dev/null +++ b/api-ref/source/samples/share-server-unmanage-request.json @@ -0,0 +1,5 @@ +{ + "unmanage": { + "force": "false" + } +} \ No newline at end of file diff --git a/api-ref/source/share-servers.inc b/api-ref/source/share-servers.inc index f3d3e99a5a..aba78f2788 100644 --- a/api-ref/source/share-servers.inc +++ b/api-ref/source/share-servers.inc @@ -130,6 +130,8 @@ Response parameters - host: host_share_server_body - created_at: created_at_share_server_body - updated_at: updated_at_share_server_body + - identifier: share_server_show_identifier + - is_auto_deletable: share_server_show_is_auto_deletable Response example ---------------- @@ -213,3 +215,168 @@ Request - tenant_id: tenant_id_path - share_server_id: share_server_id + + +Manage share server (since API v2.49) +===================================== + +.. rest_method:: POST /v2/{project_id}/share-servers/manage + +.. versionadded:: 2.49 + +Manages a share server + +An administrator can bring a pre-existing share server if the back end driver +is operating in ``driver_handles_share_servers=True`` mode. + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 403 + - 422 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - project_id: project_id_path + - host: manage_host + - identifier: identifier + - share_network: share_network_id + - driver_options: driver_options + +Request example +--------------- + +.. literalinclude:: samples/share-server-manage-request.json + :language: javascript + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: share_server_id + - project_id: project_id_share_server_manage + - updated_at: share_server_updated_at + - status: share_server_status + - host: manage_host + - share_network_name: share_network_name + - share_network_id: share_network_id + - created_at: created_at_share_server_body + - backend_details: backend_details + - is_auto_deletable: is_auto_deletable + - identifier: identifier + +Response examples +----------------- + +.. literalinclude:: samples/share-server-manage-response.json + :language: javascript + + +Unmanage share server (since API v2.49) +======================================= + +.. rest_method:: POST /v2/{project_id}/share-servers/{share_server_id}/action + +.. versionadded:: 2.49 + +Unmanages a share server + +An administrator can remove a share server from the Shared File System +service's management if there are no associated shares that the service is +aware of. The share server will not be torn down in the back end. + +Preconditions + +- Share server status must be either ``error``, ``manage_error``, ``active`` or + ``unmanage_error``. + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 404 + +Request parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - project_id: project_id + - share_server_id: share_server_id + - force: force + - unmanage: share_server_unmanage + +Request example +--------------- + +.. literalinclude:: samples/share-server-unmanage-request.json + :language: javascript + +Response parameters +------------------- + +There is no body content for the response. + + +Reset status (since API v2.49) +============================== + +.. rest_method:: POST /v2/{project_id}/share-servers/{share_server_id}/action + +.. versionadded:: 2.49 + +Resets a share server status + +Administrator only. Explicitly updates the state of a share server. + +Use the ``policy.json`` file to grant permissions for this action to other +roles. + +Response codes +-------------- + +.. rest_status_code:: success status.yaml + + - 202 + +.. rest_status_code:: error status.yaml + + - 400 + - 404 + +Request parameters +------------------ + +.. rest_parameters:: parameters.yaml + + - share_server_id: share_server_id + - project_id: project_id_path + - status: share_server_status + +Request example +--------------- + +.. literalinclude:: samples/share-server-reset-state-request.json + :language: javascript + +Response parameters +------------------- + +There is no body content for the response. diff --git a/api-ref/source/shares.inc b/api-ref/source/shares.inc index fc98fcfcde..28e27aa579 100644 --- a/api-ref/source/shares.inc +++ b/api-ref/source/shares.inc @@ -409,6 +409,11 @@ Manage share Configures Shared File Systems to manage a share. This API is available for API versions later than or equal to 2.7 +.. note:: + + Managing shares that are created on top of managed share servers (i.e. with + parameter ``share_server_id``) is not supported prior to API version 2.49. + Response codes -------------- @@ -438,6 +443,7 @@ Request - driver_options: driver_options - export_path: export_path - service_host: service_host + - share_server_id: manage_share_server_id - is_public: is_public - description: description_5 @@ -469,6 +475,7 @@ Response parameters - project_id: project_id_4 - metadata: metadata - status: status_8 + - share_server_id: manage_share_server_id - description: description_5 - host: host_9 - is_public: is_public