From 54f5caaa8f078991a3fd864aec797f1fb75d1c16 Mon Sep 17 00:00:00 2001 From: Marios Andreou Date: Fri, 23 Nov 2018 15:20:00 +0200 Subject: [PATCH] Reorganise upgrade/update/ffwd upgrade docs into their own section Brings together the upgrade/update/ffwd upgrade user and developer docs into a new section for better visibility Change-Id: Iecdd67f02f5686a49c3a7f1d998de8e49492ff83 Related-Bug: #1804642 --- doc/source/fast_forward_upgrade/index.rst | 8 -------- doc/source/index.rst | 6 +++--- .../advanced_deployment/network_isolation.rst | 2 +- .../advanced_deployment/template_deploy.rst | 2 +- .../install/containers_deployment/undercloud.rst | 2 +- doc/source/install/developer/developer.rst | 1 - doc/source/install/installation/installation.rst | 8 +++----- .../install/post_deployment/post_deployment.rst | 2 -- .../developer/upgrades/ci_upgrades.rst | 4 ++-- .../developer/upgrades/fast_fw_upgrade.plantuml | 0 .../developer/upgrades/fast_fw_upgrade.png | Bin .../developer/upgrades/fast_fw_upgrade.rst | 0 .../developer/upgrades/links.rst | 0 .../developer/upgrades/major_upgrade.plantuml | 0 .../developer/upgrades/major_upgrade.png | Bin .../developer/upgrades/major_upgrade.rst | 0 .../developer/upgrades/minor_update.plantuml | 0 .../developer/upgrades/minor_update.png | Bin .../developer/upgrades/minor_update.rst | 2 +- .../developer/upgrades}/rdo_upgrades_jobs.png | Bin .../developer/upgrades/upgrades.rst | 4 ++-- .../fast_forward_upgrade.rst | 10 +++++----- doc/source/upgrade/index.rst | 13 +++++++++++++ .../upgrade.rst => upgrade/major_upgrade.rst} | 10 +++++----- .../minor_update.rst} | 4 ++-- .../updating.rst => upgrade/undercloud.rst} | 8 ++++---- 26 files changed, 43 insertions(+), 43 deletions(-) delete mode 100644 doc/source/fast_forward_upgrade/index.rst rename doc/source/{install => upgrade}/developer/upgrades/ci_upgrades.rst (99%) rename doc/source/{install => upgrade}/developer/upgrades/fast_fw_upgrade.plantuml (100%) rename doc/source/{install => upgrade}/developer/upgrades/fast_fw_upgrade.png (100%) rename doc/source/{install => upgrade}/developer/upgrades/fast_fw_upgrade.rst (100%) rename doc/source/{install => upgrade}/developer/upgrades/links.rst (100%) rename doc/source/{install => upgrade}/developer/upgrades/major_upgrade.plantuml (100%) rename doc/source/{install => upgrade}/developer/upgrades/major_upgrade.png (100%) rename doc/source/{install => upgrade}/developer/upgrades/major_upgrade.rst (100%) rename doc/source/{install => upgrade}/developer/upgrades/minor_update.plantuml (100%) rename doc/source/{install => upgrade}/developer/upgrades/minor_update.png (100%) rename doc/source/{install => upgrade}/developer/upgrades/minor_update.rst (98%) rename doc/source/{install/_images => upgrade/developer/upgrades}/rdo_upgrades_jobs.png (100%) rename doc/source/{install => upgrade}/developer/upgrades/upgrades.rst (74%) rename doc/source/{install/post_deployment => upgrade}/fast_forward_upgrade.rst (98%) create mode 100644 doc/source/upgrade/index.rst rename doc/source/{install/post_deployment/upgrade.rst => upgrade/major_upgrade.rst} (99%) rename doc/source/{install/post_deployment/package_update.rst => upgrade/minor_update.rst} (98%) rename doc/source/{install/installation/updating.rst => upgrade/undercloud.rst} (94%) diff --git a/doc/source/fast_forward_upgrade/index.rst b/doc/source/fast_forward_upgrade/index.rst deleted file mode 100644 index 6e804a30..00000000 --- a/doc/source/fast_forward_upgrade/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -Fast Forward Upgrade Guide -========================== - -.. toctree:: - :maxdepth: 2 - :includehidden: - - ../install/post_deployment/fast_forward_upgrade.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index b552037e..599d34de 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -25,14 +25,14 @@ Install Guide install/index -Fast Forward Upgrade Guide --------------------------- +Upgrades/Updates/FFWD-Upgrade +----------------------------- .. toctree:: :maxdepth: 3 :includehidden: - fast_forward_upgrade/index + upgrade/index Documentation Conventions diff --git a/doc/source/install/advanced_deployment/network_isolation.rst b/doc/source/install/advanced_deployment/network_isolation.rst index 8dd0e771..d5870f8d 100644 --- a/doc/source/install/advanced_deployment/network_isolation.rst +++ b/doc/source/install/advanced_deployment/network_isolation.rst @@ -902,7 +902,7 @@ tenant VLANs were on a bridge named ``br-vlan``, then use these values in ``--environment-file`` option) whenever you make subsequent changes to the overcloud, such as :doc:`../post_deployment/scale_roles`, :doc:`../post_deployment/delete_nodes` or - :doc:`../post_deployment/package_update`. + :doc:`../../upgrade/minor_update`. Creating Floating IP Networks ----------------------------- diff --git a/doc/source/install/advanced_deployment/template_deploy.rst b/doc/source/install/advanced_deployment/template_deploy.rst index d1525764..2b5da0e2 100644 --- a/doc/source/install/advanced_deployment/template_deploy.rst +++ b/doc/source/install/advanced_deployment/template_deploy.rst @@ -58,7 +58,7 @@ so the deployment uses the local version:: ``--environment-file`` option) whenever you make subsequent changes to the overcloud, such as :doc:`../post_deployment/scale_roles`, :doc:`../post_deployment/delete_nodes` or - :doc:`../post_deployment/package_update`. + :doc:`../../upgrade/minor_update`. .. _custom-template-location: diff --git a/doc/source/install/containers_deployment/undercloud.rst b/doc/source/install/containers_deployment/undercloud.rst index d9fc1e29..66ae0777 100644 --- a/doc/source/install/containers_deployment/undercloud.rst +++ b/doc/source/install/containers_deployment/undercloud.rst @@ -17,7 +17,7 @@ directly on the host operating system. This reduces the required packages in the host to the bare minimum for running the container runtime and managing the base network layer. -.. note:: Check the :doc:`../installation/installing` and :doc:`../installation/updating` +.. note:: Check the :doc:`../installation/installing` and :doc:`../../upgrade/undercloud` sections for deploying and upgrading a containerized undercloud. .. note:: Check the :ref:`debug-containers` section for more tips and tricks for diff --git a/doc/source/install/developer/developer.rst b/doc/source/install/developer/developer.rst index eed1dadd..b80479af 100644 --- a/doc/source/install/developer/developer.rst +++ b/doc/source/install/developer/developer.rst @@ -7,6 +7,5 @@ Documentation of developer-specific options in |project|. .. toctree:: tht_walkthrough/tht_walkthrough - upgrades/upgrades release mistral_workflows/00-index diff --git a/doc/source/install/installation/installation.rst b/doc/source/install/installation/installation.rst index eec96cae..a261f299 100644 --- a/doc/source/install/installation/installation.rst +++ b/doc/source/install/installation/installation.rst @@ -1,13 +1,11 @@ Undercloud Installation ======================= -This section contains instructions on how to install the undercloud and how to -update components after installation. +This section contains instructions on how to install the undercloud. For update +or upgrade to a deployed undercloud see undercloud_upgrade_. .. _install_undercloud: .. include:: installing.rst -.. include:: updating.rst - -#. Proceed with :ref:`package_update` +.. _undercloud_upgrade: ../../upgrade/undercloud.html diff --git a/doc/source/install/post_deployment/post_deployment.rst b/doc/source/install/post_deployment/post_deployment.rst index 4cc0cd74..8e70e61f 100644 --- a/doc/source/install/post_deployment/post_deployment.rst +++ b/doc/source/install/post_deployment/post_deployment.rst @@ -12,8 +12,6 @@ In this chapter you will find advanced management of various |project| areas. quiesce_compute quiesce_cephstorage vm_snapshot - package_update - upgrade updating-stacks-notes build_single_image upload_single_image diff --git a/doc/source/install/developer/upgrades/ci_upgrades.rst b/doc/source/upgrade/developer/upgrades/ci_upgrades.rst similarity index 99% rename from doc/source/install/developer/upgrades/ci_upgrades.rst rename to doc/source/upgrade/developer/upgrades/ci_upgrades.rst index e4427224..f6032562 100644 --- a/doc/source/install/developer/upgrades/ci_upgrades.rst +++ b/doc/source/upgrade/developer/upgrades/ci_upgrades.rst @@ -82,7 +82,7 @@ To check the status of the Upgrades/Updates jobs, you need to click the `TripleO CI promotion jobs`_ link from `CI Status`_, where you will find the RDO cloud upgrades section: -.. image:: ../../_images/rdo_upgrades_jobs.png +.. image:: rdo_upgrades_jobs.png In this section the CI jobs have a color code, to show its current status in a glance:: @@ -143,7 +143,7 @@ for? fatal: [undercloud]: FAILED! => {"changed": true, "cmd": "set -o pipefail && /home/zuul/overcloud-upgrade.sh 2>&1 | awk '{ print strftime(\"%Y-%m-%d %H:%M:%S |\"), $0; fflush(); }' > overcloud_upgrade_console.log", - "delta": "0:00:39.175219", "end": "2017-11-14 16:55:47.124998", "failed": true, "rc": 1, + "delta": "0:00:39.175219", "end": "2017-11-14 16:55:47.124998", "failed": true, "rc": 1, "start": "2017-11-14 16:55:07.949779", "stderr": "", "stdout": "", "stdout_lines": [], "warnings": []} From this task, we can guess that something went wrong during the diff --git a/doc/source/install/developer/upgrades/fast_fw_upgrade.plantuml b/doc/source/upgrade/developer/upgrades/fast_fw_upgrade.plantuml similarity index 100% rename from doc/source/install/developer/upgrades/fast_fw_upgrade.plantuml rename to doc/source/upgrade/developer/upgrades/fast_fw_upgrade.plantuml diff --git a/doc/source/install/developer/upgrades/fast_fw_upgrade.png b/doc/source/upgrade/developer/upgrades/fast_fw_upgrade.png similarity index 100% rename from doc/source/install/developer/upgrades/fast_fw_upgrade.png rename to doc/source/upgrade/developer/upgrades/fast_fw_upgrade.png diff --git a/doc/source/install/developer/upgrades/fast_fw_upgrade.rst b/doc/source/upgrade/developer/upgrades/fast_fw_upgrade.rst similarity index 100% rename from doc/source/install/developer/upgrades/fast_fw_upgrade.rst rename to doc/source/upgrade/developer/upgrades/fast_fw_upgrade.rst diff --git a/doc/source/install/developer/upgrades/links.rst b/doc/source/upgrade/developer/upgrades/links.rst similarity index 100% rename from doc/source/install/developer/upgrades/links.rst rename to doc/source/upgrade/developer/upgrades/links.rst diff --git a/doc/source/install/developer/upgrades/major_upgrade.plantuml b/doc/source/upgrade/developer/upgrades/major_upgrade.plantuml similarity index 100% rename from doc/source/install/developer/upgrades/major_upgrade.plantuml rename to doc/source/upgrade/developer/upgrades/major_upgrade.plantuml diff --git a/doc/source/install/developer/upgrades/major_upgrade.png b/doc/source/upgrade/developer/upgrades/major_upgrade.png similarity index 100% rename from doc/source/install/developer/upgrades/major_upgrade.png rename to doc/source/upgrade/developer/upgrades/major_upgrade.png diff --git a/doc/source/install/developer/upgrades/major_upgrade.rst b/doc/source/upgrade/developer/upgrades/major_upgrade.rst similarity index 100% rename from doc/source/install/developer/upgrades/major_upgrade.rst rename to doc/source/upgrade/developer/upgrades/major_upgrade.rst diff --git a/doc/source/install/developer/upgrades/minor_update.plantuml b/doc/source/upgrade/developer/upgrades/minor_update.plantuml similarity index 100% rename from doc/source/install/developer/upgrades/minor_update.plantuml rename to doc/source/upgrade/developer/upgrades/minor_update.plantuml diff --git a/doc/source/install/developer/upgrades/minor_update.png b/doc/source/upgrade/developer/upgrades/minor_update.png similarity index 100% rename from doc/source/install/developer/upgrades/minor_update.png rename to doc/source/upgrade/developer/upgrades/minor_update.png diff --git a/doc/source/install/developer/upgrades/minor_update.rst b/doc/source/upgrade/developer/upgrades/minor_update.rst similarity index 98% rename from doc/source/install/developer/upgrades/minor_update.rst rename to doc/source/upgrade/developer/upgrades/minor_update.rst index defaa925..fcef8cb6 100644 --- a/doc/source/install/developer/upgrades/minor_update.rst +++ b/doc/source/upgrade/developer/upgrades/minor_update.rst @@ -3,7 +3,7 @@ Minor version update ==================== To get developer understanding of minor updates, first read the -:doc:`operator docs for minor updates <../../post_deployment/package_update>` +:doc:`operator docs for minor updates <../../minor_update>` and perhaps try to go through the update as an operator would, to get the basic idea. diff --git a/doc/source/install/_images/rdo_upgrades_jobs.png b/doc/source/upgrade/developer/upgrades/rdo_upgrades_jobs.png similarity index 100% rename from doc/source/install/_images/rdo_upgrades_jobs.png rename to doc/source/upgrade/developer/upgrades/rdo_upgrades_jobs.png diff --git a/doc/source/install/developer/upgrades/upgrades.rst b/doc/source/upgrade/developer/upgrades/upgrades.rst similarity index 74% rename from doc/source/install/developer/upgrades/upgrades.rst rename to doc/source/upgrade/developer/upgrades/upgrades.rst index 2d5a2995..ae6f3044 100644 --- a/doc/source/install/developer/upgrades/upgrades.rst +++ b/doc/source/upgrade/developer/upgrades/upgrades.rst @@ -1,5 +1,5 @@ -Major Upgrade/Minor Update Developer Documentation -================================================== +Developer Docs +============== This section is intended to give a better understanding of the upgrade/update process in TripleO. As well as a walkthrough for developers on the way upgrade diff --git a/doc/source/install/post_deployment/fast_forward_upgrade.rst b/doc/source/upgrade/fast_forward_upgrade.rst similarity index 98% rename from doc/source/install/post_deployment/fast_forward_upgrade.rst rename to doc/source/upgrade/fast_forward_upgrade.rst index 101668a6..94c8ab21 100644 --- a/doc/source/install/post_deployment/fast_forward_upgrade.rst +++ b/doc/source/upgrade/fast_forward_upgrade.rst @@ -12,7 +12,7 @@ overcloud. Before upgrading the undercloud to Queens, make sure you have created a valid backup of the current undercloud and overcloud. The complete backup procedure can be found on: - :doc:`undercloud backup<../controlplane_backup_restore/00_index>` + :doc:`undercloud backup<../install/controlplane_backup_restore/00_index>` Undercloud FFU upgrade ---------------------- @@ -23,7 +23,7 @@ Undercloud FFU upgrade configurations. Before performing the Fast Forward Upgrade of the undercloud in production, test it in a matching staging environment, and create a backup of the undercloud in the production environment. Please refer to - :doc:`undercloud backup<../controlplane_backup_restore/01_undercloud_backup>` + :doc:`undercloud backup<../install/controlplane_backup_restore/01_undercloud_backup>` for proper documentation on undercloud backups. The undercloud FFU upgrade consists of 3 consecutive undercloud upgrades to @@ -182,7 +182,7 @@ When moving from Newton to Queens, the setup will be changing from baremetal to containers. So as a part of the upgrade the container images for the target release should be downloaded to the Undercloud. Please see the `openstack overcloud container image prepare` -:doc:`../containers_deployment/overcloud` for more information. +:doc:`../install/containers_deployment/overcloud` for more information. The output of this step will be a Heat environment file that contains references to the latest container images. You will need to pass this file @@ -284,7 +284,7 @@ openstack overcloud ffwd-upgrade prepare of the current state, including the **undercloud** since there will be a Heat stack update performed here. The complete backup procedure can be found on: - :doc:`undercloud backup<../controlplane_backup_restore/00_index>` + :doc:`undercloud backup<../install/controlplane_backup_restore/00_index>` .. note:: @@ -637,7 +637,7 @@ Following there is a list of all the changes needed: ceph-ansible. It is possible to use the ``CephAnsibleExtraConfig`` and `CephAnsibleDisksConfig`` parameters to pass arbitrary variables to ceph-ansible, like ``devices`` and ``dedicated_devices``. See the - :doc:`TripleO Ceph config guide <../advanced_deployment/ceph_config>` + :doc:`TripleO Ceph config guide <../install/advanced_deployment/ceph_config>` The other parameters (for example ``CinderRbdPoolName``, ``CephClientUserName``, ...) will behave as they used to with puppet-ceph diff --git a/doc/source/upgrade/index.rst b/doc/source/upgrade/index.rst new file mode 100644 index 00000000..9c231bf7 --- /dev/null +++ b/doc/source/upgrade/index.rst @@ -0,0 +1,13 @@ +Upgrade, Update, FFWD Upgrade Guide +=================================== + +.. toctree:: + :maxdepth: 3 + :includehidden: + + undercloud.rst + minor_update.rst + major_upgrade.rst + fast_forward_upgrade.rst + developer/upgrades/upgrades.rst + diff --git a/doc/source/install/post_deployment/upgrade.rst b/doc/source/upgrade/major_upgrade.rst similarity index 99% rename from doc/source/install/post_deployment/upgrade.rst rename to doc/source/upgrade/major_upgrade.rst index 228373ac..e3a9b8bb 100644 --- a/doc/source/install/post_deployment/upgrade.rst +++ b/doc/source/upgrade/major_upgrade.rst @@ -20,7 +20,7 @@ as below: production environment. .. Undercloud upgrade section -.. include:: ../../install/installation/updating.rst +.. include:: undercloud.rst Upgrading the Overcloud to Queens and later ------------------------------------------- @@ -81,7 +81,7 @@ First we prepare an environment file for new container images: As part of the upgrade to Queens, the container images for the target release should be downloaded to the Undercloud. Please see the `openstack overcloud container image prepare`. - :doc:`../containers_deployment/overcloud` for more information. + :doc:`../install/containers_deployment/overcloud` for more information. The output of this step will be a Heat environment file that contains references to the latest container images. You will need to pass the path to @@ -93,7 +93,7 @@ First we prepare an environment file for new container images: In Rocky we only generate a new environment file with ``ContainerImagePrepare`` parameter at this point in the workflow. See - :doc:`container image preparation documentation<../advanced_deployment/container_image_prepare>`. + :doc:`container image preparation documentation<../install/advanced_deployment/container_image_prepare>`. for details how to generate this environment file. The file is then passed to the `upgrade prepare` command, and @@ -505,7 +505,7 @@ major-upgrade-composable-steps that come first, as described above. actions mentioned here to prepare your environment. In particular *image prepare* to generate the docker registry which you must include as one of the environment files specified below: - * :doc:`../containers_deployment/overcloud` + * :doc:`../install/containers_deployment/overcloud` .. __: @@ -566,7 +566,7 @@ major-upgrade-composable-steps that come first, as described above. ``CephAnsibleDisksConfig`` parameters to pass arbitrary variables to ceph-ansible, like ``devices`` and ``dedicated_devices``. See the `ceph-ansible scenarios`_ or the :doc:`TripleO Ceph config guide - <../advanced_deployment/ceph_config>` + <../install/advanced_deployment/ceph_config>` The other parameters (for example ``CinderRbdPoolName``, ``CephClientUserName``, ...) will behave as they used to with puppet-ceph diff --git a/doc/source/install/post_deployment/package_update.rst b/doc/source/upgrade/minor_update.rst similarity index 98% rename from doc/source/install/post_deployment/package_update.rst rename to doc/source/upgrade/minor_update.rst index 8f67cfbf..56d6eb41 100644 --- a/doc/source/install/post_deployment/package_update.rst +++ b/doc/source/upgrade/minor_update.rst @@ -36,14 +36,14 @@ the OpenStack release that you currently operate, perform these steps: Fetch latest container images to your undercloud registry and generate a Heat environment file pointing to new container images. This is done via workflow described in - :doc:`containerized deployment documentation<../containers_deployment/overcloud>`. + :doc:`containerized deployment documentation<../install/containers_deployment/overcloud>`. .. admonition:: Rocky :class: rocky Prepare an environment file with new ``ContainerImagePrepare`` parameter. This is done via a command described in - :doc:`container image preparation documentation<../advanced_deployment/container_image_prepare>`. + :doc:`container image preparation documentation<../install/advanced_deployment/container_image_prepare>`. #. **Update preparation** diff --git a/doc/source/install/installation/updating.rst b/doc/source/upgrade/undercloud.rst similarity index 94% rename from doc/source/install/installation/updating.rst rename to doc/source/upgrade/undercloud.rst index 00452b5b..b0897a5a 100644 --- a/doc/source/install/installation/updating.rst +++ b/doc/source/upgrade/undercloud.rst @@ -4,7 +4,7 @@ Updating Undercloud Components .. note:: Instack-undercloud is deprecated in Rocky cycle. Instack undercloud can only be upgraded to containerized undercloud. See - :doc:`../containers_deployment/undercloud` + :doc:`../install/containers_deployment/undercloud` for backward compatibility related information. .. note:: @@ -12,7 +12,7 @@ Updating Undercloud Components keep in mind the special cases described in :ref:`notes-for-stack-updates`. #. Before upgrading the undercloud, it is highly suggested to perform - a :doc:`backup <../controlplane_backup_restore/01_undercloud_backup>` + a :doc:`backup <../install/controlplane_backup_restore/01_undercloud_backup>` of the undercloud and validate that a restore works fine. #. Remove all Delorean repositories: @@ -33,7 +33,7 @@ Updating Undercloud Components #. Enable new Delorean repositories: - .. include:: ../repositories.txt + .. include:: ../install/repositories.txt .. We need to manually continue our list numbering here since the above "include" directive breaks the numbering. @@ -126,5 +126,5 @@ Updating Undercloud Components If you added custom OVS ports to the undercloud (e.g. in a virtual testing environment) you may need to re-add them at this point. - .. _validations: ../validations/validations.html#running-a-group-of-validations + .. _validations: ../install/validations/validations.html#running-a-group-of-validations .. _tripleo-validations: https://github.com/openstack/tripleo-validations/tree/master/validations