From b6077e2ebff6f0d7e70a1e506b2adb4d6c41c4c6 Mon Sep 17 00:00:00 2001 From: Alexandra Settle Date: Mon, 28 Nov 2016 11:51:42 +0000 Subject: [PATCH] [DOCS] Edits to the upgrade guide Implements: blueprint overhaul-upgrade-guide Change-Id: Ie1343b451ed763ec74df10630ac14f811096919b --- doc/source/upgrade-guide/index.rst | 4 +- doc/source/upgrade-guide/manual-upgrade.rst | 137 +++++++++--------- doc/source/upgrade-guide/minor-upgrade.rst | 76 ++++++---- doc/source/upgrade-guide/overview.rst | 38 +++-- .../upgrade-guide/reference-scripts.rst | 42 +++--- .../reference-upgrade-playbooks.rst | 55 +++---- doc/source/upgrade-guide/reference.rst | 6 +- doc/source/upgrade-guide/script-upgrade.rst | 31 ++-- 8 files changed, 201 insertions(+), 188 deletions(-) diff --git a/doc/source/upgrade-guide/index.rst b/doc/source/upgrade-guide/index.rst index 9b6af0a9d5..c7fd7f01b4 100644 --- a/doc/source/upgrade-guide/index.rst +++ b/doc/source/upgrade-guide/index.rst @@ -2,9 +2,9 @@ Upgrade Guide ============= -In this section you can find information on the +This guide provides information about the upgrade process from |previous_release_formal_name| to |current_release_formal_name| -upgrade process for OpenStack-Ansible. +for OpenStack-Ansible. .. toctree:: :maxdepth: 2 diff --git a/doc/source/upgrade-guide/manual-upgrade.rst b/doc/source/upgrade-guide/manual-upgrade.rst index 6dfc60b5d9..ce4356371d 100644 --- a/doc/source/upgrade-guide/manual-upgrade.rst +++ b/doc/source/upgrade-guide/manual-upgrade.rst @@ -1,21 +1,21 @@ -.. _manual-upgrade: +.. _upgrading-manually: -=============== -Manual upgrades -=============== +================== +Upgrading manually +================== -Deployers can run the upgrade steps manually. Manual execution is useful for -scoping the changes in the upgrade process (For example, in very large -deployments with strict SLA requirements), or for inclusion into other -orchestration for upgrade automation beyond what OpenStack-Ansible provides. +Deployers can run the upgrade steps manually. Manual upgrades are useful for +scoping the changes in the upgrade process (for example, in very large +deployments with strict SLA requirements), or performing other upgrade +automations beyond what is provided by OpenStack-Ansible. The steps detailed here match those performed by the ``run-upgrade.sh`` -script. Any of these steps can safely be run multiple times. +script. You can safely run these steps multiple times. Check out the |current_release_formal_name| release ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Ensure your OpenStack-Ansible code is on the latest +Ensure that your OpenStack-Ansible code is on the latest |current_release_formal_name| tagged release. .. parsed-literal:: @@ -25,10 +25,10 @@ Ensure your OpenStack-Ansible code is on the latest Prepare the shell variables ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - This step is optional, since these environment variables are simply - shortcuts. Files can be referenced directly. +Define these variables to reduce typing when running the remaining upgrade +tasks. Because these environments variables are shortcuts, this step is +optional. If you prefer, you can reference the files directly during the +upgrade. From the ``openstack-ansible`` root directory, run the following commands: @@ -38,22 +38,20 @@ From the ``openstack-ansible`` root directory, run the following commands: # export SCRIPTS_PATH="${MAIN_PATH}/scripts" # export UPGRADE_PLAYBOOKS="${SCRIPTS_PATH}/upgrade-utilities/playbooks" -These variables reduce typing when running the remaining upgrade -tasks. -Re-bootstrap Ansible for |current_release_formal_name| -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Bootstrap Ansible again +~~~~~~~~~~~~~~~~~~~~~~~ -Bootstrapping Ansible again ensures that all OpenStack-Ansible role -dependencies are in place before running playbooks from the +Bootstrap Ansible again to ensure that all OpenStack-Ansible role +dependencies are in place before you run playbooks from the |current_release_formal_name| release. .. code-block:: console # ${SCRIPTS_PATH}/bootstrap-ansible.sh -Change to playbooks directory -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Change to the playbooks directory +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Change to the playbooks directory so that the OpenStack-Ansible dynamic inventory is found automatically. @@ -62,20 +60,18 @@ inventory is found automatically. # cd playbooks -Pre-flight checks -~~~~~~~~~~~~~~~~~ +Preflight checks +~~~~~~~~~~~~~~~~ -Before starting with the new version, you should do pre-flight checks -to ensure everything is fine. If any of those check fail, the upgrade -should stop to let the deployer chose what to do. +Before starting with the upgraded version, perform preflight checks to ensure +your environment is stable. If any of those checks fail, the upgrade should +stop to let the deployer chose what to do. -Cleanup old facts -~~~~~~~~~~~~~~~~~ +Clean up old facts +~~~~~~~~~~~~~~~~~~ -Some configuration changed, and old facts should be purged before -the upgrade. - -See :ref:`fact-cleanup-playbook` for more details. +Some configurations have changed, so purge old facts before +the upgrade. For more information, see :ref:`fact-cleanup-playbook`. .. code-block:: console @@ -84,11 +80,10 @@ See :ref:`fact-cleanup-playbook` for more details. Update configuration and environment files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The user configuration files in ``/etc/openstack_deploy/`` and the environment -layout in ``/etc/openstack_deploy/env.d`` have new name -values added in |current_release_formal_name|. - -See :ref:`config-change-playbook` for more details. +The user configuration files in the ``/etc/openstack_deploy/`` directory and +the environment layout in the ``/etc/openstack_deploy/env.d`` directory have +new name values added in |current_release_formal_name|. Update the files as +follows. For more information, see :ref:`config-change-playbook`. .. code-block:: console @@ -98,22 +93,20 @@ Update user secrets file ~~~~~~~~~~~~~~~~~~~~~~~~ |current_release_formal_name| introduces new user secrets to the stack. -These are populated automatically with the following playbook. - -See :ref:`user-secrets-playbook` for more details. +These secrets are populated automatically when you run the following playbook. +For more information, see :ref:`user-secrets-playbook`. .. code-block:: console # openstack-ansible "${UPGRADE_PLAYBOOKS}/user-secrets-adjustment.yml" -Cleanup pip.conf file -~~~~~~~~~~~~~~~~~~~~~ +Clean up the pip.conf file +~~~~~~~~~~~~~~~~~~~~~~~~~~ -The presence of ``pip.conf`` file can cause build failures when upgrading to -|current_release_formal_name|. This play removes the ``pip.conf`` file -on all the physical servers and on the repo containers. - -See :ref:`pip-conf-removal` for more details. +The presence of the ``pip.conf`` file can cause build failures during the +upgrade to |current_release_formal_name|. This playbook removes the +``pip.conf`` file on all the physical servers and on the repo containers. +For more information, see :ref:`pip-conf-removal`. .. code-block:: console @@ -128,7 +121,7 @@ Before installing the infrastructure and OpenStack, update the host machines. # openstack-ansible setup-hosts.yml --limit '!galera_all' -This command is the same as doing host setups on a new install. The +This command is the same setting up hosts on a new installation. The ``galera_all`` host group is excluded to prevent reconfiguration and restarting of any Galera containers. @@ -143,17 +136,18 @@ Update the Galera container configuration independently. 'lxc_container_allow_restarts=false' --limit galera_all This command is a subset of the host setup playbook, limited to the -``galera_all`` host group. The configuration of those containers will be -updated but a restart for any changes to take effect will be deferred to a -later playbook. +``galera_all`` host group. The configuration of those containers is +updated but a restart for any changes to take effect is deferred to another +playbook (see the next section). -Perform a controlled rolling restart of the galera containers +Perform a controlled rolling restart of the Galera containers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Restart containers one at a time, ensuring that each is up, responding, -and synced with the other nodes in the cluster, before moving on to the -next. This step allows the lxc container config applied earlier to take -effect, ensuring that the containers are restarted in a controlled fashion. +Restart containers one at a time, ensuring that each is started, responding, +and synchronized with the other nodes in the cluster before moving on to the +next. This step allows the LXC container configuration that you applied earlier +to take effect, ensuring that the containers are restarted in a controlled +fashion. .. code-block:: console @@ -168,38 +162,38 @@ Install and update any new or changed HAProxy service configurations. # openstack-ansible haproxy-install.yml -Update repo servers -~~~~~~~~~~~~~~~~~~~ +Update repository servers +~~~~~~~~~~~~~~~~~~~~~~~~~ -Update the configuration of the repo servers and build new packages required by -the |current_release_formal_name| release. +Update the configuration of the repository servers and build new packages +required by the |current_release_formal_name| release. .. code-block:: console # openstack-ansible repo-install.yml -Perform a mariadb version upgrade -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Upgrade the MariaDB version +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Update mariadb to the most 10.0 minor release across the cluster. +Upgrade MariaDB to the most recent 10.x minor release across the cluster. .. code-block:: console # openstack-ansible galera-install.yml -e 'galera_upgrade=true' -Upgrade infrastructure -~~~~~~~~~~~~~~~~~~~~~~ +Upgrade the infrastructure +~~~~~~~~~~~~~~~~~~~~~~~~~~ -The following commands perform all steps from the setup-infrastructure -playbook, except for `repo-install.yml``, ``haproxyinstall.yml``, and -`galera-install.yml`` which we ran earlier. +The following commands perform all of the steps from the setup-infrastructure +playbook, except for ``repo-install.yml``, ``haproxyinstall.yml``, and +``galera-install.yml`` which you ran earlier. Running these playbook applies the relevant |current_release_formal_name| settings and packages. For certain versions of |previous_release_formal_name|, you must upgrade the RabbitMQ service. -See :ref:`setup-infra-playbook` for details. +For more information, see :ref:`setup-infra-playbook`. .. code-block:: console @@ -213,7 +207,8 @@ See :ref:`setup-infra-playbook` for details. Flush Memcached cache ~~~~~~~~~~~~~~~~~~~~~ -See :ref:`memcached-flush` for details. +Flush all of the caches in Memcached. For more information, +see :ref:`memcached-flush`. .. code-block:: console diff --git a/doc/source/upgrade-guide/minor-upgrade.rst b/doc/source/upgrade-guide/minor-upgrade.rst index ab834f5c1a..5e519ca6c8 100644 --- a/doc/source/upgrade-guide/minor-upgrade.rst +++ b/doc/source/upgrade-guide/minor-upgrade.rst @@ -1,23 +1,32 @@ -.. _minor-upgrades: +.. _upgrading-to-a-minor-version: -============== -Minor upgrades -============== +================================= +Executing a minor version upgrade +================================= -.. note:: To avoid issues and simplify troubleshooting during an upgrade, - first disable the security hardening role by setting your - variable ``apply_security_hardening`` to ``False`` in the - :file:`user_variables.yml` file. +Upgrades between minor versions of OpenStack-Ansible require updating the +repository to the latest minor release tag, and then running playbooks +against the target hosts. This section provides instructions for those tasks. + +Prerequisites +~~~~~~~~~~~~~ + +To avoid issues and simplify troubleshooting during the upgrade, disable the +security hardening role by setting the ``apply_security_hardening`` variable +to ``False`` in the :file:`user_variables.yml` file. + +Execute a minor version upgrade +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A minor upgrade typically requires the following steps: -#. Change directory into the repository clone root directory: +#. Change directory to the cloned repository's root directory: .. code-block:: console # cd /opt/openstack-ansible -#. Ensure your OpenStack-Ansible code is on the latest +#. Ensure that your OpenStack-Ansible code is on the latest |current_release_formal_name| tagged release: .. parsed-literal:: @@ -30,7 +39,7 @@ A minor upgrade typically requires the following steps: # ./scripts/bootstrap-ansible.sh -#. Change into the playbooks directory: +#. Change to the playbooks directory: .. code-block:: console @@ -57,34 +66,38 @@ A minor upgrade typically requires the following steps: .. note:: - Scope upgrades to specific OpenStack components by - executing each of the component playbooks using groups. + You can limit upgrades to specific OpenStack components. See the following + section for details. -For example: +Upgrade specific components +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. Update only the Compute hosts: +You can limit upgrades to specific OpenStack components by running each of the +component playbooks against groups. + +For example, you can update only the Compute hosts by running the following +command: .. code-block:: console # openstack-ansible os-nova-install.yml --limit nova_compute -#. Update only a single Compute host: - - .. note:: - - Skipping the ``nova-key`` tag is necessary as the keys on - all Compute hosts will not be gathered. +To update only a single Compute host, run the following command: .. code-block:: console # openstack-ansible os-nova-install.yml --limit \ --skip-tags 'nova-key' -To see which hosts belong to which groups, the -``inventory-manage.py`` script shows all groups and their hosts. -For example: + .. note:: -#. Change directory into the repository clone root directory: + Skipping the ``nova-key`` tag is necessary so that the keys on + all Compute hosts are not gathered. + +To see which hosts belong to which groups, use the ``inventory-manage.py`` +script to show all groups and their hosts. For example: + +#. Change directory to the repository clone root directory: .. code-block:: console @@ -96,30 +109,29 @@ For example: # ./scripts/inventory-manage.py -G -#. Show all hosts and which groups they belong: +#. Show all hosts and the groups to which they belong: .. code-block:: console # ./scripts/inventory-manage.py -g -To see which hosts a playbook will execute against, and to see which -tasks will execute. +To see which hosts a playbook runs against, and to see which tasks are +performed, run the following commands (for example): -#. Change directory into the repository clone playbooks directory: +#. Change directory to the repository clone playbooks directory: .. code-block:: console # cd /opt/openstack-ansible/playbooks -#. See the hosts in the ``nova_compute`` group which a playbook executes - against: +#. See the hosts in the ``nova_compute`` group that a playbook runs against: .. code-block:: console # openstack-ansible os-nova-install.yml --limit nova_compute \ --list-hosts -#. See the tasks which will be executed on hosts in the ``nova_compute`` group: +#. See the tasks that are executed on hosts in the ``nova_compute`` group: .. code-block:: console diff --git a/doc/source/upgrade-guide/overview.rst b/doc/source/upgrade-guide/overview.rst index b9c0655923..b02861a52b 100644 --- a/doc/source/upgrade-guide/overview.rst +++ b/doc/source/upgrade-guide/overview.rst @@ -2,31 +2,29 @@ Overview ======== -An OpenStack-Ansible environment can be upgraded between minor versions, -and between major versions. +An OpenStack-Ansible environment can upgrade to a minor or a major version. + +.. note:: + + You can only upgrade between sequential releases. Upgrades between minor versions of OpenStack-Ansible require -updating the repository clone to the latest minor release tag, then +updating the repository clone to the latest minor release tag, and then running playbooks against the target hosts. For more information, see -:ref:`minor-upgrades`. +:ref:`upgrading-to-a-minor-version`. -For major upgrades, the OpenStack-Ansible repository provides playbooks and -scripts used to upgrade an environment. The ``run-upgrade.sh`` script runs -each upgrade playbook in the correct order, or playbooks can be run +For upgrades between major versions, the OpenStack-Ansible repository provides +playbooks and scripts to upgrade an environment. The ``run-upgrade.sh`` +script runs each upgrade playbook in the correct order, or playbooks can be run individually if necessary. Alternatively, a deployer can upgrade manually. A major upgrade process performs the following actions: -- Modifies files residing in ``/etc/openstack_deploy`` in - order to reflect new configuration values. -- Some flag files are created by the migration scripts in order to achieve - idempotency. These files are placed in the - |upgrade_backup_dir| directory. -- Upgrade the RabbitMQ server during an OpenStack-Ansible upgrade process. - See :ref:`setup-infra-playbook` for details. - -For more information on the major upgrade process, see :ref:`script-upgrade` -and :ref:`manual-upgrade`. - -.. note:: - You can only upgrade between sequential releases. +- Modifies files residing in the ``/etc/openstack_deploy`` directory, to + reflect new configuration values. +- Places flag files that are created by the migration scripts in order to + achieve idempotency. These files are placed in the |upgrade_backup_dir| + directory. +- Upgrades the RabbitMQ server. See :ref:`setup-infra-playbook` for details. +For more information about the major upgrade process, see +:ref:`` and :ref:`Upgrading-manually`. diff --git a/doc/source/upgrade-guide/reference-scripts.rst b/doc/source/upgrade-guide/reference-scripts.rst index 367038c9bc..df44e76b1c 100644 --- a/doc/source/upgrade-guide/reference-scripts.rst +++ b/doc/source/upgrade-guide/reference-scripts.rst @@ -2,23 +2,23 @@ Scripts ======= -This section describes scripts that are used in the upgrade process in detail. +This section describes in detail the scripts that are used in the upgrade +process. -Within the main :file:`scripts` directory there is a :file:`upgrade-utilities` +Within the main :file:`scripts` directory there is an :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. +The ``run-upgrade.sh`` script controls the overall upgrade process for +deployers who do not want to upgrade manually. It provides the following +environment variables: -It provides the following environment variables: - -* ``SCRIPTS_PATH`` - path to the top level scripts directory -* ``MAIN_PATH`` - openstack_ansible root directory. -* ``UPGRADE_PLAYBOOKS`` - path to the playbooks used in upgrading +* ``SCRIPTS_PATH`` - The path to the top level scripts directory +* ``MAIN_PATH`` - The ``openstack_ansible`` root directory. +* ``UPGRADE_PLAYBOOKS`` - The path to the playbooks used in upgrading The upgrade script also bootstraps OpenStack-Ansible (using ``bootstrap-ansible.sh``) in order to provide the new role dependencies @@ -26,8 +26,8 @@ introduced in the |previous_release_formal_name| series. .. _migrate-os-vars: -``migrate_openstack_vars.py`` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +migrate_openstack_vars.py +~~~~~~~~~~~~~~~~~~~~~~~~~ Upstream decisions influenced the change of some variable names in |current_release_formal_name|. This script replaces any instances of these @@ -35,12 +35,12 @@ strings in the variable override files matching the pattern ``/etc/openstack_deploy/user_*.yml``. Variable names within comments are updated. -This script creates files of the form ``VARS_MIGRATED_`` and -places them in |upgrade_backup_dir|. -For example, once the script has processed the file -``/etc/openstack_deploy/user_variables.yml``, it creates -``VARS_MIGRATED_user_variables.yml`` in |upgrade_backup_dir|. -This indicates to OpenStack-Ansible to skip this step on successive runs. The -script itself does not check for this file. +This script creates files in the form ``VARS_MIGRATED_`` and +places them in |upgrade_backup_dir| directory. +For example, after the script processes the +``/etc/openstack_deploy/user_variables.yml`` file, it creates the +``VARS_MIGRATED_user_variables.yml`` file in the |upgrade_backup_dir| +directory. This indicates to OpenStack-Ansible to skip this step on successive +runs. The script itself does not check for this file. -Called by :ref:`config-change-playbook` +This script is called by the :ref:`config-change-playbook`. diff --git a/doc/source/upgrade-guide/reference-upgrade-playbooks.rst b/doc/source/upgrade-guide/reference-upgrade-playbooks.rst index 40ce863511..6ce4b20cfb 100644 --- a/doc/source/upgrade-guide/reference-upgrade-playbooks.rst +++ b/doc/source/upgrade-guide/reference-upgrade-playbooks.rst @@ -1,21 +1,19 @@ -================= -Upgrade playbooks -================= +========= +Playbooks +========= -This section describes the playbooks that are used in the upgrade process in -further detail. - -Within the main :file:`scripts` directory there is an :file:`upgrade-utilities` -directory, which contains an additional playbooks directory. These playbooks -facilitate the upgrade process. +This section provides details about the playbooks that are used in the +upgrade process. Within the main :file:`scripts` directory there is an +:file:`upgrade-utilities` directory, which contains an additional playbooks +directory. These playbooks facilitate the upgrade process. .. _fact-cleanup-playbook: ansible_fact_cleanup.yml ~~~~~~~~~~~~~~~~~~~~~~~~ -This calls a script to removes files in -``/etc/openstack_deploy/ansible_facts/`` +This playbook calls a script to remove files in the +``/etc/openstack_deploy/ansible_facts/`` directory. .. _config-change-playbook: @@ -25,8 +23,8 @@ deploy-config-changes.yml This playbook backs up the ``/etc/openstack_deploy`` directory before changing the configuration. -``/etc/openstack_deploy`` copies once to -|upgrade_backup_dir|. +The``/etc/openstack_deploy`` directory is copied once to the +|upgrade_backup_dir| directory. .. _user-secrets-playbook: @@ -34,19 +32,21 @@ user-secrets-adjustment.yml ~~~~~~~~~~~~~~~~~~~~~~~~~~~ This playbook ensures that the user secrets file is updated based on the -example 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. +example file in the main repository, making it possible to guarantee that all +secrets move into the upgraded environment and are generated appropriately. +This playbook adds only new secrets, such as those necessary for new services +or new settings added to existing services. Values that were set previously are +not changed. .. _pip-conf-removal: pip-conf-removal.yml ~~~~~~~~~~~~~~~~~~~~ -The presence of ``pip.conf`` locks down all Python installations to packages -on the repo servers. If ``pip.conf`` exists on a repo server or a physical -node, it will cause a circular dependency issue and the upgrade will fail. +The presence of the ``pip.conf`` file locks down all Python installations to +packages on the repo servers. If this file exists on a repo server or a +physical node, it causes a circular dependency issue and the upgrade fails. +This playbook removes the file on all the repo servers and physical nodes. .. _setup-infra-playbook: @@ -54,8 +54,8 @@ setup-infrastructure.yml ~~~~~~~~~~~~~~~~~~~~~~~~ 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. +The ``run-upgrade.sh`` script calls the ``setup-insfrastructure.yml`` playbook +with specific arguments to upgrade MariaDB and RabbitMQ. For example, to run an upgrade for both components at once, run the following commands: @@ -70,20 +70,21 @@ upgrade RabbitMQ. .. note:: The RabbitMQ server role installs patch releases automatically, - regardless of the value of ``rabbitmq_upgrade``. This variable only - controls upgrading the major or minor versions. + regardless of the value of ``rabbitmq_upgrade``. This variable + controls the upgrade of only the major or minor versions. Upgrading RabbitMQ in the |current_release_formal_name| release is optional. The ``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``. + 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 and Galera and upgrade to the 10.x series. +current version of MariaDB and Galera and upgrade to the 10.*x* series. .. _memcached-flush: memcached-flush.yml ~~~~~~~~~~~~~~~~~~~ -Sends "flush_all" to memcached with the help of nc. +This playbook sends the ``flush_all`` command to to Memcached with the help of +netcat. diff --git a/doc/source/upgrade-guide/reference.rst b/doc/source/upgrade-guide/reference.rst index f0b77d5aa2..fbd86ad4ce 100644 --- a/doc/source/upgrade-guide/reference.rst +++ b/doc/source/upgrade-guide/reference.rst @@ -1,6 +1,6 @@ -============================= -Upgrade reference information -============================= +====================================== +Reference information for the upgrades +====================================== .. toctree:: :maxdepth: 2 diff --git a/doc/source/upgrade-guide/script-upgrade.rst b/doc/source/upgrade-guide/script-upgrade.rst index 4f7c826b9a..1a46f6fd30 100644 --- a/doc/source/upgrade-guide/script-upgrade.rst +++ b/doc/source/upgrade-guide/script-upgrade.rst @@ -1,8 +1,8 @@ -.. _script-upgrade: +.. _Upgrading-by-using-a-script: -======================== -Upgrading using a script -======================== +=========================== +Upgrading by using a script +=========================== The |current_release_formal_name| release series of OpenStack-Ansible contains the code for migrating from |previous_release_formal_name| to @@ -10,19 +10,26 @@ the code for migrating from |previous_release_formal_name| to .. warning:: - The upgrade script is still under active development and should not be run + The upgrade script is still under active development. Do *not* run it on a production environment at this time. Running the upgrade script ~~~~~~~~~~~~~~~~~~~~~~~~~~ -To upgrade from |previous_release_formal_name| to -|current_release_formal_name| using the upgrade script, -perform the following steps in the ``openstack-ansible`` -directoy: +To upgrade from |previous_release_formal_name| to |current_release_formal_name| +by using the upgrade script, perform the following steps in the +``openstack-ansible`` directory: -.. parsed-literal:: +#. Change directory to the repository clone root directory: - # git checkout |latest_tag| - # ./scripts/run-upgrade.sh + .. code-block:: console + + # cd /opt/openstack-ansible + +#. Run the following commands: + + .. parsed-literal:: + + # git checkout |latest_tag| + # ./scripts/run-upgrade.sh