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

@@ -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
     <https://en.wikipedia.org/wiki/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
+    <https://en.wikipedia.org/wiki/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.

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"
     }
 }

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",
     }

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"
+        }
+    }
+}

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"
+    }
+}

api-ref/source/samples/share-server-reset-state-request.json

@@ -0,0 +1,5 @@
+{
+    "reset_status": {
+        "status": "active"
+    }
+}

api-ref/source/samples/share-server-unmanage-request.json

@@ -0,0 +1,5 @@
+{
+  "unmanage": {
+    "force": "false"
+  }
+}

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.

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