Update contributor/placement.rst to contemporary reality
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:
parent
5b734c4f20
commit
1bad050a15
@ -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
|
||||||
|
Loading…
x
Reference in New Issue
Block a user