diff --git a/doc/source/index.rst b/doc/source/index.rst index 19ccc1f6d..f5076c74a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -19,7 +19,7 @@ Overview ======== 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 +the nova repository and extracted to the `placement repository`_ in the 19.0.0 Stein release. This is a REST API stack and data model used to track resource provider inventories and usages, along with different classes of resources. For example, a resource provider can be a compute node, a shared storage pool, @@ -181,6 +181,7 @@ deployment tooling. 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 @@ -221,16 +222,30 @@ 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 (19.0.0) +Stein (1.0.0) ~~~~~~~~~~~~~~ -* The placement code is now available from its own `placement repository`_. +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. See :doc:`upgrade/to-stein` for +details of one way to manage this. The overview is: + +* 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`` -* Configuration and policy files are, by default, located in - ``/etc/placement``. +* 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://git.openstack.org/cgit/openstack/placement .. _mysql-migrate-db.sh: https://git.openstack.org/cgit/openstack/placement/plain/tools/mysql-migrate-db.sh @@ -283,4 +298,5 @@ This history of placement microversions may be found in install/install-ubuntu install/verify placement-api-microversion-history + upgrade/to-stein usage/index diff --git a/doc/source/install/from-pypi.rst b/doc/source/install/from-pypi.rst index a6f157a3e..e82f914e7 100644 --- a/doc/source/install/from-pypi.rst +++ b/doc/source/install/from-pypi.rst @@ -30,6 +30,8 @@ If not already installed, install the ``openstack`` command line tool: Before installing the service, you will need to create the database, service credentials, and API endpoints, as described in the following sections. +.. _create-database-pypi: + Create Database ^^^^^^^^^^^^^^^ @@ -91,6 +93,8 @@ Configure User and Endpoints .. include:: shared/endpoints.rst +.. _configure-conf-pypi: + Install and configure components -------------------------------- diff --git a/doc/source/upgrade/to-stein.rst b/doc/source/upgrade/to-stein.rst new file mode 100644 index 000000000..4132b3af9 --- /dev/null +++ b/doc/source/upgrade/to-stein.rst @@ -0,0 +1,172 @@ +.. + 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. + +================================ +Upgrading from Nova to Placement +================================ + +This document is for people who are upgrading from an existing Rocky-based +installation of OpenStack, where Placement is a part of Nova, to a Stein-based +system, using the independently packaged placement service. + +Doing so is not a requirement. There is a version of the placement service in +the nova Stein release. It will be removed in Train. The version in nova is +behind the extracted version in terms of features and performance fixes. + +If you are installing a new OpenStack, you'll want the :doc:`installation docs +`. + +Upgrading to use the extracted placement service requires migrating several +database tables from the ``nova_api`` database to a placement database. +Depending on the number of compute hosts in your system and the number of +active virtual machines, the amount of data to copy can vary widely. You can +get an idea by counting rows in the ``resource_providers`` and ``allocations`` +tables. + +To avoid losing data while performing the copy it is important that writing to +the placement database (on either side of the upgrade) is stopped. You may shut +down solely the placement service but this will result in errors attempting to +use the service from ``nova-scheduler`` and ``nova-compute``. It is potentially +less disruptive to shut down the entire control plane to avoid confusing +errors. What strategy is best will vary. This document describes the simple +way. + +.. note:: In some installations of nova and placement, data will already be in + a database named ``placement`` and not ``nova_api``. If that's the + case, you will not need to copy data. Make sure that there is data in + that database and that it is correct. In some cases the database will + be present *but not used*. + +There are database migrations scripts in the placement code repository which +may be used to copy the data or as models for your own tooling: +`mysql-migrate-db.sh`_ and `postgresql-migrate-db.sh`_. + +For best results run the database migration on your database host. If you are +unable to do this, you'll need to take some additional steps below. + +This document assumes that the same HTTP endpoint will be used before and after +the upgrade. If you need to change that see :ref:`configure-endpoints-pypi` for +guidance. + +Initial Steps +------------- + +#. Install the new placement code on a controller node. This can be + `openstack-placement`_ from PyPI or you can use packages from a Linux + distribution. If you are using the latter be aware that: + + * The name of the package can be found in the :doc:`installation docs + `. + + * You need to install the packages on a different host from the old nova, + to avoid accidentally upgrading before you are ready. + +#. Create a ``placement`` database with appropriate access controls. If you + need details on how to do this, see :ref:`create-database-pypi`. + +#. Create and configure the ``placement.conf`` file. + + * The default location is ``/etc/placement``. + + * Set :oslo.config:option:`placement_database.connection` to point to the + new database. For example (replacing ``PLACEMENT_DBPASS`` and + ``controller`` with the appropriate password and host): + + .. path /etc/placement/placement.conf + .. code-block:: ini + + [placement_database] + connection = mysql+pymysql://placement:PLACEMENT_DBPASS@controller/placement + + * Configure the :oslo.config:group:`keystone_authtoken` section as described + in :ref:`configure-conf-pypi`. + + * If the following configuration settings are set in the ``[placement]`` + section of ``/etc/nova/nova.conf``, copy them to a ``[placement]`` + section in ``/etc/placement/placement.conf``: + + * :oslo.config:option:`placement.randomize_allocation_candidates` + * :oslo.config:option:`placement.incomplete_consumer_project_id` + * :oslo.config:option:`placement.incomplete_consumer_user_id` + +#. Copy ``placement-policy.yaml``, if required. + + * If it exists, copy ``/etc/nova/placement-policy.yaml`` to + ``/etc/placement/policy.yaml``. If you wish to use a different filename + adjust :oslo.config:option:`placement.policy_file`. + +#. Configure the database migration tool. + + * Create the configuration file. + + .. code-block:: console + + $ mysql-migrate-db.sh --mkconfig /tmp/migrate-db.rc + + * Edit the file to set the values for the ``NOVA_API_USER``, + ``NOVA_API_PASS``, ``PLACEMENT_USER``, and ``PLACEMENT_PASS`` entries. + These are the usernames and passwords for accessing the database. + + * If you are unable to run the migration script on the database host you + will need to set ``NOVA_API_DB_HOST`` and ``PLACEMENT_DB_HOST``. + + * Do not change ``MIGRATE_TABLES`` unless you need to migrate tables + incrementally. + +#. Configure the web server that will host the placement service. The details + of this are beyond the scope of this document. :doc:`/install/from-pypi` + may provide some guidance. + +Migrate the Data +---------------- + +#. Shut down or disable your control plane in whatever way works best for you. + +#. Run the migration script: + + .. code-block:: console + + $ mysql-migrate-db.sh --migrate /tmp/migrate-db.rc + + If your controller host (the one where you have been editing + ``/etc/placement/placement.conf``) and database host are not the same, and + you've run the migration script on the database host, the final step in the + process will fail. This step stamps the database with an initial version + (the hash of the first alembic_ migration) so that future migrations will + work properly. From the controller host, you may do it manually with: + + .. code-block:: console + + $ placement-manage db stamp b4ed3a175331 + +#. Sync the placement database to be up to date with all migrations: + + .. code-block:: console + + $ placement-manage db sync + +Finalize the Upgrade +-------------------- + +#. Start up the new placement service. + +#. Restart your control plane and continue with the upgrade of the rest of the + system. + +#. At some point in the future you may remove the tables in the ``nova_api`` + database that were migrated to the ``placement`` database. + +.. _openstack-placement: https://pypi.org/p/openstack-placement +.. _mysql-migrate-db.sh: https://git.openstack.org/cgit/openstack/placement/plain/tools/mysql-migrate-db.sh +.. _postgresql-migrate-db.sh: https://git.openstack.org/cgit/openstack/placement/plain/tools/postgresql-migrate-db.sh +.. _alembic: https://alembic.sqlalchemy.org/en/latest/