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