Merge "Add host and hypervisor_hostname flag to create server"

Author: Zuul

api-ref/source/parameters.yaml

@@ -5955,6 +5955,16 @@ server_groups_quota_optional:
   in: body
   required: false
   type: integer
+# This is the host in a POST (create instance) request body.
+server_host_create:
+  description: |
+    The name of the compute service host on which the server is to be created.
+    The API will return 400 if no compute services are found with the given
+    host name. By default, it can be specified by administrators only.
+  in: body
+  required: false
+  type: string
+  min_version: 2.74
 server_hostname:
   in: body
   required: false
@@ -5963,6 +5973,16 @@ server_hostname:
     The hostname set on the instance when it is booted.
     By default, it appears in the response for administrative users only.
   min_version: 2.3
+# This is the hypervisor_hostname in a POST (create instance) request body.
+server_hypervisor_hostname_create:
+  description: |
+    The hostname of the hypervisor on which the server is to be created.
+    The API will return 400 if no hypervisors are found with the given
+    hostname. By default, it can be specified by administrators only.
+  in: body
+  required: false
+  type: string
+  min_version: 2.74
 server_id:
   description: |
     The UUID of the server.

api-ref/source/servers.inc

@@ -397,6 +397,8 @@ Request
   - description: server_description
   - tags: server_tags_create
   - trusted_image_certificates: server_trusted_image_certificates_create_req
+  - host: server_host_create
+  - hypervisor_hostname: server_hypervisor_hostname_create
   - os:scheduler_hints: os:scheduler_hints
   - os:scheduler_hints.build_near_host_ip: os:scheduler_hints_build_near_host_ip
   - os:scheduler_hints.cidr: os:scheduler_hints_cidr
@@ -427,6 +429,11 @@ Request
 .. literalinclude:: ../../doc/api_samples/servers/v2.63/server-create-req.json
    :language: javascript
 
+**Example Create Server With Host and Hypervisor Hostname (v2.74)**
+
+.. literalinclude:: ../../doc/api_samples/servers/v2.74/server-create-req-with-host-and-node.json
+   :language: javascript
+
 Response
 --------
 

doc/api_samples/servers/v2.74/server-create-req-with-host-and-node.json

@@ -0,0 +1,23 @@
+{
+    "server" : {
+        "adminPass": "MySecretPass",
+        "accessIPv4": "1.2.3.4",
+        "accessIPv6": "80fe::",
+        "name" : "new-server-test",
+        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
+        "flavorRef" : "6",
+        "OS-DCF:diskConfig": "AUTO",
+        "metadata" : {
+            "My Server Name" : "Apache1"
+        },
+        "security_groups": [
+            {
+                "name": "default"
+            }
+        ],
+        "user_data" : "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
+        "networks": "auto",
+        "host": "openstack-node-01",
+        "hypervisor_hostname": "openstack-node-01"
+    }
+}

doc/api_samples/servers/v2.74/server-create-req-with-only-host.json

@@ -0,0 +1,22 @@
+{
+    "server" : {
+        "adminPass": "MySecretPass",
+        "accessIPv4": "1.2.3.4",
+        "accessIPv6": "80fe::",
+        "name" : "new-server-test",
+        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
+        "flavorRef" : "6",
+        "OS-DCF:diskConfig": "AUTO",
+        "metadata" : {
+            "My Server Name" : "Apache1"
+        },
+        "security_groups": [
+            {
+                "name": "default"
+            }
+        ],
+        "user_data" : "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
+        "networks": "auto",
+        "host": "openstack-node-01"
+    }
+}

doc/api_samples/servers/v2.74/server-create-req-with-only-node.json

@@ -0,0 +1,22 @@
+{
+    "server" : {
+        "adminPass": "MySecretPass",
+        "accessIPv4": "1.2.3.4",
+        "accessIPv6": "80fe::",
+        "name" : "new-server-test",
+        "imageRef" : "70a599e0-31e7-49b7-b260-868f441e862b",
+        "flavorRef" : "6",
+        "OS-DCF:diskConfig": "AUTO",
+        "metadata" : {
+            "My Server Name" : "Apache1"
+        },
+        "security_groups": [
+            {
+                "name": "default"
+            }
+        ],
+        "user_data" : "IyEvYmluL2Jhc2gKL2Jpbi9zdQplY2hvICJJIGFtIGluIHlvdSEiCg==",
+        "networks": "auto",
+        "hypervisor_hostname": "openstack-node-01"
+    }
+}

doc/api_samples/servers/v2.74/server-create-resp.json

