Allow unshelve to a specific host (REST API part)

This adds support to the REST API, in a new microversion, for specifying
a destination host to unshelve server action when the server
is shelved offloaded.
This patch also supports the ability to unpin the availability_zone of an
instance that is bound to it.

Note that the functional test changes are due to those tests using the
"latest" microversion 2.91.

Implements: blueprint unshelve-to-host
Change-Id: I9e95428c208582741e6cd99bd3260d6742fcc6b7

Author: uggla

api-ref/source/parameters.yaml

@@ -1858,8 +1858,11 @@ availability_zone_state:
 availability_zone_unshelve:
   description: |
     The availability zone name. Specifying an availability zone is only
-    allowed when the server status is ``SHELVED_OFFLOADED`` otherwise a
-    409 HTTPConflict response is returned.
+    allowed when the server status is ``SHELVED_OFFLOADED`` otherwise
+    HTTP 409 conflict response is returned.
+
+    Since microversion 2.91 ``"availability_zone":null`` allows unpinning the
+    instance from any availability_zone it is pinned to.
   in: body
   required: false
   type: string
@@ -3690,6 +3693,15 @@ host_status_update_rebuild:
   required: false
   type: string
   min_version: 2.75
+host_unshelve:
+  description: |
+    The destination host name. Specifying a destination host is by default only
+    allowed to project_admin, if it not the case HTTP 403 forbidden response
+    is returned.
+  in: body
+  required: false
+  type: string
+  min_version: 2.91
 host_zone:
   description: |
     The available zone of the host.

api-ref/source/servers-action-shelve.inc

@@ -121,9 +121,65 @@ Policy defaults enable only users with the administrative role or the owner of t
 
 **Preconditions**
 
-The server status must be ``SHELVED`` or ``SHELVED_OFFLOADED``.
+Unshelving a server without parameters requires its status to be ``SHELVED`` or ``SHELVED_OFFLOADED``.
+
+Unshelving a server with availability_zone and/or host parameters requires its status to be only ``SHELVED_OFFLOADED`` otherwise HTTP 409 conflict response is returned.
+
+If a server is locked, you must have administrator privileges to unshelve the server.
+
+As of ``microversion 2.91``, you can unshelve to a specific compute node if you have PROJECT_ADMIN privileges.
+This microversion also gives the ability to pin a server to an availability_zone and to unpin a server
+from any availability_zone.
+
+When a server is pinned to an availability_zone, the server move operations will keep the server in that
+availability_zone. However, when the server is not pinned to any availability_zone, the move operations can
+move the server to nodes in different availability_zones.
+
+The behavior according to unshelve parameters will follow the below table.
+
++----------+---------------------------+----------+--------------------------------+
+| Boot     | AZ (1)                    | Host (1) | Result                         |
++==========+===========================+==========+================================+
+|  No AZ   | No AZ or AZ=null          | No       | Free scheduling (2)            |
++----------+---------------------------+----------+--------------------------------+
+|  No AZ   | No AZ or AZ=null          | Host1    | Schedule to Host1.             |
+|          |                           |          | Server remains unpinned.       |
++----------+---------------------------+----------+--------------------------------+
+|  No AZ   | AZ="AZ1"                  | No       | Schedule to any host in "AZ1". |
+|          |                           |          | Server is pined to "AZ1".      |
++----------+---------------------------+----------+--------------------------------+
+|  No AZ   | AZ="AZ1"                  | Host1    | Verify Host1 is in "AZ1",      |
+|          |                           |          | then schedule to Host1,        |
+|          |                           |          | otherwise reject the request.  |
+|          |                           |          | Server is pined to "AZ1".      |
++----------+---------------------------+----------+--------------------------------+
+|  AZ1     | No AZ                     | No       | Schedule to any host in "AZ1". |
+|          |                           |          | Server remains pined to "AZ1". |
++----------+---------------------------+----------+--------------------------------+
+|  AZ1     | AZ=null                   | No       | Free scheduling (2).           |
+|          |                           |          | Server is unpinned.            |
++----------+---------------------------+----------+--------------------------------+
+|  AZ1     | No AZ                     | Host1    | Verify Host1 is in "AZ1",      |
+|          |                           |          | then schedule to Host1,        |
+|          |                           |          | otherwise reject the request.  |
+|          |                           |          | Server remains pined to "AZ1". |
++----------+---------------------------+----------+--------------------------------+
+|  AZ1     | AZ=null                   | Host1    | Schedule to Host1.             |
+|          |                           |          | Server is unpinned.            |
++----------+---------------------------+----------+--------------------------------+
+|  AZ1     | AZ="AZ2"                  | No       | Schedule to any host in "AZ2". |
+|          |                           |          | Server is pined to "AZ2".      |
++----------+---------------------------+----------+--------------------------------+
+|  AZ1     | AZ="AZ2"                  | Host1    | Verify Host1 is in "AZ2" then  |
+|          |                           |          | schedule to Host1,             |
+|          |                           |          | otherwise reject the request.  |
+|          |                           |          | Server is pined to "AZ2".      |
++----------+---------------------------+----------+--------------------------------+
+
+(1) Unshelve body parameters
+(2) Schedule to any host available.
+
 
