DOCS: Clean up of the Mitaka upgrade guide
Forming to conventions applied in the install guide. This cleans up RST, spelling, and grammar fixes. Change-Id: Ieeb678bffc2b59a29e05528cc3d908b036e6c1a8
This commit is contained in:
Alexandra
Alexandra Settle
parent
39edcac67d
commit
29ec1bad24
@ -1,7 +1,8 @@
|
||||
Upgrade Documentation
|
||||
=====================
|
||||
|
||||
In this section you will find information on the Liberty to Mitaka upgrade process.
|
||||
In this section you can find information on the Liberty to
|
||||
Mitaka upgrade process.
|
||||
|
||||
Contents:
|
||||
|
||||
|
||||
@ -6,8 +6,8 @@ Manual Upgrade Steps
|
||||
The steps detailed here match those performed by the ``run-upgrade.sh``
|
||||
script. Any of these steps can safely be run multiple times.
|
||||
|
||||
Checkout Mitaka version
|
||||
-----------------------
|
||||
Check out the Mitaka release
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Ensure your OpenStack-Ansible code is on the latest Mitaka release tag (13.x.x).
|
||||
|
||||
@ -18,14 +18,14 @@ Ensure your OpenStack-Ansible code is on the latest Mitaka release tag (13.x.x).
|
||||
# git checkout ${LATEST_TAG}
|
||||
|
||||
Preparing the shell variables
|
||||
-----------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. note::
|
||||
|
||||
This step is optional, since these environment variables are simply
|
||||
shortcuts. Files can be referenced directly.
|
||||
|
||||
From the ``openstack-ansible`` root directory, run the following.
|
||||
From the ``openstack-ansible`` root directory, run the following commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -33,13 +33,13 @@ From the ``openstack-ansible`` root directory, run the following.
|
||||
# export SCRIPTS_PATH="${MAIN_PATH}/scripts"
|
||||
# export UPGRADE_PLAYBOOKS="${SCRIPTS_PATH}/upgrade-utilities/playbooks"
|
||||
|
||||
These variables will reduce typing when running the remaining upgrade
|
||||
These variables reduce typing when running the remaining upgrade
|
||||
tasks.
|
||||
|
||||
Re-bootstrap Ansible for Mitaka
|
||||
-------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Bootstrapping Ansible again ensures that new external Ansible role
|
||||
Bootstrapping Ansible again ensures that all OpenStack-Ansible role
|
||||
dependencies are in place before running playbooks from the Mitaka
|
||||
release.
|
||||
|
||||
@ -48,21 +48,21 @@ release.
|
||||
# ${SCRIPTS_PATH}/bootstrap-ansible.sh
|
||||
|
||||
Change to playbooks directory
|
||||
-----------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Change to the playbooks directory so that the Ansible dynamic
|
||||
inventory will be found automatically.
|
||||
Change to the playbooks directory so that the OpenStack-Ansible dynamic
|
||||
inventory is found automatically.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# cd playbooks
|
||||
|
||||
Update configuration and environment files
|
||||
------------------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The user configuration files in ``/etc/openstack_deploy/`` and the environment
|
||||
layout in ``/etc/openstack_deploy/env.d`` have had names changed and new
|
||||
values added in Mitaka. This step updates the files as necessary.
|
||||
layout in ``/etc/openstack_deploy/env.d`` have new name
|
||||
values added in Mitaka.
|
||||
|
||||
See :ref:`config-change-playbook` for more details.
|
||||
|
||||
@ -70,13 +70,8 @@ See :ref:`config-change-playbook` for more details.
|
||||
|
||||
# openstack-ansible "${UPGRADE_PLAYBOOKS}/deploy-config-changes.yml"
|
||||
|
||||
.. note::
|
||||
|
||||
The `-e pip_install_options=--force-reinstall` ensures that all pip
|
||||
packages are reinstalled and running the correct version on hosts.
|
||||
|
||||
Update user secrets file
|
||||
------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Mitaka introduces new user secrets to the stack. These are populated
|
||||
automatically with the following playbook.
|
||||
@ -88,7 +83,7 @@ See :ref:`user-secrets-playbook` for more details.
|
||||
# openstack-ansible "${UPGRADE_PLAYBOOKS}/user-secrets-adjustment.yml"
|
||||
|
||||
Upgrade hosts
|
||||
-------------
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Before installing the infrastructure and OpenStack, update the host machines.
|
||||
|
||||
@ -98,12 +93,12 @@ Before installing the infrastructure and OpenStack, update the host machines.
|
||||
|
||||
This command is the same as doing host setups on a new install. The first
|
||||
member of the ``galera_all`` host group is excluded to prevent simultaneous
|
||||
restarts of all galera containers.
|
||||
restarts of all Galera containers.
|
||||
|
||||
Update Galera LXC container configuration
|
||||
-----------------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Update the first galera container's configuration independently.
|
||||
Update the first Galera container's configuration independently.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -111,15 +106,15 @@ Update the first galera container's configuration independently.
|
||||
|
||||
This command is a subset of the host setup playbook, limited to the first
|
||||
member of the ``galera_all`` host group so that its container is restarted only
|
||||
after other galera containers have been restarted in the previous step.
|
||||
after other Galera containers have been restarted in the previous step.
|
||||
|
||||
Cleanup ``pip.conf`` file in the ``repo_servers``
|
||||
-------------------------------------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
It is possible that a ``pip.conf`` file may exist within the repository server
|
||||
infrastructure. If this file exists, it will cause build failures when upgrading
|
||||
to Mitaka. This play will remove the ``pip.conf`` file from the repository
|
||||
servers if it is found.
|
||||
If a ``pip.conf`` file exists within the repository server
|
||||
infrastructure, it can cause build failures when upgrading
|
||||
to Mitaka. This play removes the ``pip.conf`` file from the repository
|
||||
servers.
|
||||
|
||||
See :ref:`repo-server-pip-conf-removal` for more details.
|
||||
|
||||
@ -129,14 +124,13 @@ See :ref:`repo-server-pip-conf-removal` for more details.
|
||||
|
||||
|
||||
Upgrade infrastructure
|
||||
----------------------
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Running the standard OpenStack-Ansible infrastructure playbook applies the
|
||||
relevant Mitaka settings and packages. This upgrade is required for the Mitaka
|
||||
release of OpenStack-Ansible.
|
||||
|
||||
RabbitMQ may need a minor version upgrade depending on what version of Liberty
|
||||
was previously installed.
|
||||
For certain versions of Liberty, you must upgrade the RabbitMQ service.
|
||||
|
||||
See :ref:`setup-infra-playbook` for details.
|
||||
|
||||
@ -146,10 +140,10 @@ See :ref:`setup-infra-playbook` for details.
|
||||
-e 'rabbitmq_upgrade=true'
|
||||
|
||||
Upgrade OpenStack
|
||||
-----------------
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
Upgrading the OpenStack components is done with the same playbook that
|
||||
installs them, without any additional options.
|
||||
Upgrade the OpenStack components with the same installation playbook,
|
||||
without any additional options.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
||||
@ -6,10 +6,10 @@ to upgrade an environment from Liberty to Mitaka. The ``run-upgrade.sh``
|
||||
script runs each upgrade playbook in the correct order, or playbooks
|
||||
can be run individually if necessary.
|
||||
|
||||
Running the Upgrade script
|
||||
Running the upgrade script
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The Mitaka series releases of OpenStack-Ansible contain the code for
|
||||
The Mitaka release series of OpenStack-Ansible contain the code for
|
||||
migrating from Liberty to Mitaka.
|
||||
|
||||
.. warning::
|
||||
@ -26,7 +26,7 @@ following steps in the ``openstack-ansible`` directory:
|
||||
# git checkout ${LATEST_TAG}
|
||||
# ./scripts/run-upgrade.sh
|
||||
|
||||
Upgrading Manually
|
||||
Upgrading manually
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Deployers can run the upgrade steps manually. See :ref:`manual-upgrade`.
|
||||
@ -35,29 +35,29 @@ Manual execution is useful for scoping the changes in the upgrade process
|
||||
inclusion into other orchestration for upgrade automation beyond what
|
||||
OpenStack-Ansible provides.
|
||||
|
||||
Upgrade Actions
|
||||
Upgrade actions
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Both the upgrade script and manual upgrade steps perform the actions and
|
||||
use the concepts introduced below.
|
||||
|
||||
Configuration Changes
|
||||
Configuration changes
|
||||
---------------------
|
||||
|
||||
The upgrade process will modify files residing in ``/etc/openstack_deploy`` in
|
||||
The upgrade process modifies files residing in ``/etc/openstack_deploy`` in
|
||||
order to reflect new Mitaka values.
|
||||
|
||||
Flag Files
|
||||
Flag files
|
||||
----------
|
||||
|
||||
Some flag files are created by the migration scripts in order to achieve
|
||||
idempotency. These files are placed in the ``/etc/openstack_deploy.MITAKA``
|
||||
directory.
|
||||
|
||||
RabbitMQ Upgrade
|
||||
RabbitMQ upgrade
|
||||
----------------
|
||||
|
||||
The RabbitMQ server can be upgraded during an OpenStack-Ansible upgrade.
|
||||
Upgrade the RabbitMQ server during an OpenStack-Ansible upgrade.
|
||||
|
||||
See :ref:`setup-infra-playbook` for details.
|
||||
|
||||
|
||||
@ -7,8 +7,8 @@ Within the main :file:`scripts` directory there is a :file:`upgrade-utilities`
|
||||
directory, which contains additional scripts that facilitate the initial
|
||||
upgrade process.
|
||||
|
||||
run-upgrade.sh
|
||||
--------------
|
||||
``run-upgrade.sh``
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This script controls the overall upgrade process for deployers choosing not to
|
||||
do so manually.
|
||||
@ -19,35 +19,34 @@ It provides the following environment variables:
|
||||
* ``MAIN_PATH`` - openstack_ansible root directory.
|
||||
* ``UPGRADE_PLAYBOOKS`` - path to the playbooks used in upgrading
|
||||
|
||||
The upgrade script will also bootstrap ansible (using
|
||||
The upgrade script also bootstraps OpenStack-Ansible (using
|
||||
``bootstrap-ansible.sh``) in order to provide the new role dependencies
|
||||
introduced in the Liberty series.
|
||||
|
||||
.. _migrate-os-vars:
|
||||
|
||||
migrate_openstack_vars.py
|
||||
-------------------------
|
||||
``migrate_openstack_vars.py``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In Liberty, some variable names were changed to reflect upstream decisions.
|
||||
This script will look for and replace any instances of these strings in the
|
||||
Upstream decisions influenced the change of some variable names in Liberty.
|
||||
This script replaces any instances of these strings in the
|
||||
variable override files matching the pattern
|
||||
``/etc/openstack_deploy/user_*.yml``.
|
||||
Comments in the file will be preserved, though the variable names within the
|
||||
comments will be updated.
|
||||
Variable names within comments are updated.
|
||||
|
||||
This script will also create files of the form
|
||||
This script creates files of the form
|
||||
``/etc/openstack_deploy.MITAKA/VARS_MIGRATED_file``. For example, once the script has
|
||||
processed the file ``/etc/openstack_deploy/user_variables.yml``. it creates
|
||||
``/etc/openstack_deploy.MITAKA/VARS_MIGRATED_user_variables`` to indicate to
|
||||
ansible that the step can be skipped on successive runs. The script itself does
|
||||
processed the file ``/etc/openstack_deploy/user_variables.yml``, it creates
|
||||
``/etc/openstack_deploy.MITAKA/VARS_MIGRATED_user_variables``. This indicates to
|
||||
OpenStack-Ansible to skip this step on successive runs. The script itself does
|
||||
not check for this file.
|
||||
|
||||
The variable changes are shown in the following table.
|
||||
|
||||
.. This table was made with the output of
|
||||
scripts/upgrade-utilities/scripts/make_rst_table.py. Insertion needs to be
|
||||
``scripts/upgrade-utilities/scripts/make_rst_table.py``. Insertion needs to be
|
||||
done manually since the OpenStack publish jobs do not use `make` and there
|
||||
isn't yet a sphinx extension that runs an abitrary script on build.
|
||||
is not yet a Sphinx extension that runs an abitrary script on build.
|
||||
|
||||
+------------------------------------------+------------------------------------------+
|
||||
| Old Value | New Value |
|
||||
|
||||
@ -10,46 +10,44 @@ facilitate the upgrade process.
|
||||
|
||||
.. _config-change-playbook:
|
||||
|
||||
deploy-config-changes.yml
|
||||
-------------------------
|
||||
``deploy-config-changes.yml``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This playbook will back up the ``/etc/openstack_deploy`` directory before
|
||||
making the necessary changes to the configuration.
|
||||
This playbook backs up the ``/etc/openstack_deploy`` directory before
|
||||
changing the configuration.
|
||||
|
||||
``/etc/openstack_deploy`` is copied once to ``/etc/openstack_deploy.MITAKA``.
|
||||
The copy happens only once, so repeated runs are safe.
|
||||
``/etc/openstack_deploy`` copies once to ``/etc/openstack_deploy.MITAKA``.
|
||||
|
||||
.. _user-secrets-playbook:
|
||||
|
||||
user-secrets-adjustment.yml
|
||||
---------------------------
|
||||
``user-secrets-adjustment.yml``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This playbook ensures that the user secrets file is updated based on the example
|
||||
file in the main repository. This makes it possible to guarantee all secrets are
|
||||
carried into the upgraded environment and appropriately generated. Only new
|
||||
secrets are added, such as those necessary for new services or new settings
|
||||
added to existing services. Previously set values will not be changed.
|
||||
file in the main repository, making it possible to guarantee all secrets move
|
||||
into the upgraded environment and generate appropriately.
|
||||
This adds only new secrets, such as those necessary for new services or new settings
|
||||
added to existing services. Values set previously are not changed.
|
||||
|
||||
.. _setup-infra-playbook:
|
||||
|
||||
repo-server-pip-conf-removal.yml
|
||||
--------------------------------
|
||||
``repo-server-pip-conf-removal.yml``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
This playbook ensures the repository servers do not have the ``pip.conf`` in the
|
||||
root ``pip`` directory locking down the python packages available to install. If
|
||||
this file exists on the repository servers it will cause build failures.
|
||||
The presence of ``pip.conf`` locks down all Python installations to packages on the
|
||||
repo server. If ``pip.conf`` exists on the repo server, it creates a circular
|
||||
dependency, causing build failures.
|
||||
|
||||
.. _repo-server-pip-conf-removal:
|
||||
|
||||
setup-infrastructure.yml
|
||||
------------------------
|
||||
``setup-infrastructure.yml``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The ``setup-infrastructure.yml`` playbook is contained in the main
|
||||
``playbooks`` directory, but is called by ``run-upgrade.sh`` with specific
|
||||
arguments in order to upgrade infrastructure components such as MariaDB and
|
||||
RabbitMQ.
|
||||
The ``playbooks`` directory contains the ``setup-infrastructure.yml`` playbook.
|
||||
The ``run-upgrade.sh`` script calls ``setup-insfrastructure.yml`` with specific
|
||||
arguments to upgrade MariaDB and RabbitMQ.
|
||||
|
||||
For example, to run an upgrade for both components at once, run the following:
|
||||
For example, to run an upgrade for both components at once, run the following commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
@ -57,20 +55,20 @@ For example, to run an upgrade for both components at once, run the following:
|
||||
# -e 'galera_upgrade=true'
|
||||
|
||||
The ``rabbitmq_upgrade`` variable tells the ``rabbitmq_server`` role to
|
||||
upgrade the running major/minor version of RabbitMQ.
|
||||
upgrade RabbitMQ.
|
||||
|
||||
.. note::
|
||||
The RabbitMQ server role will install patch releases automatically,
|
||||
The RabbitMQ server role installs patch releases automatically,
|
||||
regardless of the value of ``rabbitmq_upgrade``. This variable only
|
||||
controls upgrading the major or minor version.
|
||||
controls upgrading the major or minor versions.
|
||||
|
||||
Upgrading RabbitMQ in the Mitaka release is optional. The
|
||||
``run-upgrade.sh`` script will not automatically upgrade it. If a RabbitMQ
|
||||
upgrade using the script is desired, insert the ``rabbitmq_upgrade: true``
|
||||
line into a file such as ``/etc/openstack_deploy/user_variables.yml``.
|
||||
``run-upgrade.sh`` script does not automatically upgrade it. To upgrade RabbitMQ,
|
||||
insert the ``rabbitmq_upgrade: true``
|
||||
line into a file, such as: ``/etc/openstack_deploy/user_variables.yml``.
|
||||
|
||||
The ``galera_upgrade`` variable tells the ``galera_server`` role to remove the
|
||||
current version of MariaDB/Galera and upgrade to the 10.x series.
|
||||
current version of MariaDB and Galera and upgrade to the 10.x series.
|
||||
|
||||
.. _setup-infra-playbook:
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user