Enable cold migration with target host

The target host can be specified when cold migrating a server.
The spec is changed from the approved spec in terms of
the following items.

* The 'host' parameter in API is optional.
  (Based on a comment in Iee356c4dd097c846b6ca8617ead6a061300c83f8)
* The 'force' parameter is removed.

Previously-approved: ocata, pike
APIImpact
Change-Id: I0fac0761aca74bcd02b20456ac6eff881dd63bcf
blueprint cold-migration-with-target-queens

specs/queens/approved/cold-migration-with-target-queens.rst

@@ -0,0 +1,172 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+===============================================
+Enable cold migration with target host - Queens
+===============================================
+
+https://blueprints.launchpad.net/nova/+spec/cold-migration-with-target-queens
+
+The aim of this feature is to let operators cold migrate instances with
+target host manually.
+
+Problem description
+===================
+
+A target host can be specified on the live migration operation.
+But a target host cannot be specified on the cold migration operation.
+It is inconsistent with the live migration operation,
+and both of these operations have similar circumstances
+when the host needs to be specified.
+
+Use Cases
+---------
+
+It is same as the live migration use case.
+Sometimes an operator or a script decides which host is the best
+suited to accept a cold migration and then wants to perform it.
+Consistency with a live migration case should be ensured.
+
+Proposed change
+===============
+
+Modify the API and the current resize_instance flow to be able to
+specify the target host for cold migration.
+
+Add the function to check whether a destination host is
+in accordance with scheduler rules or not in cold migration
+as a default behaviour.
+Specifically to say, add setting 'requested_destination' of the RequestSpec
+object in nova/compute/api.py. The field has already been supported
+in the scheduler, so it just needs to be filled in.
+
+Alternatives
+------------
+
+None
+
+Data model impact
+-----------------
+
+None
+
+REST API impact
+---------------
+
+* URL: POST /v2.1/servers/{server_id}/action
+
+  JSON request body::
+
+    {
+        "migrate": {
+            "host": "target-host"
+        }
+    }
+
+The 'host' parameter to specify a target host is optional.
+Microversion is bumped up.
+
+Security impact
+---------------
+
+None
+
+Notifications impact
+--------------------
+
+None
+
+Other end user impact
+---------------------
+
+python-novaclient will be modified to have a target host argument as
+optional.
+
+nova migrate <server> [<host>]
+
+Performance Impact
+------------------
+
+None
+
+Other deployer impact
+---------------------
+
+None
+
+Developer impact
+----------------
+
+None
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  natsume-takashi
+
+Work Items
+----------
+
+* Add logic to specify target host for cold migration
+* Add processing checking destination host in the cold migration
+* Disable retries of the scheduling when the target host is specified
+* Add API with bumping a new microversion
+* Add nova functional tests
+* Add tempest tests
+
+Dependencies
+============
+
+None
+
+Testing
+=======
+
+Add the following tests.
+
+* Unit tests
+* Functional tests
+* Tempest tests
+
+
+Documentation Impact
+====================
+
+* API Reference
+* CLI Reference
+* Admin User Guide on cold migration topic.
+
+References
+==========
+
+Mailing list discussion about why ``force`` flag is not added as part of this
+proposal: http://lists.openstack.org/pipermail/openstack-dev/2017-August/121654.html
+
+History
+=======
+
+The blueprint has been approved for Ocata as
+'cold-migration-with-target-ocata' and for Pike as
+'cold-migration-with-target-pike'.
+It is renamed to 'cold-migration-with-target-queens' now.
+But the 'force' parameter to bypass the scheduler check is removed in the spec.
+
+.. list-table:: Revisions
+   :header-rows: 1
+
+   * - Release Name
+     - Description
+   * - Ocata
+     - Approved
+   * - Pike
+     - Reapproved
+   * - Queens
+     - Reproposed