Merge "Deprecate os-hosts API"

11 files changed, 117 insertions, 7 deletions

diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst
index b32f873e62..ffb989956e 100644
--- a/api-ref/source/index.rst
+++ b/api-ref/source/index.rst
@@ -43,7 +43,6 @@ the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
 .. include:: os-availability-zone.inc
 .. include:: os-cells.inc
 .. include:: os-consoles.inc
-.. include:: os-hosts.inc
 .. include:: os-hypervisors.inc
 .. include:: os-instance-usage-audit-log.inc
 .. include:: os-migrations.inc
@@ -71,3 +70,4 @@ the `API guide <http://developer.openstack.org/api-guide/compute/index.html>`_.
 .. include:: os-security-groups.inc
 .. include:: os-security-group-default-rules.inc
 .. include:: os-security-group-rules.inc
+.. include:: os-hosts.inc
diff --git a/api-ref/source/os-hosts.inc b/api-ref/source/os-hosts.inc
index 8356d260bc..89b93db94b 100644
--- a/api-ref/source/os-hosts.inc
+++ b/api-ref/source/os-hosts.inc
@@ -1,8 +1,18 @@
 .. -*- rst -*-
 
-==================
- Hosts (os-hosts)
-==================
+===============================
+ Hosts (os-hosts) (DEPRECATED)
+===============================
+
+.. warning::
+
+    The ``os-hosts`` API is deprecated as of the 2.43 microversion. Requests
+    made with microversion >= 2.43 will result in a 404 error. To list and show
+    host details, use the :ref:`os-hypervisors` API. To enable or disable a
+    service, use the :ref:`os-services` API. There is no replacement for the
+    `shutdown`, `startup`, `reboot`, or `maintenance_mode` actions as those are
+    system-level operations which should be outside of the control of the
+    compute service.
 
 Manages physical hosts. Some virt drivers do not support all host
 functions. For more information, see `nova virt support
@@ -81,6 +91,17 @@ Update Host status
 
 Enables, disables a host or put a host in maintenance or normal mode.
 
+.. warning::
+
+  Putting a host into maintenance mode is only implemented by the XenServer
+  compute driver and it has been reported that it does not actually evacuate
+  all of the guests from the host, it just sets a flag in the Xen management
+  console, and is therefore useless. There are other APIs that allow you to do
+  the same thing which are supported across all compute drivers, which would be
+  disabling a service and then migrating the instances off that host. See the
+  `Operations Guide <https://docs.openstack.org/ops-guide/ops-maintenance-compute.html>`_
+  for more information on maintenance.
+
 Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
@@ -121,6 +142,19 @@ Reboot Host
 
 Reboots a host.
 
+.. warning::
+
+  This is only supported by the XenServer and Hyper-v drivers. The backing
+  drivers do no orchestration of dealing with guests in the nova database when
+  performing a reboot of the host. The nova-compute service for that host may
+  be temporarily disabled by the service group health check which would take it
+  out of scheduling decisions, and the guests would be down, but the periodic
+  task which checks for unexpectedly stopped instances runs in the nova-compute
+  service, which might be dead now so the nova API would show the instances as
+  running when in fact they are actually stopped. This API is also not tested
+  in a live running OpenStack environment. Needless to say, it is not
+  recommended to use this API and it is deprecated as of the 2.43 microversion.
+
 Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
@@ -153,6 +187,19 @@ Shut Down Host
 
 Shuts down a host.
 
+.. warning::
+
+  This is only supported by the XenServer and Hyper-v drivers. The backing
+  drivers do no orchestration of dealing with guests in the nova database when
+  performing a shutdown of the host. The nova-compute service for that host may
+  be temporarily disabled by the service group health check which would take it
+  out of scheduling decisions, and the guests would be down, but the periodic
+  task which checks for unexpectedly stopped instances runs in the nova-compute
+  service, which might be dead now so the nova API would show the instances as
+  running when in fact they are actually stopped. This API is also not tested
+  in a live running OpenStack environment. Needless to say, it is not
+  recommended to use this API and it is deprecated as of the 2.43 microversion.
+
 Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
@@ -185,6 +232,12 @@ Start Host
 
 Starts a host.
 
+.. warning::
+
+  This is not implemented by any in-tree compute drivers and therefore will
+  always fail with a `501 NotImplemented` error. Needless to say, it is not
+  recommended to use this API and it is deprecated as of the 2.43 microversion.
+
 Normal response codes: 200
 
 Error response codes: badRequest(400), unauthorized(401), forbidden(403),
