api: Add support for 'hostname' parameter

Add microversion 2.90, which allows allows users to configure the
hostname that will be exposed via the nova metadata service when
creating their instance.

Change-Id: I95047c1689ac14fa73eba48e19dc438988b78aad
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

3 files changed, 66 insertions, 31 deletions

diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml
index 01e663f802..5ea19faab9 100644
--- a/api-ref/source/parameters.yaml
+++ b/api-ref/source/parameters.yaml
@@ -737,8 +737,10 @@ hostname_query_server:
   description: |
     Filter the server list result by the host name of server.
 
-    This parameter is only valid when specified by administrators.
-    If non-admin users specify this parameter, it is ignored.
+    This parameter is only valid when specified by administrators until
+    microversion 2.90, after which it can be specified by all users.
+    If non-admin users specify this parameter before microversion 2.90, it is
+    ignored.
   in: query
   required: false
   type: string
@@ -6330,21 +6332,36 @@ server_host_create:
   required: false
   type: string
   min_version: 2.74
-server_hostname:
+server_hostname: &server_hostname
   in: body
   required: false
   type: string
   description: |
-    The hostname set on the instance when it is booted.
-    By default, it appears in the response for administrative users only.
+    The hostname of the instance reported in the metadata service.
+    This parameter only appears in responses for administrators until
+    microversion 2.90, after which it is shown for all users.
+
+    .. note::
+
+        This information is published via the metadata service and requires
+        application such as ``cloud-init`` to propogate it through to the
+        instance.
   min_version: 2.3
-server_hostname_update_rebuild:
+server_hostname_req:
   in: body
   required: false
   type: string
   description: |
-    The hostname set on the instance when it is booted.
-    By default, it appears in the response for administrative users only.
+    The hostname to configure for the instance in the metadata service.
+
+    .. note::
+
+        This information is published via the metadata service and requires
+        application such as ``cloud-init`` to propogate it through to the
+        instance.
+  min_version: 2.90
+server_hostname_update_rebuild:
+  <<: *server_hostname
   min_version: 2.75
 # This is the hypervisor_hostname in a POST (create instance) request body.
 server_hypervisor_hostname_create:
diff --git a/api-ref/source/servers-actions.inc b/api-ref/source/servers-actions.inc
index 47b12705d6..4be66ebafa 100644
--- a/api-ref/source/servers-actions.inc
+++ b/api-ref/source/servers-actions.inc
@@ -22,6 +22,7 @@ into a server since Mitaka release.
 
 You can get an RDP, serial, SPICE, or VNC console for a server.
 
+
 Add (Associate) Floating Ip (addFloatingIp Action) (DEPRECATED)
 ================================================================
 
@@ -469,6 +470,7 @@ Response
 
 If successful, this method does not return content in the response body.
 
+
 .. _reboot:
 
 Reboot Server (reboot Action)
@@ -582,12 +584,18 @@ Request
   - key_name: key_name_rebuild_req
   - user_data: user_data_rebuild_req
   - trusted_image_certificates: server_trusted_image_certificates_rebuild_req
+  - hostname: server_hostname_req
 
 **Example Rebuild Server (rebuild Action) (v2.63)**
 
 .. literalinclude:: ../../doc/api_samples/servers/v2.63/server-action-rebuild.json
    :language: javascript
 
+**Example Rebuild Server (rebuild Action) (v2.90)**
+
+.. literalinclude:: ../../doc/api_samples/servers/v2.90/server-action-rebuild.json
+   :language: javascript
+
 Response
 --------
 
@@ -662,6 +670,7 @@ Response
 .. literalinclude:: ../../doc/api_samples/servers/v2.75/server-action-rebuild-resp.json
    :language: javascript
 
+
 Remove (Disassociate) Floating Ip (removeFloatingIp Action) (DEPRECATED)
 =========================================================================
 
