openstack/openstack-ansible
Code Issues Proposed changes

Merge "DOCS: Clean up of the Newton upgrade guide"

Browse Source
This commit is contained in:
Jenkins 2016-05-31 19:28:34 +00:00 committed by Gerrit Code Review
commit cc11d798b1
5 changed files with 83 additions and 91 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/source/upgrade-guide/index.rst
View File

@ -1,7 +1,8 @@
Upgrade Documentation Upgrade Documentation
===================== =====================
In this section you will find information on the Mitaka to Newton upgrade process. In this section you can find information on the Mitaka to
Newton upgrade process.
Contents: Contents:

64
doc/source/upgrade-guide/manual-upgrade.rst
View File

@ -6,8 +6,8 @@ Manual Upgrade Steps
The steps detailed here match those performed by the ``run-upgrade.sh`` The steps detailed here match those performed by the ``run-upgrade.sh``
script. Any of these steps can safely be run multiple times. script. Any of these steps can safely be run multiple times.
Checkout Newton version Check out the Newton release
----------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Ensure your OpenStack-Ansible code is on the latest Newton release tag (14.x.x). Ensure your OpenStack-Ansible code is on the latest Newton release tag (14.x.x).
@ -18,14 +18,14 @@ Ensure your OpenStack-Ansible code is on the latest Newton release tag (14.x.x).
# git checkout ${LATEST_TAG} # git checkout ${LATEST_TAG}
Preparing the shell variables Preparing the shell variables
----------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. note:: .. note::
This step is optional, since these environment variables are simply This step is optional, since these environment variables are simply
shortcuts. Files can be referenced directly. 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 .. code-block:: console
@ -33,13 +33,13 @@ From the ``openstack-ansible`` root directory, run the following.
# export SCRIPTS_PATH="${MAIN_PATH}/scripts" # export SCRIPTS_PATH="${MAIN_PATH}/scripts"
# export UPGRADE_PLAYBOOKS="${SCRIPTS_PATH}/upgrade-utilities/playbooks" # 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. tasks.
Re-bootstrap Ansible for Newton Re-bootstrap Ansible for Newton
------------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 Newton dependencies are in place before running playbooks from the Newton
release. release.
@ -48,21 +48,21 @@ release.
# ${SCRIPTS_PATH}/bootstrap-ansible.sh # ${SCRIPTS_PATH}/bootstrap-ansible.sh
Change to playbooks directory Change to playbooks directory
----------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Change to the playbooks directory so that the Ansible dynamic Change to the playbooks directory so that the OpenStack-Ansible dynamic
inventory will be found automatically. inventory is found automatically.
.. code-block:: console .. code-block:: console
# cd playbooks # cd playbooks
Update configuration and environment files Update configuration and environment files
------------------------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The user configuration files in ``/etc/openstack_deploy/`` and the environment The user configuration files in ``/etc/openstack_deploy/`` and the environment
layout in ``/etc/openstack_deploy/env.d`` have had names changed and new layout in ``/etc/openstack_deploy/env.d`` have new name
values added in Newton. This step updates the files as necessary. values added in Newton.
See :ref:`config-change-playbook` for more details. 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" # 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 Update user secrets file
------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~
Newton introduces new user secrets to the stack. These are populated Newton introduces new user secrets to the stack. These are populated
automatically with the following playbook. 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" # openstack-ansible "${UPGRADE_PLAYBOOKS}/user-secrets-adjustment.yml"
Upgrade hosts Upgrade hosts
------------- ~~~~~~~~~~~~~
Before installing the infrastructure and OpenStack, update the host machines. 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 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 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 Galera LXC container configuration
----------------------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Update the first galera container's configuration independently. Update the first Galera container's configuration independently.
.. code-block:: console .. 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 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 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`` Cleanup ``pip.conf`` file in the ``repo_servers``
------------------------------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is possible that a ``pip.conf`` file may exist within the repository server If a ``pip.conf`` file exists within the repository server
infrastructure. If this file exists, it will cause build failures when upgrading infrastructure, it can cause build failures when upgrading
to Newton. This play will remove the ``pip.conf`` file from the repository to Newton. This play removes the ``pip.conf`` file from the repository
servers if it is found. servers.
See :ref:`repo-server-pip-conf-removal` for more details. 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 Upgrade infrastructure
---------------------- ~~~~~~~~~~~~~~~~~~~~~~
Running the standard OpenStack-Ansible infrastructure playbook applies the Running the standard OpenStack-Ansible infrastructure playbook applies the
relevant Newton settings and packages. This upgrade is required for the Newton relevant Newton settings and packages. This upgrade is required for the Newton
release of OpenStack-Ansible. release of OpenStack-Ansible.
RabbitMQ may need a minor version upgrade depending on what version of Mitaka For certain versions of Mitaka, you must upgrade the RabbitMQ service.
was previously installed.
See :ref:`setup-infra-playbook` for details. See :ref:`setup-infra-playbook` for details.
@ -146,10 +140,10 @@ See :ref:`setup-infra-playbook` for details.
-e 'rabbitmq_upgrade=true' -e 'rabbitmq_upgrade=true'
Upgrade OpenStack Upgrade OpenStack
----------------- ~~~~~~~~~~~~~~~~~
Upgrading the OpenStack components is done with the same playbook that Upgrade the OpenStack components with the same installation playbook,
installs them, without any additional options. without any additional options.
.. code-block:: console .. code-block:: console

