openstack/openstack-ansible
Code Issues Proposed changes

[docs] Revise upgrade guide structure

Browse Source 
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
This commit is contained in:
daz 2016-06-10 13:00:07 +10:00
parent ab8e272f7f
commit 875c5e4e6e
11 changed files with 115 additions and 107 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/source/install-guide-revised-draft/index.rst
View File

@ -64,7 +64,6 @@ Appendices
app-configfiles.rst
app-resources.rst
app-minorupgrade.rst
app-tips.rst
app-plumgrid.rst
app-nuage.rst

0
doc/source/install-guide-revised-draft/configure-keystone.rst → doc/source/install-guide/configure-keystone.rst
View File

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

@ -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

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

@ -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::

76
doc/source/install-guide-revised-draft/app-minorupgrade.rst → doc/source/upgrade-guide/minor-upgrade.rst
View File

@ -1,71 +1,63 @@
`Home <index.html>`__ 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 <node-name> \
--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

2
doc/source/upgrade-guide/navigation.txt
View File

@ -1,4 +1,4 @@
* `Documentation Home <../index.html>`_
* `Installation Guide <../installation-guide/index.html>`_
* `Installation Guide <../install-guide/index.html>`_
* `Upgrade Guide <index.html>`_
* `Developer Documentation <../developer-docs/index.html>`_

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

@ -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.
--------------

0
doc/source/upgrade-guide/scripts.rst → doc/source/upgrade-guide/reference-scripts.rst
View File

3
doc/source/upgrade-guide/upgrade-playbooks.rst → doc/source/upgrade-guide/reference-upgrade-playbooks.rst
View File

@ -1,4 +1,5 @@
Upgrade Playbooks
=================
Upgrade playbooks
=================
This section describes the playbooks that are used in the upgrade process in

9
doc/source/upgrade-guide/reference.rst Normal file
View File

@ -0,0 +1,9 @@
=============================
Upgrade reference information
=============================
.. toctree::
:maxdepth: 2
reference-scripts
reference-upgrade-playbooks

30
doc/source/upgrade-guide/script-upgrade.rst Normal file
View File

@ -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