openstack/placement
Code Issues Proposed changes

Update contributor/placement.rst to contemporary reality

Browse Source 
This udpates the placement contributor documentation to reflect the
current state of affairs. Ininitially this was just going to be an
update to reflect that the oslo versioned objects had moved. However,
while reviewing the rest of the doc it became clear there were other
issues that should be resolved. Doing so in one shot helps to maintain
the continuity of the document and doing it piecemeal means it is less
likely to happen.

Change-Id: Ia8d4861799e27a30108dd465d15828c5a1943819
This commit is contained in:
Chris Dent 2018-03-14 09:58:29 +00:00
parent 5b734c4f20
commit 1bad050a15
1 changed files with 31 additions and 37 deletions

68
doc/source/contributor/placement.rst

@ -54,11 +54,11 @@ additional resources should be considered a significant change requiring robust
review from many stakeholders. review from many stakeholders.
The set of HTTP resources represents a concise and constrained grammar for The set of HTTP resources represents a concise and constrained grammar for
expressing the management of resource providers, inventories, resource classes expressing the management of resource providers, inventories, resource classes,
and allocations. If a solution is initially designed to need more resources or traits, and allocations. If a solution is initially designed to need more
a more complex grammar that may be a sign that we need to give our goals resources or a more complex grammar that may be a sign that we need to give our
greater scrutiny. Is there a way to do what we want with what we have already? goals greater scrutiny. Is there a way to do what we want with what we have
Can some other service help? Is a new collaborating service required? already? Can some other service help? Is a new collaborating service required?
Minimal Framework Minimal Framework
================= =================
@ -172,18 +172,12 @@ granular way to have different behavior per microversion. A
``Version`` instance can be treated as a tuple of two ints and ``Version`` instance can be treated as a tuple of two ints and
compared as such or there is a ``matches`` method. compared as such or there is a ``matches`` method.
In other cases there are some helper methods in the microversion A ``version_handler`` decorator is also available. It makes it possible to have
package: multiple different handler methods of the same (fully-qualified by package)
name, each available for a different microversion window. If a request wants a
* The ``raise_http_status_code_if_not_version`` utility will raise a microversion that's not available, a defined status code is returned (usually
http status code if the requested microversion is not within a ``404`` or ``405``). There is a unit test in place which will fail if there are
described version window. version intersections.
* 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 Adding a New Handler
==================== ====================
@ -245,7 +239,8 @@ request, the caller is responsible for selecting the right one before calling
``extract_json``. ``extract_json``.
When a handler needs to read or write the data store it should use methods on When a handler needs to read or write the data store it should use methods on
the objects found in the `nova.objects.resource_provider` package. Doing so the objects found in the
`nova.api.openstack.placement.objects.resource_provider` package. Doing so
requires a context which is provided to the handler method via the WSGI requires a context which is provided to the handler method via the WSGI
environment. It can be retrieved as follows:: environment. It can be retrieved as follows::
@ -266,9 +261,9 @@ Most of the handler code in the placement API is tested using `gabbi`_. Some
utility code is tested with unit tests found in utility code is tested with unit tests found in
`nova/tests/unit/api/openstack/placement/`. The back-end objects are tested `nova/tests/unit/api/openstack/placement/`. The back-end objects are tested
with a combination of unit and functional tests found in with a combination of unit and functional tests found in
``nova/tests/unit/objects/test_resource_provider.py`` and ``nova/tests/unit/api/openstack/placement/objects/test_resource_provider.py``
`nova/tests/functional/db`. Adding unit and non-gabbi functional tests is done and `nova/tests/functional/db`. Adding unit and non-gabbi functional tests is
in the same way as other aspects of nova. done in the same way as other aspects of nova.
Using Gabbi Using Gabbi
----------- -----------
@ -283,12 +278,12 @@ application is run via `wsgi-intercept`_, meaning that real HTTP requests are
being made over a file handle that appears to Python to be a socket. being made over a file handle that appears to Python to be a socket.
In the placement API the YAML files (aka "gabbits") can be found in In the placement API the YAML files (aka "gabbits") can be found in
``nova/tests/functional/api/openstack/placement/gabbits``. Fixture definitions are ``nova/tests/functional/api/openstack/placement/gabbits``. Fixture definitions
in ``fixtures.py`` in the parent directory. Tests are currently grouped by handlers are in ``fixtures.py`` in the parent directory. Tests are currently grouped by
(e.g., ``resource-provider.yaml`` and ``inventory.yaml``). This is not a handlers (e.g., ``resource-provider.yaml`` and ``inventory.yaml``). This is not
requirement and as we increase the number of tests it makes sense to have more a requirement and as we increase the number of tests it makes sense to have
YAML files with fewer tests, divided up by the arc of API interaction that they more YAML files with fewer tests, divided up by the arc of API interaction that
test. they test.
The gabbi tests are integrated into the functional tox target, loaded via The gabbi tests are integrated into the functional tox target, loaded via
``nova/tests/functional/api/openstack/placement/test_placement_api.py``. If you ``nova/tests/functional/api/openstack/placement/test_placement_api.py``. If you
@ -307,10 +302,10 @@ the name in the yaml file, replacing space with ``_``::
tox -efunctional placement_api.inventory_post_new_ipv4_address_inventory tox -efunctional placement_api.inventory_post_new_ipv4_address_inventory
.. note:: `.testr.conf` in the nova repository is configured such that each .. note:: ``tox.ini`` in the nova repository is configured by a ``group_regex``
gabbi YAML is considered a group. Thus, all tests in the file will so that each gabbi YAML is considered a group. Thus, all tests in the
be run in the same process when running testr concurrently (the file will be run in the same process when running stestr concurrently
default). (the default).
Writing More Gabbi Tests Writing More Gabbi Tests
------------------------ ------------------------
@ -365,20 +360,19 @@ To lessen the pain of the eventual extraction of placement the service has been
developed in a way to limit dependency on the rest of the nova codebase and be developed in a way to limit dependency on the rest of the nova codebase and be
self-contained: self-contained:
* Most code is in `nova/api/openstack/placement` except for oslo versioned * Most code is in `nova/api/openstack/placement`.
object code in ``nova/objects/resource_provider.py``. * Database query code is kept within the objects in
* Database query code is kept within the objects. `nova/api/openstack/placement/objects`.
* The methods on the objects are not remotable, as the only intended caller is * The methods on the objects are not remotable, as the only intended caller is
the placement API code. the placement API code.
There are some exceptions to the self-contained rule (which will have to be There are some exceptions to the self-contained rule (which are actively being
addressed if the extraction ever happens): addressed to prepare for the extraction):
* Exceptions unique to the placement API are still within the `nova.exceptions` * Exceptions unique to the placement API are still within the `nova.exceptions`
package. package.
* Code related to a resource class cache is within the `nova.db` package. * Code related to a resource class cache is within the `nova.db` package.
* Database models, migrations and tables use the nova api database. * Database models, migrations and tables use the nova api database.
* The nova `FaultWrapper` middleware is being used.
* `nova.i18n` package provides the ``_`` and related functions. * `nova.i18n` package provides the ``_`` and related functions.
* ``nova.conf`` is used for configuration. * ``nova.conf`` is used for configuration.
* Unit and functional tests depend on fixtures and other functionality in base * Unit and functional tests depend on fixtures and other functionality in base