From 2d0dfc632f81bd328392659c6fd097b103c14b01 Mon Sep 17 00:00:00 2001 From: Chris Dent Date: Fri, 16 Dec 2016 18:32:42 +0000 Subject: [PATCH] [placement] placement_dev info for microversion handling A section for placement_dev.rst describing how to manage microversions, including available utility methods. Change-Id: I8ace96ed7fd721c547cedf5285833a8baa52a70a --- doc/source/placement.rst | 6 ----- doc/source/placement_dev.rst | 52 +++++++++++++++++++++++++++++++++--- 2 files changed, 49 insertions(+), 9 deletions(-) diff --git a/doc/source/placement.rst b/doc/source/placement.rst index b4a5eaa82a39..282829a67f75 100644 --- a/doc/source/placement.rst +++ b/doc/source/placement.rst @@ -153,16 +153,10 @@ Microversions The placement API uses microversions for making incremental changes to the API which client requests must opt into. -The rules around `when a microversion is needed`_ are the same as for the -compute REST API. - -.. _when a microversion is needed: http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion - It is especially important to keep in mind that nova-compute is a client of the placement REST API and based on how Nova supports rolling upgrades the nova-compute service could be Newton level code making requests to an Ocata placement API, and vice-versa, an Ocata compute service in a cells v2 cell could be making requests to a Newton placement API. - .. include:: ../../nova/api/openstack/placement/rest_api_version_history.rst diff --git a/doc/source/placement_dev.rst b/doc/source/placement_dev.rst index dd4ed022057c..e90c1806b724 100644 --- a/doc/source/placement_dev.rst +++ b/doc/source/placement_dev.rst @@ -128,9 +128,52 @@ surprising or unexpected. Microversions ============= -.. TODO(cdent) fill in with how and why of microversions, maybe move some content - from placement.rst, but include references to the decorators and - other vailable methods. +The placement API makes use of `microversions`_ to allow the release of +new features on an opt in basis. See :doc:`placement` for an up to date +history of the available microversions. + +The rules around `when a microversion is needed`_ are the same as for the +compute API. When adding a new microversion there are a few bits of +required housekeeping that must be done in the code: + +* Update the ``VERSIONS`` list in + `nova.api.openstack.placement.microversion` to indicate the new + microversion and give a very brief summary of the added feature. +* Update `nova/api/openstack/placement/rest_api_version_history.rst` + to add a more detailed section describing the new microversion. +* Add a `release note`_ announcing the new or changed feature and + the microversion. +* If the ``version_handler`` decorator (see below) has been used, + increment ``TOTAL_VERSIONED_METHODS`` in + `nova/tests/unit/api/openstack/placement/test_microversion.py`. + This provides a confirmatory check just to make sure you're paying + attention and as a helpful reminder to do the other things in this + list. + +In the placement API, microversions only use the modern form of the +version header:: + + OpenStack-API-Version: placement 1.2 + +If a valid microversion is present in a request it will be placed, +as a ``Version`` object, into the WSGI environment with the +``placement.microversion`` key. Often, accessing this in handler +code directly (to control branching) is the most explicit and +granular way to have different behavior per microversion. A +``Version`` instance can be treated as a tuple of two ints and +compared as such or there is a ``matches`` method. + +In other cases there are some helper methods in the microversion +package: + +* The ``raise_404_if_not_version`` utility will cause a 404 if the + requested microversion is not within a described version window. +* The ``version_handler`` decorator makes it possible to have + multiple different handler methods of the same (fully-qualified by + package) name, each available for a different microversion window. + If a request wants a microversion that's not available, a 404 + response is returned. There is a unit test in place which will + fail if there are version intersections. Adding a New Handler ==================== @@ -154,3 +197,6 @@ Futures .. _WebOb: http://docs.webob.org/en/latest/ .. _Request: http://docs.webob.org/en/latest/reference.html#request .. _Response: http://docs.webob.org/en/latest/#response +.. _microversions: http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html +.. _when a microversion is needed: http://docs.openstack.org/developer/nova/api_microversion_dev.html#when-do-i-need-a-new-microversion +.. _release note: http://docs.openstack.org/developer/reno/usage.html