diff --git a/.gitignore b/.gitignore index 5585e99ad..ec5ca7886 100644 --- a/.gitignore +++ b/.gitignore @@ -29,7 +29,6 @@ coverage.xml cover/* covhtml/* dist/* -doc/source/api/* doc/build/* api-guide/build/* api-ref/build/* diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess index 99039ccdc..1befc5f39 100644 --- a/doc/source/_extra/.htaccess +++ b/doc/source/_extra/.htaccess @@ -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 diff --git a/doc/source/specs/placeholder.rst b/doc/source/admin/index.rst similarity index 79% rename from doc/source/specs/placeholder.rst rename to doc/source/admin/index.rst index 8d6992873..5235589fc 100644 --- a/doc/source/specs/placeholder.rst +++ b/doc/source/admin/index.rst @@ -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. diff --git a/doc/source/admin/upgrade-notes.rst b/doc/source/admin/upgrade-notes.rst new file mode 100644 index 000000000..258ffccc8 --- /dev/null +++ b/doc/source/admin/upgrade-notes.rst @@ -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 ` 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. diff --git a/doc/source/upgrade/to-stein.rst b/doc/source/admin/upgrade-to-stein.rst similarity index 100% rename from doc/source/upgrade/to-stein.rst rename to doc/source/admin/upgrade-to-stein.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 08f92c1b2..4db93e731 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 `_ -* `Compute Node Inventory `_ -* `Resource Provider Allocations `_ -* `Resource Provider Base Models `_ -* `Nested Resource Providers`_ -* `Custom Resource Classes `_ -* `Scheduler Filters in DB `_ -* `Scheduler claiming resources to the Placement API `_ -* `The Traits API - Manage Traits with ResourceProvider `_ -* `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 ` 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 diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index a59a76b2b..c6db730e8 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -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 diff --git a/doc/source/specs/index.rst b/doc/source/specs/index.rst index c94a47bbf..a5a6376b6 100644 --- a/doc/source/specs/index.rst +++ b/doc/source/specs/index.rst @@ -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 `_ +* `Compute Node Inventory `_ +* `Resource Provider Allocations `_ +* `Resource Provider Base Models `_ +* `Nested Resource Providers`_ +* `Custom Resource Classes `_ +* `Scheduler Filters in DB `_ +* `Scheduler claiming resources to the Placement API `_ +* `The Traits API - Manage Traits with ResourceProvider `_ +* `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 diff --git a/doc/source/specs/train/implemented/2005575-nested-magic-1.rst b/doc/source/specs/train/implemented/2005575-nested-magic-1.rst index f5102fcc3..2cf75d929 100644 --- a/doc/source/specs/train/implemented/2005575-nested-magic-1.rst +++ b/doc/source/specs/train/implemented/2005575-nested-magic-1.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 --------------- diff --git a/doc/source/usage/index.rst b/doc/source/user/index.rst similarity index 74% rename from doc/source/usage/index.rst rename to doc/source/user/index.rst index 34f0dcbbf..feac9390d 100644 --- a/doc/source/usage/index.rst +++ b/doc/source/user/index.rst @@ -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 diff --git a/doc/source/usage/provider-tree.rst b/doc/source/user/provider-tree.rst similarity index 100% rename from doc/source/usage/provider-tree.rst rename to doc/source/user/provider-tree.rst diff --git a/doc/test/redirect-tests.txt b/doc/test/redirect-tests.txt index 8c0b3f6a8..ba3d4e58d 100644 --- a/doc/test/redirect-tests.txt +++ b/doc/test/redirect-tests.txt @@ -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