Upgrade from rocky-nova docs
This is an attempt at documentation for upgrading to extracted placement from nova. It is effectively a translation, with links, of the script used in grenade. It tries to provide details where it matters, but be vague where independent initiative is warranted. Story: 2005190 Task: 29940 Change-Id: I32b22d75400c7f7b428ed3d48ac928584071ed29
This commit is contained in:
parent
057dc23897
commit
1a620ba216
|
@ -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
|
||||
|
|
|
@ -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
|
||||
--------------------------------
|
||||
|
||||
|
|
|
@ -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
|
||||
</install/index>`.
|
||||
|
||||
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
|
||||
</install/index>`.
|
||||
|
||||
* 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/
|
Loading…
Reference in New Issue