From aad4be2e3d071aa402d53178689b350436ae4b34 Mon Sep 17 00:00:00 2001 From: jichenjc Date: Mon, 27 Mar 2017 17:49:11 +0800 Subject: [PATCH] Deprecate os-hosts API This patch deprecates os-hosts APIs including: GET /os-hosts - list hosts GET /os-hosts/{host_name} - show host details PUT /os-hosts/{host_name} - update host status GET /os-hosts/{host_name}/reboot - reboot host GET /os-hosts/{host_name}/shutdown - shutdown host GET /os-hosts/{host_name}/startup - start host Much of the ``os-hosts`` API is duplicated with the ``os-services`` and ``os-hypervisors`` APIs. It's not a good idea to make nova have the compute related API, so this patch deprecated them. Implements blueprint deprecate-os-hosts Co-Authored-By: Matt Riedemann Change-Id: Ieb85653b85a1eff38a9fb0c9ff05e4cd39150ecc --- api-ref/source/index.rst | 2 +- api-ref/source/os-hosts.inc | 59 ++++++++++++++++++- api-ref/source/os-hypervisors.inc | 2 + api-ref/source/os-services.inc | 2 + .../versions/v21-version-get-resp.json | 2 +- .../versions/versions-get-resp.json | 2 +- nova/api/openstack/api_version_request.py | 3 +- nova/api/openstack/compute/hosts.py | 6 ++ .../compute/rest_api_version_history.rst | 11 ++++ .../unit/api/openstack/compute/test_hosts.py | 25 ++++++++ .../microversion-2.43-77d63cae38695fd1.yaml | 10 ++++ 11 files changed, 117 insertions(+), 7 deletions(-) create mode 100644 releasenotes/notes/microversion-2.43-77d63cae38695fd1.yaml diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index b32f873e6251..ffb989956e08 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -43,7 +43,6 @@ the `API guide `_. .. 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 `_. .. 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 8356d260bc10..89b93db94bc5 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 `_ + 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 9e58f4af64c6..79e78b546c28 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 1d72f9efc208..ef912d2297d7 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 64120de26c91..241212017eae 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 27ad9b370360..924b060df15d 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 7f08d4b02e7e..254920e211d3 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 a9d2f6dfab94..565a3e08de6a 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 5e6b0ffd0fd7..afcfd03f6d4f 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 da2432f15db2..902a473cd8c6 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 000000000000..afb39b806513 --- /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.