From 875c5e4e6ecfc55e84e948b2125459c4c8912b9c Mon Sep 17 00:00:00 2001 From: daz Date: Fri, 10 Jun 2016 13:00:07 +1000 Subject: [PATCH] [docs] Revise upgrade guide structure 1. Move minor upgrade content from the install guide to the upgrade guide 2. Revise the overview section to include minor upgrades 3. Restructure the upgrade guide for improved information flow 4. Add configure-keystone.rst to the old install guide that was accidently removed in https://review.openstack.org/#/c/328095/ Change-Id: I602ef4a4f95f5ff46ee9b9eaaaa6ccdfd637d1dc Implements: blueprint osa-install-guide-overhaul --- .../install-guide-revised-draft/index.rst | 1 - .../configure-keystone.rst | 0 doc/source/upgrade-guide/index.rst | 10 ++- doc/source/upgrade-guide/manual-upgrade.rst | 14 +++- .../minor-upgrade.rst} | 76 ++++++++---------- doc/source/upgrade-guide/navigation.txt | 2 +- doc/source/upgrade-guide/overview.rst | 77 ++++++------------- .../{scripts.rst => reference-scripts.rst} | 0 ...ks.rst => reference-upgrade-playbooks.rst} | 3 +- doc/source/upgrade-guide/reference.rst | 9 +++ doc/source/upgrade-guide/script-upgrade.rst | 30 ++++++++ 11 files changed, 115 insertions(+), 107 deletions(-) rename doc/source/{install-guide-revised-draft => install-guide}/configure-keystone.rst (100%) rename doc/source/{install-guide-revised-draft/app-minorupgrade.rst => upgrade-guide/minor-upgrade.rst} (59%) rename doc/source/upgrade-guide/{scripts.rst => reference-scripts.rst} (100%) rename doc/source/upgrade-guide/{upgrade-playbooks.rst => reference-upgrade-playbooks.rst} (98%) create mode 100644 doc/source/upgrade-guide/reference.rst create mode 100644 doc/source/upgrade-guide/script-upgrade.rst diff --git a/doc/source/install-guide-revised-draft/index.rst b/doc/source/install-guide-revised-draft/index.rst index 6296d2f6c0..71c848d0aa 100644 --- a/doc/source/install-guide-revised-draft/index.rst +++ b/doc/source/install-guide-revised-draft/index.rst @@ -64,7 +64,6 @@ Appendices app-configfiles.rst app-resources.rst - app-minorupgrade.rst app-tips.rst app-plumgrid.rst app-nuage.rst diff --git a/doc/source/install-guide-revised-draft/configure-keystone.rst b/doc/source/install-guide/configure-keystone.rst similarity index 100% rename from doc/source/install-guide-revised-draft/configure-keystone.rst rename to doc/source/install-guide/configure-keystone.rst diff --git a/doc/source/upgrade-guide/index.rst b/doc/source/upgrade-guide/index.rst index 70dc4527ae..f5c7bb5720 100644 --- a/doc/source/upgrade-guide/index.rst +++ b/doc/source/upgrade-guide/index.rst @@ -1,15 +1,17 @@ +===================== Upgrade Documentation ===================== In this section you can find information on the Mitaka to -Newton upgrade process. +Newton upgrade process for OpenStack-Ansible. -Contents: +Table of Contents: .. toctree:: :maxdepth: 2 overview + minor-upgrade + script-upgrade manual-upgrade - scripts - upgrade-playbooks + reference diff --git a/doc/source/upgrade-guide/manual-upgrade.rst b/doc/source/upgrade-guide/manual-upgrade.rst index d1079e5b1c..f6a6005e41 100644 --- a/doc/source/upgrade-guide/manual-upgrade.rst +++ b/doc/source/upgrade-guide/manual-upgrade.rst @@ -1,7 +1,13 @@ .. _manual-upgrade: -Manual Upgrade Steps -==================== +=============== +Manual upgrades +=============== + +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. The steps detailed here match those performed by the ``run-upgrade.sh`` script. Any of these steps can safely be run multiple times. @@ -17,8 +23,8 @@ Ensure your OpenStack-Ansible code is on the latest Newton release tag (14.x.x). # LATEST_TAG=$(git describe --abbrev=0 --tags) # git checkout ${LATEST_TAG} -Preparing the shell variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Prepare the shell variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: diff --git a/doc/source/install-guide-revised-draft/app-minorupgrade.rst b/doc/source/upgrade-guide/minor-upgrade.rst similarity index 59% rename from doc/source/install-guide-revised-draft/app-minorupgrade.rst rename to doc/source/upgrade-guide/minor-upgrade.rst index c9f1e1351a..982e212292 100644 --- a/doc/source/install-guide-revised-draft/app-minorupgrade.rst +++ b/doc/source/upgrade-guide/minor-upgrade.rst @@ -1,71 +1,63 @@ -`Home `__ OpenStack-Ansible Installation Guide +.. _minor-upgrades: -========================== -Appendix C: Minor upgrades -========================== +============== +Minor upgrades +============== -Upgrades between minor versions of OpenStack-Ansible are handled by -updating the repository clone to the latest tag, then executing playbooks -against the target hosts. +.. 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. -.. note:: In order to avoid issues and ease the troubleshooting if an - issue appears during the upgrade, disable the security - hardening role before running the following steps. Set your - variable ``apply_security_hardening`` to ``False``. - -A minor upgrade typically requires the execution of the following: +A minor upgrade typically requires the following steps: #. Change directory into the repository clone root directory: - .. code-block:: shell-session + .. code-block:: console # cd /opt/openstack-ansible -#. Update the git remotes: +#. Ensure your OpenStack-Ansible code is on the latest Newton release tag (14.x.x): - .. code-block:: shell-session + .. code-block:: console + + # git checkout stable/newton + # LATEST_TAG=$(git describe --abbrev=0 --tags) + # git checkout ${LATEST_TAG} - # git fetch --all +#. Update all the dependent roles to the latest version: -#. Checkout the latest tag (the below tag is an example): - - .. code-block:: shell-session - - # git checkout 13.0.1 - -#. Update all the dependent roles to the latest versions: - - .. code-block:: shell-session + .. code-block:: console # ./scripts/bootstrap-ansible.sh #. Change into the playbooks directory: - .. code-block:: shell-session + .. code-block:: console # cd playbooks #. Update the hosts: - .. code-block:: shell-session + .. code-block:: console # openstack-ansible setup-hosts.yml #. Update the infrastructure: - .. code-block:: shell-session + .. code-block:: console # openstack-ansible -e rabbitmq_upgrade=true \ - setup-infrastructure.yml + setup-infrastructure.yml #. Update all OpenStack services: - .. code-block:: shell-session + .. code-block:: console # openstack-ansible setup-openstack.yml .. note:: - + Scope upgrades to specific OpenStack components by executing each of the component playbooks using groups. @@ -73,18 +65,18 @@ For example: #. Update only the Compute hosts: - .. code-block:: shell-session + .. 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. - .. code-block:: shell-session + .. code-block:: console # openstack-ansible os-nova-install.yml --limit \ --skip-tags 'nova-key' @@ -95,19 +87,19 @@ For example: #. Change directory into the repository clone root directory: - .. code-block:: shell-session + .. code-block:: console # cd /opt/openstack-ansible #. Show all groups and which hosts belong to them: - .. code-block:: shell-session + .. code-block:: console # ./scripts/inventory-manage.py -G #. Show all hosts and which groups they belong: - .. code-block:: shell-session + .. code-block:: console # ./scripts/inventory-manage.py -g @@ -116,20 +108,20 @@ tasks will execute. #. Change directory into the repository clone playbooks directory: - .. code-block:: shell-session + .. code-block:: console # cd /opt/openstack-ansible/playbooks #. See the hosts in the ``nova_compute`` group which a playbook executes against: - .. code-block:: shell-session + .. 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: - .. code-block:: shell-session + .. code-block:: console # openstack-ansible os-nova-install.yml --limit nova_compute \ --skip-tags 'nova-key' \ @@ -137,4 +129,4 @@ tasks will execute. -------------- -.. include:: navigation.txt +.. include:: navigation.txt \ No newline at end of file diff --git a/doc/source/upgrade-guide/navigation.txt b/doc/source/upgrade-guide/navigation.txt index e7f7212f19..aae70553c2 100644 --- a/doc/source/upgrade-guide/navigation.txt +++ b/doc/source/upgrade-guide/navigation.txt @@ -1,4 +1,4 @@ * `Documentation Home <../index.html>`_ -* `Installation Guide <../installation-guide/index.html>`_ +* `Installation Guide <../install-guide/index.html>`_ * `Upgrade Guide `_ * `Developer Documentation <../developer-docs/index.html>`_ diff --git a/doc/source/upgrade-guide/overview.rst b/doc/source/upgrade-guide/overview.rst index d262c70cd7..05d176ef33 100644 --- a/doc/source/upgrade-guide/overview.rst +++ b/doc/source/upgrade-guide/overview.rst @@ -1,65 +1,34 @@ +======== Overview ======== -The OpenStack-Ansible repository provides playbooks and scripts used -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. +An OpenStack-Ansible environment can be upgraded between minor versions, +and between major versions. -Running the upgrade script -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Upgrades between minor versions of OpenStack-Ansible require +updating the repository clone to the latest minor release tag, then +running playbooks against the target hosts. For more information, see +:ref:`minor-upgrades`. -The Newton release series of OpenStack-Ansible contain the code for -migrating from Mitaka to Newton. +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 +individually if necessary. Alternatively, a deployer can upgrade manually. A +major upgrade process performs the following actions: -.. warning:: +- 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 ``/etc/openstack_deploy.NEWTON`` + directory. +- Upgrade the RabbitMQ server during an OpenStack-Ansible upgrade process. + See :ref:`setup-infra-playbook` for details. - The upgrade script is still under active development and should not be run at this time. +For more information on the major upgrade process, see :ref:`script-upgrade` +and :ref:`manual-upgrade`. -To upgrade from Mitaka to Newton using the upgrade script, perform the -following steps in the ``openstack-ansible`` directory: - -.. code-block:: console - - # git checkout stable/newton - # LATEST_TAG=$(git describe --abbrev=0 --tags) - # git checkout ${LATEST_TAG} - # ./scripts/run-upgrade.sh - -Upgrading manually -~~~~~~~~~~~~~~~~~~ - -Deployers can run the upgrade steps manually. See :ref:`manual-upgrade`. -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. - -Upgrade actions -~~~~~~~~~~~~~~~ - -Both the upgrade script and manual upgrade steps perform the actions and -use the concepts introduced below. - -Configuration changes ---------------------- - -The upgrade process modifies files residing in ``/etc/openstack_deploy`` in -order to reflect new Newton values. - -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 ----------------- - -Upgrade the RabbitMQ server during an OpenStack-Ansible upgrade. - -See :ref:`setup-infra-playbook` for details. +.. note:: + You can only upgrade between sequential releases. -------------- diff --git a/doc/source/upgrade-guide/scripts.rst b/doc/source/upgrade-guide/reference-scripts.rst similarity index 100% rename from doc/source/upgrade-guide/scripts.rst rename to doc/source/upgrade-guide/reference-scripts.rst diff --git a/doc/source/upgrade-guide/upgrade-playbooks.rst b/doc/source/upgrade-guide/reference-upgrade-playbooks.rst similarity index 98% rename from doc/source/upgrade-guide/upgrade-playbooks.rst rename to doc/source/upgrade-guide/reference-upgrade-playbooks.rst index 867e1f2958..065c95e139 100644 --- a/doc/source/upgrade-guide/upgrade-playbooks.rst +++ b/doc/source/upgrade-guide/reference-upgrade-playbooks.rst @@ -1,4 +1,5 @@ -Upgrade Playbooks +================= +Upgrade playbooks ================= This section describes the playbooks that are used in the upgrade process in diff --git a/doc/source/upgrade-guide/reference.rst b/doc/source/upgrade-guide/reference.rst new file mode 100644 index 0000000000..f0b77d5aa2 --- /dev/null +++ b/doc/source/upgrade-guide/reference.rst @@ -0,0 +1,9 @@ +============================= +Upgrade reference information +============================= + +.. toctree:: + :maxdepth: 2 + + reference-scripts + reference-upgrade-playbooks diff --git a/doc/source/upgrade-guide/script-upgrade.rst b/doc/source/upgrade-guide/script-upgrade.rst new file mode 100644 index 0000000000..1d3615460b --- /dev/null +++ b/doc/source/upgrade-guide/script-upgrade.rst @@ -0,0 +1,30 @@ +.. _script-upgrade: + +======================== +Upgrading using a script +======================== + +The Newton release series of OpenStack-Ansible contains the code for +migrating from Mitaka to Newton. + +.. warning:: + + The upgrade script is still under active development and should not be run + on a production environment at this time. + +Running the upgrade script +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To upgrade from Mitaka to Newton using the upgrade script, perform the +following steps in the ``openstack-ansible`` directory: + +.. code-block:: console + + # git checkout stable/newton + # LATEST_TAG=$(git describe --abbrev=0 --tags) + # git checkout ${LATEST_TAG} + # ./scripts/run-upgrade.sh + +-------------- + +.. include:: navigation.txt