Microversion 2.73: Support adding the reason behind a server lock

This patch adds a new parameter ``locked_reason`` to
``POST /servers/{server_id}/action`` request where the
action is lock. It enables the user to specify a reason when locking
a server.

The locked_reason will be exposed through ``GET servers/{server_id}``,
``GET /servers/detail``, ``POST /servers/{server_id}/action``  where
the action is rebuild and ``PUT servers/{server_id}`` requests' responses.

The InstanceActionNotification will emit the locked_reason
along with the other instance details. This patch hence changes the
payload object to include the "locked_reason" field.

Note that "locked" will be allowed as a valid filtering/sorting parameter
for ``GET /servers/detail`` and ``GET /servers`` from this new microversion.

Implements blueprint add-locked-reason

Change-Id: I46edd595e7417c584106487123774a73c6dbe65e

api-ref/source/servers.inc

@@ -170,6 +170,7 @@ whitelist will be silently ignored.
   - ``tags`` (New in version 2.26)
   - ``tags-any`` (New in version 2.26)
   - ``changes-before`` (New in version 2.66)
+  - ``locked`` (New in version 2.73)
 
 
 - For admin user, whitelist includes all filter keys mentioned in
@@ -240,6 +241,7 @@ Request
   - tags: tags_query
   - tags-any: tags_any_query
   - changes-before: changes_before_server
+  - locked: locked_query_server
 
 Response
 --------
@@ -577,6 +579,7 @@ Request
   - tags: tags_query
   - tags-any: tags_any_query
   - changes-before: changes_before_server
+  - locked: locked_query_server
 
 Response
 --------
@@ -646,10 +649,11 @@ Response
   - description: server_description_resp
   - tags: tags
   - trusted_image_certificates: server_trusted_image_certificates_resp
+  - locked_reason: locked_reason_resp
 
-**Example List Servers Detailed (2.63)**
+**Example List Servers Detailed (2.73)**
 
-.. literalinclude:: /../../doc/api_samples/servers/v2.63/servers-details-resp.json
+.. literalinclude:: /../../doc/api_samples/servers/v2.73/servers-details-resp.json
    :language: javascript
 
 **Example List Servers Detailed (2.69)**
@@ -769,10 +773,11 @@ Response
   - tags: tags
   - trusted_image_certificates: server_trusted_image_certificates_resp
   - server_groups: server_groups_2_71
+  - locked_reason: locked_reason_resp
 
-**Example Show Server Details (2.63)**
+**Example Show Server Details (2.73)**
 
-.. literalinclude:: ../../doc/api_samples/servers/v2.63/server-get-resp.json
+.. literalinclude:: ../../doc/api_samples/servers/v2.73/server-get-resp.json
    :language: javascript
 
 **Example Show Server Details (2.69)**
@@ -861,10 +866,11 @@ Response
   - tags: tags
   - trusted_image_certificates: server_trusted_image_certificates_resp
   - server_groups: server_groups_2_71
+  - locked_reason: locked_reason_resp
 
-**Example Update Server (2.63)**
+**Example Update Server (2.73)**
 
-.. literalinclude:: ../../doc/api_samples/servers/v2.63/server-update-resp.json
+.. literalinclude:: ../../doc/api_samples/servers/v2.73/server-update-resp.json
    :language: javascript
 
 Delete Server