From 159cce3c4a9cde524a44a95212a6a9fc75b43ff0 Mon Sep 17 00:00:00 2001 From: Jose Luis Franco Arza Date: Fri, 29 Sep 2017 11:41:57 +0200 Subject: [PATCH] Unify undercloud upgrade steps The steps needed to upgrade the undercloud were specified in two different files. This commit updates the steps to cover O to P from commit 496223 in the 'Undercloud Installation' section and reuses that doc file for the 'Upgrading to a Next Major Release'. As an addition, a new class 'otop' has been added to include specific documentation sections when upgrading from Ocata to Pike. Change-Id: I9097ca11a95f94c5eaf580fb8a82b3173d606a5d --- _custom/custom.css | 1 + _templates/layout.html | 1 + .../install/installation/installation.rst | 1 + doc/source/install/installation/updating.rst | 79 ++++++++++---- .../install/post_deployment/upgrade.rst | 102 +----------------- 5 files changed, 64 insertions(+), 120 deletions(-) diff --git a/_custom/custom.css b/_custom/custom.css index 15e21c6c..6a4b0226 100644 --- a/_custom/custom.css +++ b/_custom/custom.css @@ -72,6 +72,7 @@ .ltom {background: #dee;} .mton {background: #ded;} .ntoo {background: #edd;} +.otop {background: #dfb;} .validations {background: #fdd;} .optional {background: #ffe;} diff --git a/_templates/layout.html b/_templates/layout.html index 47912a4c..6912afb5 100644 --- a/_templates/layout.html +++ b/_templates/layout.html @@ -54,6 +54,7 @@ diff --git a/doc/source/install/installation/installation.rst b/doc/source/install/installation/installation.rst index 553f0be9..cb450b79 100644 --- a/doc/source/install/installation/installation.rst +++ b/doc/source/install/installation/installation.rst @@ -8,3 +8,4 @@ update components after installation. .. include:: updating.rst +#. Proceed with :ref:`package_update` diff --git a/doc/source/install/installation/updating.rst b/doc/source/install/installation/updating.rst index 990c1d96..45da72db 100644 --- a/doc/source/install/installation/updating.rst +++ b/doc/source/install/installation/updating.rst @@ -3,9 +3,19 @@ Updating Undercloud Components You can upgrade any packages that are installed on the undercloud machine. -#. Remove all Delorean repositories:: +#. Remove all Delorean repositories: + + .. note:: + + You may wish to backup your current repos before disabling them:: + + mkdir /home/stack/REPOBACKUP + sudo mv /etc/yum.repos.d/delorean* /home/stack/REPOBACKUP + + :: + + sudo rm /etc/yum.repos.d/delorean* - sudo rm /etc/yum.repos.d/delorean* #. Enable new Delorean repositories: @@ -18,38 +28,67 @@ You can upgrade any packages that are installed on the undercloud machine. sudo yum clean all -#. Stop all OpenStack-related services if upgrading to Ocata or an older release. - In Pike and later releases this step is handled by the undercloud upgrade - process and should not be done by the user. +#. Update required package: - .. admonition:: Stable Branch - :class: stable + .. admonition:: Validations + :class: validations - Stop services so that they are not restarted by packaging scripts - when they are updated. The service restarts will be handled by the - undercloud upgrade command after new configuration has been applied.:: + It is strongly recommended that you validate the state of your undercloud + before starting any upgrade operations. The tripleo-validations_ repo has + some 'pre-upgrade' validations that you can execute by following the + instructions at validations_ to execute the "pre-upgrade" group:: + + mistral execution-get-output $(openstack workflow execution create -f value -c ID tripleo.validations.v1.run_groups '{"group_names": ["pre-upgrade"]}') + + .. admonition:: Newton to Ocata + :class: ntoo + + The following commands need to be run before the undercloud upgrade:: sudo systemctl stop openstack-* sudo systemctl stop neutron-* sudo systemctl stop openvswitch sudo systemctl stop httpd + sudo yum -y update instack-undercloud openstack-puppet-modules openstack-tripleo-common -#. Update the TripleO CLI package:: + .. admonition:: Ocata to Pike + :class: otop - sudo yum -y update python-tripleoclient + .. admonition:: Ceph + :class: ceph - .. admonition:: Ceph - :class: ceph + Prior to Pike, TripleO deployed Ceph with puppet-ceph. With the + Pike release it is possible to use TripleO to deploy Ceph with + either ceph-ansible or puppet-ceph, though puppet-ceph is + deprecated. To use ceph-ansible, the CentOS Storage SIG Ceph + repository must be enabled on the undercloud and the + ceph-ansible package must then be installed:: - If you are using Pike or newer and Ceph was deployed in the - overcloud, update ceph-ansible on the undercloud:: + sudo yum -y install --enablerepo=extras centos-release-ceph-jewel + sudo yum -y install ceph-ansible + + + Update TripleO CLI package:: + + sudo yum -y update python-tripleoclient - sudo yum -y update ceph-ansible #. Run the undercloud upgrade command. This command will upgrade all packages and use puppet to apply new configuration and restart all OpenStack - services.:: + services:: - openstack undercloud upgrade + openstack undercloud upgrade -#. Proceed with :ref:`package_update`. + .. note:: + + You may wish to use time and capture the output to a file for any debug:: + + time openstack undercloud upgrade 2>&1 | tee undercloud_upgrade.log + + .. note:: + + 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 + .. _tripleo-validations: https://github.com/openstack/tripleo-validations/tree/master/validations diff --git a/doc/source/install/post_deployment/upgrade.rst b/doc/source/install/post_deployment/upgrade.rst index b1c97d33..57a44f50 100644 --- a/doc/source/install/post_deployment/upgrade.rst +++ b/doc/source/install/post_deployment/upgrade.rst @@ -23,106 +23,8 @@ Note that there are version specific caveats and notes which are pointed out as it in a matching staging environment, and create a backup of the production environment. - -Upgrading the Undercloud ------------------------- - -1. Disable the old OpenStack release repositories and enable new - release repositories on the undercloud: - - Backup and disable current repos. Note that the repository files might be - named differently depending on your installation:: - - mkdir /home/stack/REPOBACKUP - sudo mv /etc/yum.repos.d/delorean* /home/stack/REPOBACKUP/ - - Get and enable new repos for `NEW_VERSION`: - - .. include:: ../repositories.txt - -2. Run undercloud upgrade: - - .. note:: - - It is strongly recommended that you validate the state of your undercloud - before starting any upgrade operations. The tripleo-validations_ repo has - some 'pre-upgrade' validations that you can execute by following the - instructions at validations_ to execute the "pre-upgrade" group:: - - openstack workflow execution create tripleo.validations.v1.run_groups '{"group_names": ["pre-upgrade"]}' - mistral execution-get-output $id_returned_above - - .. admonition:: Mitaka to Newton - :class: mton - - In the first release of instack-undercloud newton(5.0.0), the undercloud - telemetry services are **disabled** by default. In order to maintain the - telemetry services during the mitaka to newton upgrade the operator must - explicitly enable them **before** running the undercloud upgrade. This - is done by adding:: - - enable_telemetry = true - - in the [DEFAULT] section of the undercloud.conf configuration file. - - If you are using any newer newton release, this option is switched back - to **enabled** by default to make upgrade experience better. Hence, if - you are using a later newton release you don't need to explicitly enable - this option. - - .. admonition:: Ocata to Pike - :class: mton - - Prior to Pike, TripleO deployed Ceph with puppet-ceph. With the - Pike release it is possible to use TripleO to deploy Ceph with - either ceph-ansible or puppet-ceph, though puppet-ceph is - deprecated. To use ceph-ansible, the CentOS Storage SIG Ceph - repository must be enabled on the undercloud and the - ceph-ansible package must then be installed:: - - sudo yum -y install --enablerepo=extras centos-release-ceph-jewel - sudo yum -y install ceph-ansible - - It is not yet possible to migrate an existing puppet-ceph - deployment to a ceph-ansible deployment. Only new deployments - are currently possible with ceph-ansible. - - .. admonition:: Newton to Ocata - :class: ntoo - - The following commands need to be run before the undercloud upgrade:: - - sudo systemctl stop openstack-* - sudo systemctl stop neutron-* - sudo systemctl stop httpd - sudo yum -y update instack-undercloud openstack-puppet-modules openstack-tripleo-common - - The following command will upgrade the undercloud:: - - sudo yum -y update python-openstackclient python-tripleoclient ceph-ansible - openstack undercloud upgrade - - Once the undercloud upgrade is fully completed you may - remove the older mysql backup folder /home/stack/mysql-backup - -.. note:: - - You may wish to use time and capture the output to a file for any debug:: - - time openstack undercloud upgrade 2>&1 | tee undercloud_upgrade.log - -.. note:: - - 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 -.. _tripleo-validations: https://github.com/openstack/tripleo-validations/tree/master/validations - -.. note:: - - It is not necessary to update ceph-ansible if Ceph is not used in - the overcloud. +.. Undercloud upgrade section +.. include:: ../../install/installation/updating.rst Upgrading the Overcloud to Ocata or Pike -------------------------------------------