diff --git a/api-ref/source/os-hypervisors.inc b/api-ref/source/os-hypervisors.inc
index 9e58f4af64..79e78b546c 100644
--- a/api-ref/source/os-hypervisors.inc
+++ b/api-ref/source/os-hypervisors.inc
@@ -1,5 +1,7 @@
 .. -*- rst -*-
 
+.. _os-hypervisors:
+
 ==============================
  Hypervisors (os-hypervisors)
 ==============================
diff --git a/api-ref/source/os-services.inc b/api-ref/source/os-services.inc
index 1d72f9efc2..ef912d2297 100644
--- a/api-ref/source/os-services.inc
+++ b/api-ref/source/os-services.inc
@@ -1,5 +1,7 @@
 .. -*- rst -*-
 
+.. _os-services:
+
 ================================
  Compute services (os-services)
 ================================
diff --git a/doc/api_samples/versions/v21-version-get-resp.json b/doc/api_samples/versions/v21-version-get-resp.json
index 64120de26c..241212017e 100644
--- a/doc/api_samples/versions/v21-version-get-resp.json
+++ b/doc/api_samples/versions/v21-version-get-resp.json
@@ -19,7 +19,7 @@
             }
         ],
         "status": "CURRENT",
-        "version": "2.42",
+        "version": "2.43",
         "min_version": "2.1",
         "updated": "2013-07-23T11:33:21Z"
     }
diff --git a/doc/api_samples/versions/versions-get-resp.json b/doc/api_samples/versions/versions-get-resp.json
index 27ad9b3703..924b060df1 100644
--- a/doc/api_samples/versions/versions-get-resp.json
+++ b/doc/api_samples/versions/versions-get-resp.json
@@ -22,7 +22,7 @@
                 }
             ],
             "status": "CURRENT",
-            "version": "2.42",
+            "version": "2.43",
             "min_version": "2.1",
             "updated": "2013-07-23T11:33:21Z"
         }
diff --git a/nova/api/openstack/api_version_request.py b/nova/api/openstack/api_version_request.py
index 7f08d4b02e..254920e211 100644
--- a/nova/api/openstack/api_version_request.py
+++ b/nova/api/openstack/api_version_request.py
@@ -102,6 +102,7 @@ REST_API_VERSION_HISTORY = """REST API Version History:
              re-introduce the tag attribute that, due to bugs, was lost
              starting with version 2.33 for block devices and starting with
              version 2.37 for network interfaces.
+    * 2.43 - Deprecate os-hosts API
 """
 
 # The minimum and maximum versions of the API supported
@@ -110,7 +111,7 @@ REST_API_VERSION_HISTORY = """REST API Version History:
 # 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.42"
+_MAX_API_VERSION = "2.43"
 DEFAULT_API_VERSION = _MIN_API_VERSION
 
 # Almost all proxy APIs which related to network, images and baremetal
diff --git a/nova/api/openstack/compute/hosts.py b/nova/api/openstack/compute/hosts.py
index a9d2f6dfab..565a3e08de 100644
--- a/nova/api/openstack/compute/hosts.py
+++ b/nova/api/openstack/compute/hosts.py
@@ -40,6 +40,7 @@ class HostController(wsgi.Controller):
         self.api = compute.HostAPI()
         super(HostController, self).__init__()
 
+    @wsgi.Controller.api_version("2.1", "2.42")
     @extensions.expected_errors(())
     def index(self, req):
         """Returns a dict in the format
@@ -96,6 +97,7 @@ class HostController(wsgi.Controller):
                               'zone': service['availability_zone']})
         return {'hosts': hosts}
 
+    @wsgi.Controller.api_version("2.1", "2.42")
     @extensions.expected_errors((400, 404, 501))
     @validation.schema(hosts.update)
     def update(self, req, id, body):
@@ -187,14 +189,17 @@ class HostController(wsgi.Controller):
             raise webob.exc.HTTPBadRequest(explanation=e.format_message())
         return {"host": host_name, "power_action": result}
 
+    @wsgi.Controller.api_version("2.1", "2.42")
     @extensions.expected_errors((400, 404, 501))
     def startup(self, req, id):
         return self._host_power_action(req, host_name=id, action="startup")
 
+    @wsgi.Controller.api_version("2.1", "2.42")
     @extensions.expected_errors((400, 404, 501))
     def shutdown(self, req, id):
         return self._host_power_action(req, host_name=id, action="shutdown")
 
+    @wsgi.Controller.api_version("2.1", "2.42")
     @extensions.expected_errors((400, 404, 501))
     def reboot(self, req, id):
         return self._host_power_action(req, host_name=id, action="reboot")
