openstack/nova
Code Issues Proposed changes

Update some placement docs to reflect modern times

Browse Source 
This change provides a small number of updates to the placement user and
contributor documentation to reflect some of the things that have
changed recently. This is by no means complete, but is an improvement
over what was there.

Partial-Bug: #1778227

Change-Id: Ia348cd3c99b1a5104e15595fdebc83e1ca582a98
This commit is contained in:
Chris Dent 2018-07-09 23:29:28 +01:00 committed by Matt Riedemann
parent 194e842c30
commit cc7f4ea724
2 changed files with 31 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
doc/source/contributor/placement.rst
View File

@ -281,8 +281,8 @@ utility code is tested with unit tests found in
`nova/tests/unit/api/openstack/placement/`. The back-end objects are tested
with a combination of unit and functional tests found in
``nova/tests/unit/api/openstack/placement/objects/test_resource_provider.py``
and `nova/tests/functional/db`. Adding unit and non-gabbi functional tests is
done in the same way as other aspects of nova.
and `nova/tests/functional/api/openstack/placement/db`. Adding unit and
non-gabbi functional tests is done in the same way as other aspects of nova.
When writing tests for handler code (that is, the code found in
``nova/api/openstack/placement/handlers``) a good rule of thumb is that if you
@ -311,11 +311,11 @@ 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
``nova/tests/functional/api/openstack/placement/gabbits``. Fixture definitions
are in ``fixtures.py`` in the parent directory. Tests are currently grouped by
handlers (e.g., ``resource-provider.yaml`` and ``inventory.yaml``). This is not
a requirement and as we increase the number of tests it makes sense to have
more YAML files with fewer tests, divided up by the arc of API interaction that
they test.
are in ``nova/tests/functional/api/openstack/placement/fixtures/gabbits.py``.
Tests are frequently grouped by handler name (e.g., ``resource-provider.yaml``
and ``inventory.yaml``). This is not a requirement and as we increase the
number of tests it makes sense to have more YAML files with fewer tests,
divided up by the arc of API interaction that they test.
The gabbi tests are integrated into the functional tox target, loaded via
``nova/tests/functional/api/openstack/placement/test_placement_api.py``. If you
@ -401,10 +401,12 @@ self-contained:
There are some exceptions to the self-contained rule (which are actively being
addressed to prepare for the extraction):
* Exceptions unique to the placement API are still within the `nova.exceptions`
package.
* Code related to a resource class cache is within the `nova.db` package.
* Database models, migrations and tables use the nova api database.
* Some of the code related to a resource class cache is within the `nova.db`
package, while other parts are in ``nova/rc_fields.py``.
* Database models, migrations and tables are described as part of the nova api
database. An optional configuration option,
:oslo.config:option:`placement_database.connection`, can be set to use a
database just for placement (based on the api database schema).
* `nova.i18n` package provides the ``_`` and related functions.
* ``nova.conf`` is used for configuration.
* Unit and functional tests depend on fixtures and other functionality in base

25
doc/source/user/placement.rst
View File

@ -29,9 +29,9 @@ from an external shared storage pool resource provider and IP addresses from
an external IP pool resource provider.
The types of resources consumed are tracked as **classes**. The service
provides a set of standard resource classes (for example `DISK_GB`,
`MEMORY_MB`, and `VCPU`) and provides the ability to define custom resource
classes as needed.
provides a set of standard resource classes (for example ``DISK_GB``,
``MEMORY_MB``, and ``VCPU``) and provides the ability to define custom
resource classes as needed.
Each resource provider may also have a set of traits which describe qualitative
aspects of the resource provider. Traits describe an aspect of a resource
@ -147,10 +147,17 @@ option for the placement API service and the resources it manages. After
upgrading the nova-api service for Newton and running the
``nova-manage api_db sync`` command the placement tables will be created.
.. note:: There are plans to add the ability to run the placement service
with a separate **placement** database that would just have the tables
necessary for that service and not everything else that goes into the
Nova **api** database.
With the Rocky release, it has become possible to use a separate database for
placement. If :oslo.config:option:`placement_database.connection` is
configured with a database connect string, that database will be used for
storing placement data. Once the database is created, the
``nova-manage api_db sync`` command will create and synchronize both the
nova api and placement tables. If ``[placement_database]/connection`` is not
set, the nova api database will be used.
.. note:: At this time there is no facility for migrating existing placement
data from the nova api database to a placement database. There are
many ways to do this. Which one is best will depend on the environment.
**3. Create accounts and update the service catalog**
@ -300,6 +307,10 @@ Rocky (18.0.0)
associations to the placement service. This change is idempotent if
``[placement]`` is not configured in ``nova-api`` but it will result in new
warnings in the logs until configured.
* As described above, before Rocky, the placement service used the nova api
database to store placement data. In Rocky, if the ``connection`` setting in
a ``[placement_database]`` group is set in configuration, that group will be
used to describe where and how placement data is stored.
REST API
========