@@ -791,6 +800,7 @@ Response
 .. literalinclude:: ../../doc/api_samples/os-rescue/server-rescue.json
    :language: javascript
 
+
 Resize Server (resize Action)
 =============================
 
diff --git a/api-ref/source/servers.inc b/api-ref/source/servers.inc
index c6e6560b32..547a71e914 100644
--- a/api-ref/source/servers.inc
+++ b/api-ref/source/servers.inc
@@ -368,7 +368,6 @@ Request
 
 .. rest_parameters:: parameters.yaml
 
-
   - server: server
   - flavorRef: flavorRef
   - name: server_name
@@ -404,6 +403,7 @@ Request
   - security_groups: security_groups
   - user_data: user_data
   - description: server_description
+  - hostname: server_hostname_req
   - tags: server_tags_create
   - trusted_image_certificates: server_trusted_image_certificates_create_req
   - host: server_host_create
@@ -443,6 +443,11 @@ Request
 .. literalinclude:: ../../doc/api_samples/servers/v2.74/server-create-req-with-host-and-node.json
    :language: javascript
 
+**Example Create Server With Hostname (v2.90)**
+
+.. literalinclude:: ../../doc/api_samples/servers/v2.90/server-create-req.json
+   :language: javascript
+
 Response
 --------
 
@@ -633,8 +638,15 @@ Response
   - OS-DCF:diskConfig: disk_config
   - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone
   - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host
+  - OS-EXT-SRV-ATTR:hostname: server_hostname
   - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname
   - OS-EXT-SRV-ATTR:instance_name: OS-EXT-SRV-ATTR:instance_name
+  - OS-EXT-SRV-ATTR:kernel_id: server_kernel_id
+  - OS-EXT-SRV-ATTR:launch_index: server_launch_index
+  - OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id
+  - OS-EXT-SRV-ATTR:reservation_id: server_reservation_id
+  - OS-EXT-SRV-ATTR:root_device_name: server_root_device_name
+  - OS-EXT-SRV-ATTR:user_data: server_user_data
   - OS-EXT-STS:power_state: OS-EXT-STS:power_state
   - OS-EXT-STS:task_state: OS-EXT-STS:task_state
   - OS-EXT-STS:vm_state: OS-EXT-STS:vm_state
@@ -656,13 +668,6 @@ Response
   - security_groups: security_groups_obj_optional
   - security_group.name: name
   - servers_links: servers_links
-  - OS-EXT-SRV-ATTR:hostname: server_hostname
-  - OS-EXT-SRV-ATTR:reservation_id: server_reservation_id
-  - OS-EXT-SRV-ATTR:launch_index: server_launch_index
-  - OS-EXT-SRV-ATTR:kernel_id: server_kernel_id
-  - OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id
-  - OS-EXT-SRV-ATTR:root_device_name: server_root_device_name
-  - OS-EXT-SRV-ATTR:user_data: server_user_data
   - locked: locked
   - host_status: host_status
   - description: server_description_resp
@@ -757,8 +762,15 @@ Response
   - OS-DCF:diskConfig: disk_config
   - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone
   - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host
+  - OS-EXT-SRV-ATTR:hostname: server_hostname
   - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname
   - OS-EXT-SRV-ATTR:instance_name: OS-EXT-SRV-ATTR:instance_name
+  - OS-EXT-SRV-ATTR:kernel_id: server_kernel_id
+  - OS-EXT-SRV-ATTR:launch_index: server_launch_index
+  - OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id
+  - OS-EXT-SRV-ATTR:reservation_id: server_reservation_id
+  - OS-EXT-SRV-ATTR:root_device_name: server_root_device_name
+  - OS-EXT-SRV-ATTR:user_data: server_user_data
   - OS-EXT-STS:power_state: OS-EXT-STS:power_state
   - OS-EXT-STS:task_state: OS-EXT-STS:task_state
   - OS-EXT-STS:vm_state: OS-EXT-STS:vm_state