18
doc/source/upgrade-guide/overview.rst
View File

@ -6,10 +6,10 @@ to upgrade an environment from Mitaka to Newton. The ``run-upgrade.sh``
script runs each upgrade playbook in the correct order, or playbooks script runs each upgrade playbook in the correct order, or playbooks
can be run individually if necessary. can be run individually if necessary.
Running the Upgrade script Running the upgrade script
~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~
The Newton series releases of OpenStack-Ansible contain the code for The Newton release series of OpenStack-Ansible contain the code for
migrating from Mitaka to Newton. migrating from Mitaka to Newton.
.. warning:: .. warning::
@ -26,7 +26,7 @@ following steps in the ``openstack-ansible`` directory:
# git checkout ${LATEST_TAG} # git checkout ${LATEST_TAG}
# ./scripts/run-upgrade.sh # ./scripts/run-upgrade.sh
Upgrading Manually Upgrading manually
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
Deployers can run the upgrade steps manually. See :ref:`manual-upgrade`. 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 inclusion into other orchestration for upgrade automation beyond what
OpenStack-Ansible provides. OpenStack-Ansible provides.
Upgrade Actions Upgrade actions
~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~
Both the upgrade script and manual upgrade steps perform the actions and Both the upgrade script and manual upgrade steps perform the actions and
use the concepts introduced below. 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 Newton values. order to reflect new Newton values.
Flag Files Flag files
---------- ----------
Some flag files are created by the migration scripts in order to achieve Some flag files are created by the migration scripts in order to achieve
idempotency. These files are placed in the ``/etc/openstack_deploy.NEWTON`` idempotency. These files are placed in the ``/etc/openstack_deploy.NEWTON``
directory. 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. See :ref:`setup-infra-playbook` for details.

29
doc/source/upgrade-guide/scripts.rst
View File

