Clean up document's index
In the top index page of the document, some sections had actual contents and some had only links to the contents. However, this makes it difficult for readers to get what is in the document and what isn't at a glance. This patch cleans it up to simplify the top index. This patch also renames some of the directories to follow the doc layout rules[1]. [1] https://specs.openstack.org/openstack/docs-specs/specs/pike/os-manuals-migration.html Note that the following ToDo is left for further cleanup: * Publish the api guide and move the microversion history to the `/api-guide` directory Change-Id: Ideb1d5e7c74d1d564d07bac1a1e7c86c55ede873
This commit is contained in:
Tetsuro Nakamura
parent
c541277906
commit
ac1e0f8afe
|
|
@ -29,7 +29,6 @@ coverage.xml
|
|||
cover/*
|
||||
covhtml/*
|
||||
dist/*
|
||||
doc/source/api/*
|
||||
doc/build/*
|
||||
api-guide/build/*
|
||||
api-ref/build/*
|
||||
|
|
|
|||
|
|
@ -1,3 +1,6 @@
|
|||
redirectmatch 301 ^/placement/([^/]+)/specs/train/approved/2005297-negative-aggregate-membership.html /placement/$1/specs/train/implemented/2005297-negative-aggregate-membership.html
|
||||
redirectmatch 301 ^/placement/([^/]+)/specs/train/approved/placement-resource-provider-request-group-mapping-in-allocation-candidates.html /placement/$1/specs/train/implemented/placement-resource-provider-request-group-mapping-in-allocation-candidates.html
|
||||
redirectmatch 301 ^/placement/([^/]+)/specs/train/approved/2005575-nested-magic-1.html /placement/$1/specs/train/implemented/2005575-nested-magic-1.html
|
||||
redirectmatch 301 ^/placement/([^/]+)/upgrade/to-stein.html /placement/$1/admin/upgrade-to-stein.html
|
||||
redirectmatch 301 ^/placement/([^/]+)/usage/index.html /placement/$1/user/index.html
|
||||
redirectmatch 301 ^/placement/([^/]+)/usage/provider-tree.html /placement/$1/user/provider-tree.html
|
||||
|
|
|
|||
|
|
@ -11,9 +11,12 @@
|
|||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
===========
|
||||
Placeholder
|
||||
===========
|
||||
Upgrade
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
upgrade-notes
|
||||
upgrade-to-stein
|
||||
|
||||
This is a placeholder document until the first specification has been
|
||||
created in approved or moved to implemented.
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
=============
|
||||
Upgrade Notes
|
||||
=============
|
||||
|
||||
This section provide notes on upgrading to a given target release.
|
||||
|
||||
.. note::
|
||||
|
||||
As a reminder, the
|
||||
:ref:`placement-status upgrade check <placement-status-checks>` tool can be
|
||||
used to help determine the status of your deployment and how ready it is to
|
||||
perform an upgrade.
|
||||
|
||||
For releases prior to Stein, please see the `nova upgrade notes`_.
|
||||
|
||||
.. _nova upgrade notes: https://docs.openstack.org/nova/rocky/user/placement.html#upgrade-notes
|
||||
|
||||
|
||||
Stein (1.0.0)
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
If you are upgrading an existing OpenStack installation from Rocky to Stein,
|
||||
and wish to use the newly extracted placement, you will need to copy some
|
||||
data and configuration settings from nova.
|
||||
|
||||
* Configuration and policy files are, by default, located in
|
||||
``/etc/placement``.
|
||||
* The placement server side settings in ``nova.conf`` should be moved to a
|
||||
separate placement configuration file ``placement.conf``.
|
||||
* The default configuration value of ``[placement]/policy_file`` is changed
|
||||
from ``placement-policy.yaml`` to ``policy.yaml``
|
||||
* Several tables in the ``nova_api`` database need to be migrated to a new
|
||||
``placement`` database.
|
||||
|
||||
Following these steps will ensure that future changes to placement
|
||||
configuration and code will not conflict with your setup.
|
||||
|
||||
As stated above, using the extracted placement code is not required in Stein,
|
||||
there is a copy in the Stein release of Nova. However that code will be deleted
|
||||
in the Train cycle so you must upgrade to external Placement prior to
|
||||
upgrading to Train.
|
||||
|
|
@ -11,12 +11,9 @@
|
|||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
===============
|
||||
Placement API
|
||||
===============
|
||||
|
||||
Overview
|
||||
========
|
||||
===========
|
||||
Placement
|
||||
===========
|
||||
|
||||
The placement API service was introduced in the 14.0.0 Newton release within
|
||||
the nova repository and extracted to the `placement repository`_ in the 19.0.0
|
||||
|
|
@ -39,304 +36,60 @@ aspects of the resource provider. Traits describe an aspect of a resource
|
|||
provider that cannot itself be consumed but a workload may wish to specify. For
|
||||
example, available disk may be solid state drives (SSD).
|
||||
|
||||
.. _placement repository: https://opendev.org/openstack/placement
|
||||
|
||||
Usages
|
||||
======
|
||||
|
||||
This section documents an overview of some of the features provided by placement.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
usage/index
|
||||
user/index
|
||||
|
||||
Command Line Interface
|
||||
======================
|
||||
|
||||
This section documents a command line reference.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
cli/index
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
This section provides information on configuring the system, including
|
||||
role-based access control policy rules.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
configuration/index
|
||||
|
||||
Contribution
|
||||
============
|
||||
|
||||
This section provides information on how to contribute to the placement
|
||||
project and development processes and guidelines.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
contributor/index
|
||||
|
||||
Specifications
|
||||
==============
|
||||
|
||||
Significant feature developments are tracked in documents called specifications.
|
||||
From the Train cycle onward, those documents are kept in this section.
|
||||
Prior to that, Placement specifications were a part of the `Nova Specs`_.
|
||||
|
||||
The following specifications represent the stages of design and development of
|
||||
resource providers and the Placement service. Implementation details may have
|
||||
changed or be partially complete at this time.
|
||||
|
||||
|
||||
* `Generic Resource Pools <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/generic-resource-pools.html>`_
|
||||
* `Compute Node Inventory <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/compute-node-inventory-newton.html>`_
|
||||
* `Resource Provider Allocations <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/resource-providers-allocations.html>`_
|
||||
* `Resource Provider Base Models <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/resource-providers.html>`_
|
||||
* `Nested Resource Providers`_
|
||||
* `Custom Resource Classes <http://specs.openstack.org/openstack/nova-specs/specs/ocata/implemented/custom-resource-classes.html>`_
|
||||
* `Scheduler Filters in DB <http://specs.openstack.org/openstack/nova-specs/specs/ocata/implemented/resource-providers-scheduler-db-filters.html>`_
|
||||
* `Scheduler claiming resources to the Placement API <http://specs.openstack.org/openstack/nova-specs/specs/pike/approved/placement-claims.html>`_
|
||||
* `The Traits API - Manage Traits with ResourceProvider <http://specs.openstack.org/openstack/nova-specs/specs/pike/approved/resource-provider-traits.html>`_
|
||||
* `Request Traits During Scheduling`_
|
||||
* `filter allocation candidates by aggregate membership`_
|
||||
* `perform granular allocation candidate requests`_
|
||||
* `inventory and allocation data migration`_ (reshaping provider trees)
|
||||
* `handle allocation updates in a safe way`_
|
||||
|
||||
.. _Nested Resource Providers: http://specs.openstack.org/openstack/nova-specs/specs/queens/approved/nested-resource-providers.html
|
||||
.. _Request Traits During Scheduling: https://specs.openstack.org/openstack/nova-specs/specs/queens/approved/request-traits-in-nova.html
|
||||
.. _filter allocation candidates by aggregate membership: https://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/alloc-candidates-member-of.html
|
||||
.. _perform granular allocation candidate requests: http://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/granular-resource-requests.html
|
||||
.. _inventory and allocation data migration: http://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/reshape-provider-tree.html
|
||||
.. _handle allocation updates in a safe way: https://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/add-consumer-generation.html
|
||||
.. _Nova Specs: http://specs.openstack.org/openstack/nova-specs
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
specs/index
|
||||
|
||||
Deployment
|
||||
==========
|
||||
|
||||
.. note:: Before the Stein release the placement code was in Nova alongside
|
||||
the compute REST API code (nova-api). Make sure that the release
|
||||
version of this document matches the release version you want to
|
||||
deploy.
|
||||
|
||||
Steps Overview
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
This subsection gives an overview of the process without going into detail
|
||||
on the methods used.
|
||||
|
||||
**1. Deploy the API service**
|
||||
|
||||
Placement provides a ``placement-api`` WSGI script for running the service with
|
||||
Apache, nginx or other WSGI-capable web servers. Depending on what packaging
|
||||
solution is used to deploy OpenStack, the WSGI script may be in ``/usr/bin``
|
||||
or ``/usr/local/bin``.
|
||||
|
||||
``placement-api``, as a standard WSGI script, provides a module level
|
||||
``application`` attribute that most WSGI servers expect to find. This means it
|
||||
is possible to run it with lots of different servers, providing flexibility in
|
||||
the face of different deployment scenarios. Common scenarios include:
|
||||
|
||||
* apache2_ with mod_wsgi_
|
||||
* apache2 with mod_proxy_uwsgi_
|
||||
* nginx_ with uwsgi_
|
||||
* nginx with gunicorn_
|
||||
|
||||
In all of these scenarios the host, port and mounting path (or prefix) of the
|
||||
application is controlled in the web server's configuration, not in the
|
||||
configuration (``placement.conf``) of the placement application.
|
||||
|
||||
When placement was `first added to DevStack`_ it used the ``mod_wsgi`` style.
|
||||
Later it `was updated`_ to use mod_proxy_uwsgi_. Looking at those changes can
|
||||
be useful for understanding the relevant options.
|
||||
|
||||
DevStack is configured to host placement at ``/placement`` on either the
|
||||
default port for http or for https (``80`` or ``443``) depending on whether TLS
|
||||
is being used. Using a default port is desirable.
|
||||
|
||||
By default, the placement application will get its configuration for settings
|
||||
such as the database connection URL from ``/etc/placement/placement.conf``.
|
||||
The directory the configuration file will be found in can be changed by setting
|
||||
``OS_PLACEMENT_CONFIG_DIR`` in the environment of the process that starts the
|
||||
application. With recent releases of ``oslo.config``, configuration options may
|
||||
also be set in the environment_.
|
||||
|
||||
.. note:: When using uwsgi with a front end (e.g., apache2 or nginx) something
|
||||
needs to ensure that the uwsgi process is running. In DevStack this is done
|
||||
with systemd_. This is one of many different ways to manage uwsgi.
|
||||
|
||||
This document refrains from declaring a set of installation instructions for
|
||||
the placement service. This is because a major point of having a WSGI
|
||||
application is to make the deployment as flexible as possible. Because the
|
||||
placement API service is itself stateless (all state is in the database), it is
|
||||
possible to deploy as many servers as desired behind a load balancing solution
|
||||
for robust and simple scaling. If you familiarize yourself with installing
|
||||
generic WSGI applications (using the links in the common scenarios list,
|
||||
above), those techniques will be applicable here.
|
||||
|
||||
.. _apache2: http://httpd.apache.org/
|
||||
.. _mod_wsgi: https://modwsgi.readthedocs.io/
|
||||
.. _mod_proxy_uwsgi: http://uwsgi-docs.readthedocs.io/en/latest/Apache.html
|
||||
.. _nginx: http://nginx.org/
|
||||
.. _uwsgi: http://uwsgi-docs.readthedocs.io/en/latest/Nginx.html
|
||||
.. _gunicorn: http://gunicorn.org/
|
||||
.. _first added to DevStack: https://review.opendev.org/#/c/342362/
|
||||
.. _was updated: https://review.opendev.org/#/c/456717/
|
||||
.. _systemd: https://review.opendev.org/#/c/448323/
|
||||
.. _environment: https://docs.openstack.org/oslo.config/latest/reference/drivers.html#environment
|
||||
|
||||
**2. Synchronize the database**
|
||||
|
||||
The placement service uses its own database, defined in the
|
||||
:oslo.config:group:`placement_database` section of configuration. The
|
||||
:oslo.config:option:`placement_database.connection` option **must** be set or
|
||||
the service will not start. The command line tool :doc:`cli/placement-manage`
|
||||
can be used to migrate the database tables to their correct form, including
|
||||
creating them. The database described by the ``connection`` option must already
|
||||
exist and have appropriate access controls defined.
|
||||
|
||||
Another option for synchronization is to set
|
||||
:oslo.config:option:`placement_database.sync_on_startup` to ``True`` in
|
||||
configuration. This will perform any missing database migrations as the
|
||||
placement web service starts. Whether you choose to sync automaticaly or use
|
||||
the command line tool depends on the constraints of your environment and
|
||||
deployment tooling.
|
||||
|
||||
.. warning:: In the Stein release, the placement code was extracted from nova.
|
||||
If you are upgrading to use the extracted placement you will need
|
||||
to migrate your placement data from the ``nova_api`` database to
|
||||
the ``placement`` database. You can find sample scripts that may
|
||||
help with this in the `placement repository`_:
|
||||
`mysql-migrate-db.sh`_ and `postgresql-migrate-db.sh`_.
|
||||
See also :ref:`placement-upgrade-notes`, below.
|
||||
|
||||
.. note:: Upgrading to the extracted placement at the same time as the other
|
||||
OpenStack services when upgrading to Stein is an option but *is not
|
||||
required*. The nova code will continue to have a copy of the
|
||||
placement service in its Stein release. However this copy **will** be
|
||||
deleted in Train and switching to the extracted version before
|
||||
upgrading to Train (potentially with the help of the scripts above)
|
||||
will be required.
|
||||
|
||||
**3. Create accounts and update the service catalog**
|
||||
|
||||
Create a **placement** service user with an **admin** role in Keystone.
|
||||
|
||||
The placement API is a separate service and thus should be registered under
|
||||
a **placement** service type in the service catalog. Clients of placement, such
|
||||
as the resource tracker in the nova-compute node, will use the service catalog
|
||||
to find the placement endpoint.
|
||||
|
||||
See :ref:`configure-endpoints-pypi` for examples of creating the service user
|
||||
and catalog entries.
|
||||
|
||||
Devstack sets up the placement service on the default HTTP port (80) with a
|
||||
``/placement`` prefix instead of using an independent port.
|
||||
|
||||
.. _placement-upgrade-notes:
|
||||
|
||||
Installation Packages
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This section provides instructions on installing placement from Linux
|
||||
distribution packages.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
install/index
|
||||
|
||||
Upgrade Notes
|
||||
=============
|
||||
|
||||
The following sub-sections provide notes on upgrading to a given target release.
|
||||
|
||||
.. note::
|
||||
|
||||
As a reminder, the
|
||||
:ref:`placement-status upgrade check <placement-status-checks>` tool can be
|
||||
used to help determine the status of your deployment and how ready it is to
|
||||
perform an upgrade.
|
||||
|
||||
For releases prior to Stein, please see the `nova upgrade notes`_.
|
||||
|
||||
.. _nova upgrade notes: https://docs.openstack.org/nova/rocky/user/placement.html#upgrade-notes
|
||||
|
||||
|
||||
Stein (1.0.0)
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
If you are upgrading an existing OpenStack installation from Rocky to Stein,
|
||||
and wish to use the newly extracted placement, you will need to copy some
|
||||
data and configuration settings from nova.
|
||||
|
||||
* Configuration and policy files are, by default, located in
|
||||
``/etc/placement``.
|
||||
* The placement server side settings in ``nova.conf`` should be moved to a
|
||||
separate placement configuration file ``placement.conf``.
|
||||
* The default configuration value of ``[placement]/policy_file`` is changed
|
||||
from ``placement-policy.yaml`` to ``policy.yaml``
|
||||
* Several tables in the ``nova_api`` database need to be migrated to a new
|
||||
``placement`` database.
|
||||
|
||||
Following these steps will ensure that future changes to placement
|
||||
configuration and code will not conflict with your setup.
|
||||
|
||||
As stated above, using the extracted placement code is not required in Stein,
|
||||
there is a copy in the Stein release of Nova. However that code will be deleted
|
||||
in the Train cycle so you must upgrade to external Placement prior to
|
||||
upgrading to Train.
|
||||
|
||||
.. _placement repository: https://opendev.org/openstack/placement
|
||||
.. _mysql-migrate-db.sh: https://opendev.org/openstack/placement/raw/branch/master/tools/mysql-migrate-db.sh
|
||||
.. _postgresql-migrate-db.sh: https://opendev.org/openstack/placement/raw/branch/master/tools/postgresql-migrate-db.sh
|
||||
|
||||
The following subsection provides more details of one way to manage this upgrade.
|
||||
Administrator Guide
|
||||
===================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 2
|
||||
|
||||
upgrade/to-stein
|
||||
|
||||
REST API
|
||||
========
|
||||
|
||||
The placement API service provides a well-documented, JSON-based `HTTP API`_
|
||||
and data model. It is designed to be easy to use from whatever HTTP client is
|
||||
suitable. There is a plugin to the openstackclient_ command line tool called
|
||||
osc-placement_ which is useful for occasional inspection and manipulation of
|
||||
the resources in the placement service.
|
||||
|
||||
.. _HTTP API: https://docs.openstack.org/api-ref/placement/
|
||||
.. _openstackclient: https://pypi.org/project/openstackclient/
|
||||
.. _osc-placement: https://pypi.org/project/osc-placement/
|
||||
|
||||
Microversions
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
The placement API uses microversions for making incremental changes to the
|
||||
API which client requests must opt into.
|
||||
|
||||
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.
|
||||
|
||||
This history of placement microversions may be found in the following
|
||||
subsection.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
placement-api-microversion-history
|
||||
admin/index
|
||||
|
|
|
|||
|
|
@ -1,6 +1,136 @@
|
|||
=================
|
||||
Placement Service
|
||||
=================
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
.. note:: Before the Stein release the placement code was in Nova alongside
|
||||
the compute REST API code (nova-api). Make sure that the release
|
||||
version of this document matches the release version you want to
|
||||
deploy.
|
||||
|
||||
Steps Overview
|
||||
--------------
|
||||
|
||||
This subsection gives an overview of the process without going into detail
|
||||
on the methods used.
|
||||
|
||||
**1. Deploy the API service**
|
||||
|
||||
Placement provides a ``placement-api`` WSGI script for running the service with
|
||||
Apache, nginx or other WSGI-capable web servers. Depending on what packaging
|
||||
solution is used to deploy OpenStack, the WSGI script may be in ``/usr/bin``
|
||||
or ``/usr/local/bin``.
|
||||
|
||||
``placement-api``, as a standard WSGI script, provides a module level
|
||||
``application`` attribute that most WSGI servers expect to find. This means it
|
||||
is possible to run it with lots of different servers, providing flexibility in
|
||||
the face of different deployment scenarios. Common scenarios include:
|
||||
|
||||
* apache2_ with mod_wsgi_
|
||||
* apache2 with mod_proxy_uwsgi_
|
||||
* nginx_ with uwsgi_
|
||||
* nginx with gunicorn_
|
||||
|
||||
In all of these scenarios the host, port and mounting path (or prefix) of the
|
||||
application is controlled in the web server's configuration, not in the
|
||||
configuration (``placement.conf``) of the placement application.
|
||||
|
||||
When placement was `first added to DevStack`_ it used the ``mod_wsgi`` style.
|
||||
Later it `was updated`_ to use mod_proxy_uwsgi_. Looking at those changes can
|
||||
be useful for understanding the relevant options.
|
||||
|
||||
DevStack is configured to host placement at ``/placement`` on either the
|
||||
default port for http or for https (``80`` or ``443``) depending on whether TLS
|
||||
is being used. Using a default port is desirable.
|
||||
|
||||
By default, the placement application will get its configuration for settings
|
||||
such as the database connection URL from ``/etc/placement/placement.conf``.
|
||||
The directory the configuration file will be found in can be changed by setting
|
||||
``OS_PLACEMENT_CONFIG_DIR`` in the environment of the process that starts the
|
||||
application. With recent releases of ``oslo.config``, configuration options may
|
||||
also be set in the environment_.
|
||||
|
||||
.. note:: When using uwsgi with a front end (e.g., apache2 or nginx) something
|
||||
needs to ensure that the uwsgi process is running. In DevStack this is done
|
||||
with systemd_. This is one of many different ways to manage uwsgi.
|
||||
|
||||
This document refrains from declaring a set of installation instructions for
|
||||
the placement service. This is because a major point of having a WSGI
|
||||
application is to make the deployment as flexible as possible. Because the
|
||||
placement API service is itself stateless (all state is in the database), it is
|
||||
possible to deploy as many servers as desired behind a load balancing solution
|
||||
for robust and simple scaling. If you familiarize yourself with installing
|
||||
generic WSGI applications (using the links in the common scenarios list,
|
||||
above), those techniques will be applicable here.
|
||||
|
||||
.. _apache2: http://httpd.apache.org/
|
||||
.. _mod_wsgi: https://modwsgi.readthedocs.io/
|
||||
.. _mod_proxy_uwsgi: http://uwsgi-docs.readthedocs.io/en/latest/Apache.html
|
||||
.. _nginx: http://nginx.org/
|
||||
.. _uwsgi: http://uwsgi-docs.readthedocs.io/en/latest/Nginx.html
|
||||
.. _gunicorn: http://gunicorn.org/
|
||||
.. _first added to DevStack: https://review.opendev.org/#/c/342362/
|
||||
.. _was updated: https://review.opendev.org/#/c/456717/
|
||||
.. _systemd: https://review.opendev.org/#/c/448323/
|
||||
.. _environment: https://docs.openstack.org/oslo.config/latest/reference/drivers.html#environment
|
||||
|
||||
**2. Synchronize the database**
|
||||
|
||||
The placement service uses its own database, defined in the
|
||||
:oslo.config:group:`placement_database` section of configuration. The
|
||||
:oslo.config:option:`placement_database.connection` option **must** be set or
|
||||
the service will not start. The command line tool :doc:`/cli/placement-manage`
|
||||
can be used to migrate the database tables to their correct form, including
|
||||
creating them. The database described by the ``connection`` option must
|
||||
already exist and have appropriate access controls defined.
|
||||
|
||||
Another option for synchronization is to set
|
||||
:oslo.config:option:`placement_database.sync_on_startup` to ``True`` in
|
||||
configuration. This will perform any missing database migrations as the
|
||||
placement web service starts. Whether you choose to sync automaticaly or use
|
||||
the command line tool depends on the constraints of your environment and
|
||||
deployment tooling.
|
||||
|
||||
.. warning:: In the Stein release, the placement code was extracted from nova.
|
||||
If you are upgrading to use the extracted placement you will need
|
||||
to migrate your placement data from the ``nova_api`` database to
|
||||
the ``placement`` database. You can find sample scripts that may
|
||||
help with this in the `placement repository`_:
|
||||
`mysql-migrate-db.sh`_ and `postgresql-migrate-db.sh`_.
|
||||
See also :doc:`/admin/upgrade-notes`.
|
||||
|
||||
.. note:: Upgrading to the extracted placement at the same time as the other
|
||||
OpenStack services when upgrading to Stein is an option but *is not
|
||||
required*. The nova code will continue to have a copy of the
|
||||
placement service in its Stein release. However this copy **will** be
|
||||
deleted in Train and switching to the extracted version before
|
||||
upgrading to Train (potentially with the help of the scripts above)
|
||||
will be required.
|
||||
|
||||
.. _placement repository: https://opendev.org/openstack/placement
|
||||
.. _mysql-migrate-db.sh: https://opendev.org/openstack/placement/raw/branch/master/tools/mysql-migrate-db.sh
|
||||
.. _postgresql-migrate-db.sh: https://opendev.org/openstack/placement/raw/branch/master/tools/postgresql-migrate-db.sh
|
||||
|
||||
**3. Create accounts and update the service catalog**
|
||||
|
||||
Create a **placement** service user with an **admin** role in Keystone.
|
||||
|
||||
The placement API is a separate service and thus should be registered under
|
||||
a **placement** service type in the service catalog. Clients of placement, such
|
||||
as the resource tracker in the nova-compute node, will use the service catalog
|
||||
to find the placement endpoint.
|
||||
|
||||
See :ref:`configure-endpoints-pypi` for examples of creating the service user
|
||||
and catalog entries.
|
||||
|
||||
Devstack sets up the placement service on the default HTTP port (80) with a
|
||||
``/placement`` prefix instead of using an independent port.
|
||||
|
||||
|
||||
Installation Packages
|
||||
---------------------
|
||||
|
||||
This section provides instructions on installing placement from Linux
|
||||
distribution packages.
|
||||
|
||||
.. warning:: These installation documents are a work in progress. Some of the
|
||||
distribution packages mentioned are not yet available so the
|
||||
|
|
|
|||
|
|
@ -15,6 +15,37 @@
|
|||
Placement Specifications
|
||||
=========================
|
||||
|
||||
Significant feature developments are tracked in documents called specifications.
|
||||
From the Train cycle onward, those documents are kept in this section.
|
||||
Prior to that, Placement specifications were a part of the `Nova Specs`_.
|
||||
|
||||
The following specifications represent the stages of design and development of
|
||||
resource providers and the Placement service. Implementation details may have
|
||||
changed or be partially complete at this time.
|
||||
|
||||
* `Generic Resource Pools <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/generic-resource-pools.html>`_
|
||||
* `Compute Node Inventory <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/compute-node-inventory-newton.html>`_
|
||||
* `Resource Provider Allocations <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/resource-providers-allocations.html>`_
|
||||
* `Resource Provider Base Models <https://specs.openstack.org/openstack/nova-specs/specs/newton/implemented/resource-providers.html>`_
|
||||
* `Nested Resource Providers`_
|
||||
* `Custom Resource Classes <http://specs.openstack.org/openstack/nova-specs/specs/ocata/implemented/custom-resource-classes.html>`_
|
||||
* `Scheduler Filters in DB <http://specs.openstack.org/openstack/nova-specs/specs/ocata/implemented/resource-providers-scheduler-db-filters.html>`_
|
||||
* `Scheduler claiming resources to the Placement API <http://specs.openstack.org/openstack/nova-specs/specs/pike/approved/placement-claims.html>`_
|
||||
* `The Traits API - Manage Traits with ResourceProvider <http://specs.openstack.org/openstack/nova-specs/specs/pike/approved/resource-provider-traits.html>`_
|
||||
* `Request Traits During Scheduling`_
|
||||
* `filter allocation candidates by aggregate membership`_
|
||||
* `perform granular allocation candidate requests`_
|
||||
* `inventory and allocation data migration`_ (reshaping provider trees)
|
||||
* `handle allocation updates in a safe way`_
|
||||
|
||||
.. _Nested Resource Providers: http://specs.openstack.org/openstack/nova-specs/specs/queens/approved/nested-resource-providers.html
|
||||
.. _Request Traits During Scheduling: https://specs.openstack.org/openstack/nova-specs/specs/queens/approved/request-traits-in-nova.html
|
||||
.. _filter allocation candidates by aggregate membership: https://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/alloc-candidates-member-of.html
|
||||
.. _perform granular allocation candidate requests: http://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/granular-resource-requests.html
|
||||
.. _inventory and allocation data migration: http://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/reshape-provider-tree.html
|
||||
.. _handle allocation updates in a safe way: https://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/add-consumer-generation.html
|
||||
.. _Nova Specs: http://specs.openstack.org/openstack/nova-specs
|
||||
|
||||
Train
|
||||
-----
|
||||
|
||||
|
|
@ -39,5 +70,4 @@ In Progress
|
|||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
placeholder.rst
|
||||
template.rst
|
||||
|
|
|
|||
|
|
@ -572,7 +572,7 @@ The new query parameters will be documented in the API reference.
|
|||
|
||||
Microversion paperwork will be done.
|
||||
|
||||
:doc:`/usage/provider-tree` will be updated (and/or split off of).
|
||||
:doc:`/user/provider-tree` will be updated (and/or split off of).
|
||||
|
||||
Security impact
|
||||
---------------
|
||||
|
|
|
|||
|
|
@ -67,3 +67,37 @@ portion of the inventory set by the resource tracker.
|
|||
.. _setting the traits: https://docs.openstack.org/api-ref/placement/?expanded=update-resource-provider-traits-detail#update-resource-provider-traits
|
||||
.. _allocation candidates: https://docs.openstack.org/api-ref/placement/?expanded=list-allocation-candidates-detail#list-allocation-candidates
|
||||
.. _allocation: https://docs.openstack.org/api-ref/placement/?expanded=update-allocations-detail#update-allocations
|
||||
|
||||
|
||||
REST API
|
||||
========
|
||||
|
||||
The placement API service provides a well-documented, JSON-based `HTTP API`_
|
||||
and data model. It is designed to be easy to use from whatever HTTP client is
|
||||
suitable. There is a plugin to the openstackclient_ command line tool called
|
||||
osc-placement_ which is useful for occasional inspection and manipulation of
|
||||
the resources in the placement service.
|
||||
|
||||
.. _HTTP API: https://docs.openstack.org/api-ref/placement/
|
||||
.. _openstackclient: https://pypi.org/project/openstackclient/
|
||||
.. _osc-placement: https://pypi.org/project/osc-placement/
|
||||
|
||||
Microversions
|
||||
-------------
|
||||
|
||||
The placement API uses microversions for making incremental changes to the
|
||||
API which client requests must opt into.
|
||||
|
||||
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.
|
||||
|
||||
This history of placement microversions may be found in the following
|
||||
subsection.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
../placement-api-microversion-history
|
||||
|
|
@ -1,3 +1,6 @@
|
|||
/placement/latest/specs/train/approved/2005297-negative-aggregate-membership.html 301 /placement/latest/specs/train/implemented/2005297-negative-aggregate-membership.html
|
||||
/placement/latest/specs/train/approved/placement-resource-provider-request-group-mapping-in-allocation-candidates.html 301 /placement/latest/specs/train/implemented/placement-resource-provider-request-group-mapping-in-allocation-candidates.html
|
||||
/placement/latest/specs/train/approved/2005575-nested-magic-1.html 301 /placement/latest/specs/train/implemented/2005575-nested-magic-1.html
|
||||
/placement/latest/upgrade/to-stein.html 301 /placement/latest/admin/upgrade-to-stein.html
|
||||
/placement/latest/usage/index.html 301 /placement/latest/user/index.html
|
||||
/placement/latest/usage/provider-tree.html 301 /placement/latest/user/provider-tree.html
|
||||
|
|
|
|||
Loading…
Reference in New Issue