@@ -0,0 +1,22 @@
+{
+    "server": {
+        "OS-DCF:diskConfig": "AUTO",
+        "adminPass": "DB2bQBhxvq8a",
+        "id": "84e2b49d-39a9-4d32-9100-e62161c236db",
+        "links": [
+            {
+                "href": "http://openstack.example.com/v2.1/6f70656e737461636b20342065766572/servers/84e2b49d-39a9-4d32-9100-e62161c236db",
+                "rel": "self"
+            },
+            {
+                "href": "http://openstack.example.com/6f70656e737461636b20342065766572/servers/84e2b49d-39a9-4d32-9100-e62161c236db",
+                "rel": "bookmark"
+            }
+        ],
+        "security_groups": [
+            {
+                "name": "default"
+            }
+        ]
+    }
+}

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

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

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

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

nova/api/openstack/api_version_request.py

@@ -184,6 +184,10 @@
              ``POST /servers/{server_id}/action`` where the action is rebuild.
              It also supports ``locked`` as a filter/sort parameter for
              ``GET /servers/detail`` and ``GET /servers``.
+    * 2.74 - Add support for specifying ``host`` and/or ``hypervisor_hostname``
+             in request body to ``POST /servers``. Allow users to specify which
+             host/node they want their servers to land on and still be
+             validated by the scheduler.
 """
 
 # The minimum and maximum versions of the API supported
@@ -192,7 +196,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.73"
+_MAX_API_VERSION = "2.74"
 DEFAULT_API_VERSION = _MIN_API_VERSION
 
 # Almost all proxy APIs which are related to network, images and baremetal

nova/api/openstack/compute/rest_api_version_history.rst

@@ -940,3 +940,19 @@ server and exposes this information via ``GET /servers/detail``,
 ``POST /servers/{server_id}/action`` where the action is rebuild. It also
 supports ``locked`` as a filter/sort parameter for ``GET /servers/detail``
 and ``GET /servers``.
+
+2.74
+----
+
+API microversion 2.74 adds support for specifying optional ``host``
+and/or ``hypervisor_hostname`` parameters in the request body of
+``POST /servers``. These request a specific destination host/node
+to boot the requested server. These parameters are mutually exclusive
+with the special ``availability_zone`` format of ``zone:host:node``.
+Unlike ``zone:host:node``, the ``host`` and/or ``hypervisor_hostname``
+parameters still allow scheduler filters to be run. If the requested
+host/node is unavailable or otherwise unsuitable, earlier failure will
+be raised.
+There will be also a new policy named
+``compute:servers:create:requested_destination``. By default,
+it can be specified by administrators only.

nova/api/openstack/compute/schemas/servers.py

@@ -356,6 +356,14 @@
     'properties']['volume_type'] = parameter_types.volume_type
 
 
+# Add host and hypervisor_hostname in server
+base_create_v274 = copy.deepcopy(base_create_v267)
+base_create_v274['properties']['server'][
+    'properties']['host'] = parameter_types.hostname
+base_create_v274['properties']['server'][
+    'properties']['hypervisor_hostname'] = parameter_types.hostname
+
+
 base_update = {
     'type': 'object',
     'properties': {

nova/api/openstack/compute/servers.py

@@ -561,6 +561,35 @@ def _process_networks_for_create(
 
         create_kwargs['requested_networks'] = requested_networks
 
+    @staticmethod
+    def _process_hosts_for_create(
+            context, target, server_dict, create_kwargs, host, node):
+        """Processes hosts request parameter for server create
+
+        :param context: The nova auth request context
+        :param target: The target dict for ``context.can`` policy checks
+        :param server_dict: The POST /servers request body "server" entry
+        :param create_kwargs: dict that gets populated by this method and
+            passed to nova.comptue.api.API.create()
+        :param host: Forced host of availability_zone
+        :param node: Forced node of availability_zone
+        :raise: webob.exc.HTTPBadRequest if the request parameters are invalid
+        :raise: nova.exception.Forbidden if a policy check fails
+        """
+        requested_host = server_dict.get('host')
+        requested_hypervisor_hostname = server_dict.get('hypervisor_hostname')
+        if requested_host or requested_hypervisor_hostname:
+            # If the policy check fails, this will raise Forbidden exception.
+            context.can(server_policies.REQUESTED_DESTINATION, target=target)
+            if host or node:
+                msg = _("One mechanism with host and/or "
+                        "hypervisor_hostname and another mechanism "
+                        "with zone:host:node are mutually exclusive.")
+                raise exc.HTTPBadRequest(explanation=msg)
+        create_kwargs['requested_host'] = requested_host
+        create_kwargs['requested_hypervisor_hostname'] = (
+            requested_hypervisor_hostname)
+
     @wsgi.response(202)
     @wsgi.expected_errors((400, 403, 409))
     @validation.schema(schema_servers.base_create_v20, '2.0', '2.0')
@@ -573,7 +602,8 @@ def _process_networks_for_create(
     @validation.schema(schema_servers.base_create_v252, '2.52', '2.56')
     @validation.schema(schema_servers.base_create_v257, '2.57', '2.62')
     @validation.schema(schema_servers.base_create_v263, '2.63', '2.66')
-    @validation.schema(schema_servers.base_create_v267, '2.67')
+    @validation.schema(schema_servers.base_create_v267, '2.67', '2.73')
+    @validation.schema(schema_servers.base_create_v274, '2.74')
     def create(self, req, body):
         """Creates a new server for a given user."""
         context = req.environ['nova.context']
@@ -653,6 +683,10 @@ def create(self, req, body):
         if host or node:
             context.can(server_policies.SERVERS % 'create:forced_host', {})
 
+        if api_version_request.is_supported(req, min_version='2.74'):
+            self._process_hosts_for_create(context, target, server_dict,
+                                           create_kwargs, host, node)
+
         # NOTE(danms): Don't require an answer from all cells here, as
         # we assume that if a cell isn't reporting we won't schedule into
         # it anyway. A bit of a gamble, but a reasonable one.
@@ -750,7 +784,8 @@ def create(self, req, body):
                 exception.UnableToAutoAllocateNetwork,
                 exception.MultiattachNotSupportedOldMicroversion,
                 exception.CertificateValidationFailed,
-                exception.CreateWithPortResourceRequestOldVersion) as error:
+                exception.CreateWithPortResourceRequestOldVersion,
+                exception.ComputeHostNotFound) as error:
             raise exc.HTTPBadRequest(explanation=error.format_message())
         except INVALID_FLAVOR_IMAGE_EXCEPTIONS as error:
             raise exc.HTTPBadRequest(explanation=error.format_message())

nova/compute/api.py

@@ -999,7 +999,19 @@ def _provision_instances(self, context, instance_type, min_count,
             block_device_mapping, shutdown_terminate,
             instance_group, check_server_group_quota, filter_properties,
             key_pair, tags, trusted_certs, supports_multiattach,
-            network_metadata=None):
+            network_metadata=None, requested_host=None,
+            requested_hypervisor_hostname=None):
+        # NOTE(boxiang): Check whether compute nodes exist by validating
+        # the host and/or the hypervisor_hostname. Pass the destination
+        # to the scheduler with host and/or hypervisor_hostname(node).
+        destination = None
+        if requested_host or requested_hypervisor_hostname:
+            self._validate_host_or_node(context, requested_host,
+                                        requested_hypervisor_hostname)
+            destination = objects.Destination()
+            if requested_host:
+                destination.host = requested_host
+            destination.node = requested_hypervisor_hostname
         # Check quotas
         num_instances = compute_utils.check_num_instances_quota(
                 context, instance_type, min_count, max_count)
@@ -1041,6 +1053,9 @@ def _provision_instances(self, context, instance_type, min_count,
                 if network_metadata:
                     req_spec.network_metadata = network_metadata
 
+                if destination:
+                    req_spec.requested_destination = destination
+
                 # Create an instance object, but do not store in db yet.
                 instance = objects.Instance(context=context)
                 instance.uuid = instance_uuid
@@ -1263,7 +1278,8 @@ def _create_instance(self, context, instance_type,
                reservation_id=None, legacy_bdm=True, shutdown_terminate=False,
                check_server_group_quota=False, tags=None,
                supports_multiattach=False, trusted_certs=None,
-               supports_port_resource_request=False):
+               supports_port_resource_request=False,
+               requested_host=None, requested_hypervisor_hostname=None):
         """Verify all the input parameters regardless of the provisioning
         strategy being performed and schedule the instance(s) for
         creation.