@ -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 directory, which contains additional scripts that facilitate the initial
upgrade process. upgrade process.
run-upgrade.sh ``run-upgrade.sh``
-------------- ~~~~~~~~~~~~~~~~~~
This script controls the overall upgrade process for deployers choosing not to This script controls the overall upgrade process for deployers choosing not to
do so manually. do so manually.
@ -19,35 +19,34 @@ It provides the following environment variables:
* ``MAIN_PATH`` - openstack_ansible root directory. * ``MAIN_PATH`` - openstack_ansible root directory.
* ``UPGRADE_PLAYBOOKS`` - path to the playbooks used in upgrading * ``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 ``bootstrap-ansible.sh``) in order to provide the new role dependencies
introduced in the Mitaka series. introduced in the Mitaka series.
.. _migrate-os-vars: .. _migrate-os-vars:
migrate_openstack_vars.py ``migrate_openstack_vars.py``
------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In Mitaka, some variable names were changed to reflect upstream decisions. Upstream decisions influenced the change of some variable names in Newton.
This script will look for and replace any instances of these strings in the This script replaces any instances of these strings in the
variable override files matching the pattern variable override files matching the pattern
``/etc/openstack_deploy/user_*.yml``. ``/etc/openstack_deploy/user_*.yml``.
Comments in the file will be preserved, though the variable names within the Variable names within comments are updated.
comments will be updated.
This script will also create files of the form This script creates files of the form
``/etc/openstack_deploy.NEWTON/VARS_MIGRATED_file``. For example, once the script has ``/etc/openstack_deploy.NEWTON/VARS_MIGRATED_file``. For example, once the script has
processed the file ``/etc/openstack_deploy/user_variables.yml``. it creates processed the file ``/etc/openstack_deploy/user_variables.yml``, it creates
``/etc/openstack_deploy.NEWTON/VARS_MIGRATED_user_variables`` to indicate to ``/etc/openstack_deploy.NEWTON/VARS_MIGRATED_user_variables``. This indicates to
ansible that the step can be skipped on successive runs. The script itself does OpenStack-Ansible to skip this step on successive runs. The script itself does
not check for this file. not check for this file.
The variable changes are shown in the following table. The variable changes are shown in the following table.
.. This table was made with the output of .. 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 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 | | Old Value | New Value |

60
doc/source/upgrade-guide/upgrade-playbooks.rst
View File

@ -10,46 +10,44 @@ facilitate the upgrade process.
.. _config-change-playbook: .. _config-change-playbook:
deploy-config-changes.yml ``deploy-config-changes.yml``
------------------------- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This playbook will back up the ``/etc/openstack_deploy`` directory before This playbook backs up the ``/etc/openstack_deploy`` directory before
making the necessary changes to the configuration. changing the configuration.
``/etc/openstack_deploy`` is copied once to ``/etc/openstack_deploy.NEWTON``. ``/etc/openstack_deploy`` copies once to ``/etc/openstack_deploy.NEWTON``.
The copy happens only once, so repeated runs are safe.
.. _user-secrets-playbook: .. _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 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 file in the main repository, making it possible to guarantee all secrets move
carried into the upgraded environment and appropriately generated. Only new into the upgraded environment and generate appropriately.
secrets are added, such as those necessary for new services or new settings This adds only new secrets, such as those necessary for new services or new settings
added to existing services. Previously set values will not be changed. added to existing services. Values set previously are not changed.
.. _setup-infra-playbook: .. _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 The presence of ``pip.conf`` locks down all Python installations to packages on the
root ``pip`` directory locking down the python packages available to install. If repo server. If ``pip.conf`` exists on the repo server, it creates a circular
this file exists on the repository servers it will cause build failures. dependency, causing build failures.
.. _repo-server-pip-conf-removal: .. _repo-server-pip-conf-removal:
setup-infrastructure.yml ``setup-infrastructure.yml``
------------------------ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``setup-infrastructure.yml`` playbook is contained in the main The ``playbooks`` directory contains the ``setup-infrastructure.yml`` playbook.
``playbooks`` directory, but is called by ``run-upgrade.sh`` with specific The ``run-upgrade.sh`` script calls ``setup-insfrastructure.yml`` with specific
arguments in order to upgrade infrastructure components such as MariaDB and arguments to upgrade MariaDB and RabbitMQ.
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 .. 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' # -e 'galera_upgrade=true'
The ``rabbitmq_upgrade`` variable tells the ``rabbitmq_server`` role to The ``rabbitmq_upgrade`` variable tells the ``rabbitmq_server`` role to
upgrade the running major/minor version of RabbitMQ. upgrade RabbitMQ.
.. note:: .. 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 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 Newton release is optional. The Upgrading RabbitMQ in the Newton release is optional. The
``run-upgrade.sh`` script will not automatically upgrade it. If a RabbitMQ ``run-upgrade.sh`` script does not automatically upgrade it. To upgrade RabbitMQ,
upgrade using the script is desired, insert the ``rabbitmq_upgrade: true`` insert the ``rabbitmq_upgrade: true``
line into a file such as ``/etc/openstack_deploy/user_variables.yml``. line into a file, such as: ``/etc/openstack_deploy/user_variables.yml``.
The ``galera_upgrade`` variable tells the ``galera_server`` role to remove the 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: .. _setup-infra-playbook: