openstack/nova
Code Issues Proposed changes

[placement] placement_dev info for microversion handling

Browse Source 
A section for placement_dev.rst describing how to manage
microversions, including available utility methods.

Change-Id: I8ace96ed7fd721c547cedf5285833a8baa52a70a
This commit is contained in:
Chris Dent 2016-12-16 18:32:42 +00:00 committed by Matt Riedemann
parent db203ffe62
commit 2d0dfc632f
2 changed files with 49 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/placement.rst
View File

@ -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

52
doc/source/placement_dev.rst
View File

@ -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