@@ -779,13 +791,6 @@ Response
   - progress: progress
   - security_groups: security_groups_obj_optional
   - security_group.name: name
-  - OS-EXT-SRV-ATTR:hostname: server_hostname
-  - OS-EXT-SRV-ATTR:reservation_id: server_reservation_id
-  - OS-EXT-SRV-ATTR:launch_index: server_launch_index
-  - OS-EXT-SRV-ATTR:kernel_id: server_kernel_id
-  - OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id
-  - OS-EXT-SRV-ATTR:root_device_name: server_root_device_name
-  - OS-EXT-SRV-ATTR:user_data: server_user_data
   - locked: locked
   - host_status: host_status
   - description: server_description_resp
@@ -830,11 +835,14 @@ Request
   - accessIPv4: accessIPv4_in
   - accessIPv6: accessIPv6_in
   - name: server_name_optional
+  - hostname: server_hostname_req
   - OS-DCF:diskConfig: OS-DCF:diskConfig
   - description: server_description
 
-.. note:: You can specify parameters to update independently.
-  e.g. ``name`` only, ``description`` only, ``name`` and ``description``, etc.
+.. note::
+
+   You can specify parameters to update independently.
+   e.g. ``name`` only, ``description`` only, ``name`` and ``description``, etc.
 
 **Example Update Server (2.63)**
 
@@ -889,18 +897,18 @@ Response
   - config_drive: config_drive_resp_update_rebuild
   - OS-EXT-AZ:availability_zone: OS-EXT-AZ:availability_zone_update_rebuild
   - OS-EXT-SRV-ATTR:host: OS-EXT-SRV-ATTR:host_update_rebuild
+  - OS-EXT-SRV-ATTR:hostname: server_hostname_update_rebuild
   - OS-EXT-SRV-ATTR:hypervisor_hostname: OS-EXT-SRV-ATTR:hypervisor_hostname_update_rebuild
   - OS-EXT-SRV-ATTR:instance_name: OS-EXT-SRV-ATTR:instance_name_update_rebuild
-  - OS-EXT-STS:power_state: OS-EXT-STS:power_state_update_rebuild
-  - OS-EXT-STS:task_state: OS-EXT-STS:task_state_update_rebuild
-  - OS-EXT-STS:vm_state: OS-EXT-STS:vm_state_update_rebuild
-  - OS-EXT-SRV-ATTR:hostname: server_hostname_update_rebuild
-  - OS-EXT-SRV-ATTR:reservation_id: server_reservation_id_update_rebuild
-  - OS-EXT-SRV-ATTR:launch_index: server_launch_index_update_rebuild
   - OS-EXT-SRV-ATTR:kernel_id: server_kernel_id_update_rebuild
+  - OS-EXT-SRV-ATTR:launch_index: server_launch_index_update_rebuild
   - OS-EXT-SRV-ATTR:ramdisk_id: server_ramdisk_id_update_rebuild
+  - OS-EXT-SRV-ATTR:reservation_id: server_reservation_id_update_rebuild
   - OS-EXT-SRV-ATTR:root_device_name: server_root_device_name_update_rebuild
   - OS-EXT-SRV-ATTR:user_data: server_user_data_update
+  - OS-EXT-STS:power_state: OS-EXT-STS:power_state_update_rebuild
+  - OS-EXT-STS:task_state: OS-EXT-STS:task_state_update_rebuild
+  - OS-EXT-STS:vm_state: OS-EXT-STS:vm_state_update_rebuild
   - os-extended-volumes:volumes_attached: os-extended-volumes:volumes_attached_update_rebuild
   - os-extended-volumes:volumes_attached.id: os-extended-volumes:volumes_attached.id_update_rebuild
   - os-extended-volumes:volumes_attached.delete_on_termination: os-extended-volumes:volumes_attached.delete_on_termination_update_rebuild