@@ -248,6 +253,7 @@ class HostController(wsgi.Controller):
                                     instance['ephemeral_gb'])
         return project_map
 
+    @wsgi.Controller.api_version("2.1", "2.42")
     @extensions.expected_errors(404)
     def show(self, req, id):
         """Shows the physical/usage resource given by hosts.
diff --git a/nova/api/openstack/compute/rest_api_version_history.rst b/nova/api/openstack/compute/rest_api_version_history.rst
index 5e6b0ffd0f..afcfd03f6d 100644
--- a/nova/api/openstack/compute/rest_api_version_history.rst
+++ b/nova/api/openstack/compute/rest_api_version_history.rst
@@ -482,3 +482,14 @@ user documentation.
   2.37 and for block_device_mapping_v2 starting with version 2.33. Microversion
   2.42 restores the tag parameter to both networks and block_device_mapping_v2,
   allowing networks and block devices to be tagged again.
+
+2.43
+----
+
+  The ``os-hosts`` API is deprecated as of the 2.43 microversion. Requests
+  made with microversion >= 2.43 will result in a 404 error. To list and show
+  host details, use the ``os-hypervisors`` API. To enable or disable a
+  service, use the ``os-services`` API. There is no replacement for the
+  `shutdown`, `startup`, `reboot`, or `maintenance_mode` actions as those are
+  system-level operations which should be outside of the control of the
+  compute service.
diff --git a/nova/tests/unit/api/openstack/compute/test_hosts.py b/nova/tests/unit/api/openstack/compute/test_hosts.py
index da2432f15d..902a473cd8 100644
--- a/nova/tests/unit/api/openstack/compute/test_hosts.py
+++ b/nova/tests/unit/api/openstack/compute/test_hosts.py
@@ -17,6 +17,7 @@ import mock
 import testtools
 import webob.exc
 
+from nova.api.openstack import api_version_request as api_version
 from nova.api.openstack.compute import hosts as os_hosts_v21
 from nova.compute import power_state
 from nova.compute import vm_states
@@ -131,6 +132,7 @@ def _create_instance_dict(**kwargs):
 class FakeRequestWithNovaZone(object):
     environ = {"nova.context": context_maker.get_admin_context()}
     GET = {"zone": "nova"}
+    api_version_request = api_version.APIVersionRequest('2.1')
 
 
 class HostTestCaseV21(test.TestCase):
@@ -413,3 +415,26 @@ class HostsPolicyEnforcementV21(test.NoDBTestCase):
         self.assertEqual(
             "Policy doesn't allow %s to be performed." % rule_name,
             exc.format_message())
+
+
+class HostControllerDeprecationTest(test.NoDBTestCase):
+
+    def setUp(self):
+        super(HostControllerDeprecationTest, self).setUp()
+        self.controller = os_hosts_v21.HostController()
+        self.req = fakes.HTTPRequest.blank('', version='2.43')
+
+    def test_not_found_for_all_host_api(self):
+        self.assertRaises(exception.VersionNotFoundForAPIMethod,
+                          self.controller.show, self.req, fakes.FAKE_UUID)
+        self.assertRaises(exception.VersionNotFoundForAPIMethod,
+                          self.controller.startup, self.req, fakes.FAKE_UUID)
+        self.assertRaises(exception.VersionNotFoundForAPIMethod,
+                          self.controller.shutdown, self.req, fakes.FAKE_UUID)
+        self.assertRaises(exception.VersionNotFoundForAPIMethod,
+                          self.controller.reboot, self.req, fakes.FAKE_UUID)
+        self.assertRaises(exception.VersionNotFoundForAPIMethod,
+                          self.controller.index, self.req)
+        self.assertRaises(exception.VersionNotFoundForAPIMethod,
+                          self.controller.update, self.req, fakes.FAKE_UUID,
+                          body={})
diff --git a/releasenotes/notes/microversion-2.43-77d63cae38695fd1.yaml b/releasenotes/notes/microversion-2.43-77d63cae38695fd1.yaml
new file mode 100644
index 0000000000..afb39b8065
--- /dev/null
+++ b/releasenotes/notes/microversion-2.43-77d63cae38695fd1.yaml
@@ -0,0 +1,10 @@
+---
+deprecations:
+  - |
+    The ``os-hosts`` API is deprecated as of the 2.43 microversion. Requests
+    made with microversion >= 2.43 will result in a 404 error. To list and show
+    host details, use the ``os-hypervisors`` API. To enable or disable a
+    service, use the ``os-services`` API. There is no replacement for the
+    `shutdown`, `startup`, `reboot`, or `maintenance_mode` actions as those are
+    system-level operations which should be outside of the control of the
+    compute service.