@@ -1339,7 +1355,8 @@ def _create_instance(self, context, instance_type,
             boot_meta, security_groups, block_device_mapping,
             shutdown_terminate, instance_group, check_server_group_quota,
             filter_properties, key_pair, tags, trusted_certs,
-            supports_multiattach, network_metadata)
+            supports_multiattach, network_metadata,
+            requested_host, requested_hypervisor_hostname)
 
         instances = []
         request_specs = []
@@ -1806,7 +1823,8 @@ def create(self, context, instance_type,
                legacy_bdm=True, shutdown_terminate=False,
                check_server_group_quota=False, tags=None,
                supports_multiattach=False, trusted_certs=None,
-               supports_port_resource_request=False):
+               supports_port_resource_request=False,
+               requested_host=None, requested_hypervisor_hostname=None):
         """Provision instances, sending instance information to the
         scheduler.  The scheduler will determine where the instance(s)
         go and will handle creating the DB entries.
@@ -1849,7 +1867,9 @@ def create(self, context, instance_type,
             check_server_group_quota=check_server_group_quota,
             tags=tags, supports_multiattach=supports_multiattach,
             trusted_certs=trusted_certs,
-            supports_port_resource_request=supports_port_resource_request)
+            supports_port_resource_request=supports_port_resource_request,
+            requested_host=requested_host,
+            requested_hypervisor_hostname=requested_hypervisor_hostname)
 
     def _check_auto_disk_config(self, instance=None, image=None,
                                 **extra_instance_updates):