From 3bb1c40f72f95da61bfa20f9692fbcbd11bdfc0c Mon Sep 17 00:00:00 2001 From: Alexandra Date: Fri, 20 May 2016 11:44:44 +0100 Subject: [PATCH] DOCS: Clean up of the Newton upgrade guide Forming to conventions applied in the install guide. This cleans up RST, spelling, and grammar fixes. Change-Id: Ieeb678bffc2b59a29e05528cc3d908b036e6c1a8 (cherry picked from commit 29ec1bad24946bf86dfc656f47ab90665bb6fd2f) --- doc/source/upgrade-guide/index.rst | 3 +- doc/source/upgrade-guide/manual-upgrade.rst | 64 +++++++++---------- doc/source/upgrade-guide/overview.rst | 18 +++--- doc/source/upgrade-guide/scripts.rst | 29 ++++----- .../upgrade-guide/upgrade-playbooks.rst | 60 +++++++++-------- 5 files changed, 83 insertions(+), 91 deletions(-) diff --git a/doc/source/upgrade-guide/index.rst b/doc/source/upgrade-guide/index.rst index 809b7ee8c6..70dc4527ae 100644 --- a/doc/source/upgrade-guide/index.rst +++ b/doc/source/upgrade-guide/index.rst @@ -1,7 +1,8 @@ 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: diff --git a/doc/source/upgrade-guide/manual-upgrade.rst b/doc/source/upgrade-guide/manual-upgrade.rst index 271043b308..2f14dc4055 100644 --- a/doc/source/upgrade-guide/manual-upgrade.rst +++ b/doc/source/upgrade-guide/manual-upgrade.rst @@ -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 Newton version ------------------------ +Check out the Newton release +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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} 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 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 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 Newton. This step updates the files as necessary. +layout in ``/etc/openstack_deploy/env.d`` have new name +values added in Newton. 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 ------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~ Newton 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 Newton. 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 Newton. 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 Newton settings and packages. This upgrade is required for the Newton release of OpenStack-Ansible. -RabbitMQ may need a minor version upgrade depending on what version of Mitaka -was previously installed. +For certain versions of Mitaka, 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 diff --git a/doc/source/upgrade-guide/overview.rst b/doc/source/upgrade-guide/overview.rst index b5336b6b42..d262c70cd7 100644 --- a/doc/source/upgrade-guide/overview.rst +++ b/doc/source/upgrade-guide/overview.rst @@ -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 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. .. 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 Newton 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.NEWTON`` 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. diff --git a/doc/source/upgrade-guide/scripts.rst b/doc/source/upgrade-guide/scripts.rst index 7356453ebc..0c67f2eac2 100644 --- a/doc/source/upgrade-guide/scripts.rst +++ b/doc/source/upgrade-guide/scripts.rst @@ -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 Mitaka series. .. _migrate-os-vars: -migrate_openstack_vars.py -------------------------- +``migrate_openstack_vars.py`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In Mitaka, 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 Newton. +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.NEWTON/VARS_MIGRATED_file``. For example, once the script has -processed the file ``/etc/openstack_deploy/user_variables.yml``. it creates -``/etc/openstack_deploy.NEWTON/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.NEWTON/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 | diff --git a/doc/source/upgrade-guide/upgrade-playbooks.rst b/doc/source/upgrade-guide/upgrade-playbooks.rst index a950241983..384ad7f2b7 100644 --- a/doc/source/upgrade-guide/upgrade-playbooks.rst +++ b/doc/source/upgrade-guide/upgrade-playbooks.rst @@ -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.NEWTON``. -The copy happens only once, so repeated runs are safe. +``/etc/openstack_deploy`` copies once to ``/etc/openstack_deploy.NEWTON``. .. _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 Newton 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: