From 56194bcb5abb4fda39d5d69f21ca4ca935241d05 Mon Sep 17 00:00:00 2001 From: Jean-Philippe Evrard Date: Sun, 18 Feb 2018 08:33:02 +0000 Subject: [PATCH] [Docs] Move upgrade guides into ops Simplify the documentation, to be in-line with general openstack recommendations, and follow the proposed blueprint bp/docs-improvements. Change-Id: Ib983d14cbbde13aa8fbb51ac91faa637ede3ed58 --- doc/source/admin/index.rst | 8 +++---- .../major-upgrades-manual-upgrade.rst} | 1 - .../upgrades/major-upgrades-with-script.rst} | 5 ++-- .../upgrades/major-upgrades.rst} | 23 +++++++++++-------- .../upgrades/minor-updates.rst} | 18 +++++++-------- doc/source/user/index.rst | 13 ++++------- 6 files changed, 33 insertions(+), 35 deletions(-) rename doc/source/{user/manual-upgrade.rst => admin/upgrades/major-upgrades-manual-upgrade.rst} (99%) rename doc/source/{user/script-upgrade.rst => admin/upgrades/major-upgrades-with-script.rst} (83%) rename doc/source/{user/overview.rst => admin/upgrades/major-upgrades.rst} (66%) rename doc/source/{user/minor-upgrade.rst => admin/upgrades/minor-updates.rst} (88%) diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 398305ee52..cef9483b34 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -10,10 +10,8 @@ For information how to deploy your OpenStack-Ansible cloud, refer to the for step-by-step instructions on how to deploy the OpenStack packages and dependencies on your cloud using OpenStack-Ansible. -This guide is recommended for users of a successfully deployed -OpenStack-Ansible cloud. This explains from basic operations such as -adding images, booting instances, and attaching volumes, to the -more complex operations like upgrading. +This guide ranges from first operations to verify your deployment, to +the major upgrades procedures. .. toctree:: :maxdepth: 1 @@ -25,5 +23,7 @@ more complex operations like upgrading. monitoring-systems.rst backup-restore.rst troubleshooting.rst + upgrades/minor-updates.rst + upgrades/major-upgrades.rst advanced-config.rst ref-info.rst diff --git a/doc/source/user/manual-upgrade.rst b/doc/source/admin/upgrades/major-upgrades-manual-upgrade.rst similarity index 99% rename from doc/source/user/manual-upgrade.rst rename to doc/source/admin/upgrades/major-upgrades-manual-upgrade.rst index a300041f53..730737b766 100644 --- a/doc/source/user/manual-upgrade.rst +++ b/doc/source/admin/upgrades/major-upgrades-manual-upgrade.rst @@ -1,6 +1,5 @@ .. _upgrading-manually: -================== Upgrading manually ================== diff --git a/doc/source/user/script-upgrade.rst b/doc/source/admin/upgrades/major-upgrades-with-script.rst similarity index 83% rename from doc/source/user/script-upgrade.rst rename to doc/source/admin/upgrades/major-upgrades-with-script.rst index e6a4bdcc1b..6a8cf40255 100644 --- a/doc/source/user/script-upgrade.rst +++ b/doc/source/admin/upgrades/major-upgrades-with-script.rst @@ -1,6 +1,5 @@ .. _upgrading-by-using-a-script: -=========================== Upgrading by using a script =========================== @@ -10,8 +9,8 @@ the code for migrating from |previous_release_formal_name| to .. warning:: - The upgrade script is still under active development. Do *not* run it - on a production environment at this time. + The upgrade script is always under active development. + Test it on a development environment first. Running the upgrade script ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/user/overview.rst b/doc/source/admin/upgrades/major-upgrades.rst similarity index 66% rename from doc/source/user/overview.rst rename to doc/source/admin/upgrades/major-upgrades.rst index 6f2c2d88dc..76babcd7d7 100644 --- a/doc/source/user/overview.rst +++ b/doc/source/admin/upgrades/major-upgrades.rst @@ -1,17 +1,18 @@ -======== -Overview -======== +============== +Major upgrades +============== -An OpenStack-Ansible environment can upgrade to a minor or a major version. +This guide provides information about the upgrade process from +|previous_release_formal_name| to |current_release_formal_name| +for OpenStack-Ansible. .. 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, and then -running playbooks against the target hosts. For more information, see -:ref:`upgrading-to-a-minor-version`. + +Introduction +============ For upgrades between major versions, the OpenStack-Ansible repository provides playbooks and scripts to upgrade an environment. The ``run-upgrade.sh`` @@ -24,7 +25,11 @@ major upgrade process performs the following actions: - 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. +- Upgrades the infrastructure servers. + See :ref:`setup-infra-playbook` for details. For more information about the major upgrade process, see :ref:`upgrading-by-using-a-script` and :ref:`upgrading-manually`. + +.. include:: major-upgrades-with-script.rst +.. include:: major-upgrades-manual-upgrade.rst diff --git a/doc/source/user/minor-upgrade.rst b/doc/source/admin/upgrades/minor-updates.rst similarity index 88% rename from doc/source/user/minor-upgrade.rst rename to doc/source/admin/upgrades/minor-updates.rst index e030c99d16..ffc7200e0e 100644 --- a/doc/source/user/minor-upgrade.rst +++ b/doc/source/admin/upgrades/minor-updates.rst @@ -1,19 +1,19 @@ -.. _upgrading-to-a-minor-version: +===================== +Minor version upgrade +===================== -================================= -Executing a minor version upgrade -================================= - -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. +Upgrades between minor versions of OpenStack-Ansible require +updating the repository clone to the latest minor release tag, updating +the ansible roles, 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. +to ``False`` in the :file:`user_variables.yml` file, and +backup your openstack-ansible installation. Execute a minor version upgrade ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index c7fd7f01b4..642d0bb5f7 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -1,16 +1,11 @@ -============= -Upgrade Guide -============= +========== +User Guide +========== + -This guide provides information about the upgrade process from -|previous_release_formal_name| to |current_release_formal_name| -for OpenStack-Ansible. .. toctree:: :maxdepth: 2 - overview - minor-upgrade - script-upgrade manual-upgrade reference