-If the server is locked, you must have administrator privileges to unshelve the server.
 
 **Asynchronous Postconditions**
 
@@ -147,11 +203,30 @@ Request
           {"unshelve": null} or {"unshelve": {"availability_zone": <string>}}.
           A request body of {"unshelve": {}} is not allowed.
 
+.. note:: Since microversion 2.91, allowed request body schema are
+
+  - {"unshelve": null}   (Keep compatibility with previous microversions)
+
+  or
+
+  - {"unshelve": {"availability_zone": <string>}} (Unshelve and pin server to availability_zone)
+  - {"unshelve": {"availability_zone": null}}   (Unshelve and unpin server from any availability zone)
+  - {"unshelve": {"host": <fqdn>}}
+  - {"unshelve": {"availability_zone": <string>, "host": <fqdn>}}
+  - {"unshelve": {"availability_zone": null, "host": <fqdn>}}
+
+  Everything else is not allowed, examples:
+
+  - {"unshelve": {}}
+  - {"unshelve": {"host": <fqdn>, "host": <fqdn>}}
+  - {"unshelve": {"foo": <string>}}
+
 .. rest_parameters:: parameters.yaml
 
   - server_id: server_id_path
   - unshelve: unshelve
   - availability_zone: availability_zone_unshelve
+  - host: host_unshelve
 
 |
 
@@ -162,9 +237,22 @@ Request
 
 **Example Unshelve server (unshelve Action) (v2.77)**
 
-.. literalinclude:: ../../doc/api_samples/os-shelve/v2.77/os-unshelve.json
+.. literalinclude:: ../../doc/api_samples/os-shelve/v2.77/os-unshelve-az.json
    :language: javascript
 
+**Examples Unshelve server (unshelve Action) (v2.91)**
+
+.. literalinclude:: ../../doc/api_samples/os-shelve/v2.91/os-unshelve-host.json
+   :language: javascript
+
+.. literalinclude:: ../../doc/api_samples/os-shelve/v2.91/os-unshelve-az-host.json
+   :language: javascript
+
+.. literalinclude:: ../../doc/api_samples/os-shelve/v2.91/os-unshelve-host-and-unpin-az.json
+   :language: javascript
+
+.. literalinclude:: ../../doc/api_samples/os-shelve/v2.91/os-unshelve-unpin-az.json
+   :language: javascript
 
 Response
 --------

doc/api_samples/os-shelve/v2.77/os-unshelve.json renamed to doc/api_samples/os-shelve/v2.77/os-unshelve-az.json

@@ -0,0 +1,6 @@
+{
+    "unshelve": {
+        "availability_zone": "nova",
+        "host": "host01"
+    }
+}

doc/api_samples/os-shelve/v2.91/os-unshelve-az-host.json

@@ -0,0 +1,6 @@
+{
+    "unshelve": {
+        "availability_zone": null,
+        "host": "host01"
+    }
+}

doc/api_samples/os-shelve/v2.91/os-unshelve-host-and-unpin-az.json

@@ -0,0 +1,5 @@
+{
+    "unshelve": {
+        "host": "host01"
+    }
+}

doc/api_samples/os-shelve/v2.91/os-unshelve-host.json

@@ -0,0 +1,5 @@
+{
+    "unshelve": {
+        "availability_zone": null
+    }
+}

doc/api_samples/os-shelve/v2.91/os-unshelve-unpin-az.json

@@ -19,7 +19,7 @@
             }
         ],
         "status": "CURRENT",
-        "version": "2.90",
+        "version": "2.91",
         "min_version": "2.1",
         "updated": "2013-07-23T11:33:21Z"
     }

doc/api_samples/versions/v21-version-get-resp.json

@@ -22,7 +22,7 @@
                 }
             ],
             "status": "CURRENT",
-            "version": "2.90",
+            "version": "2.91",
             "min_version": "2.1",
             "updated": "2013-07-23T11:33:21Z"
         }

doc/api_samples/versions/versions-get-resp.json

@@ -247,6 +247,8 @@
              updating or rebuilding an instance. The
              ``OS-EXT-SRV-ATTR:hostname`` attribute is now returned in various
              server responses regardless of policy configuration.
+    * 2.91 - Add support to unshelve instance to a specific host and
+             to pin/unpin AZ.
 """
 
 # The minimum and maximum versions of the API supported
@@ -255,7 +257,7 @@
 # Note(cyeoh): This only applies for the v2.1 API once microversions
 # support is fully merged. It does not affect the V2 API.
 _MIN_API_VERSION = '2.1'
-_MAX_API_VERSION = '2.90'
+_MAX_API_VERSION = '2.91'
 DEFAULT_API_VERSION = _MIN_API_VERSION
 
 # Almost all proxy APIs which are related to network, images and baremetal