From 601b94dc33e91fe2be1fc25e748a3dc1f2683e3c Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Wed, 5 Sep 2018 13:36:37 +0100
Subject: [PATCH] Add host package update to upgrade procedures

This is an optional step that may be desirable to perform prior to
upgrading Kolla containers.

Change-Id: Ibe30c5a252508a4aa1b24d9484456f90532b8af7
Story: 2003305
Task: 24257
---
 doc/source/upgrading.rst | 42 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/doc/source/upgrading.rst b/doc/source/upgrading.rst
index a41b9de13..0f64a8795 100644
--- a/doc/source/upgrading.rst
+++ b/doc/source/upgrading.rst
@@ -94,8 +94,29 @@ instead perform a targeted upgrade of specific services where necessary.
 Upgrading the Seed
 ==================
 
-Currently, upgrading the seed services is not supported.  It may however be
-necessary to upgrade some host services::
+Currently, upgrading the seed services is not supported.
+
+Upgrading Host Packages
+-----------------------
+
+Prior to upgrading the seed, it may be desirable to upgrade system packages on
+the seed host.
+
+To update all eligible packages, use ``*``, escaping if necessary::
+
+    (kayobe) $ kayobe seed host package update --packages *
+
+To only install updates that have been marked security related::
+
+    (kayobe) $ kayobe seed host package update --packages <packages> --security
+
+Note that these commands do not affect packages installed in containers, only
+those installed on the host.
+
+Upgrading Host Services
+-----------------------
+
+It may be necessary to upgrade some host services::
 
     (kayobe) $ kayobe seed host upgrade
 
@@ -110,6 +131,23 @@ should be obtained either by building them locally or pulling them from an
 image registry.  Second, the overcloud services should be replaced with new
 containers created from the new container images.
 
+Upgrading Host Packages
+-----------------------
+
+Prior to upgrading the OpenStack control plane, it may be desirable to upgrade
+system packages on the overcloud hosts.
+
+To update all eligible packages, use ``*``, escaping if necessary::
+
+    (kayobe) $ kayobe overcloud host package update --packages *
+
+To only install updates that have been marked security related::
+
+    (kayobe) $ kayobe overcloud host package update --packages <packages> --security
+
+Note that these commands do not affect packages installed in containers, only
+those installed on the host.
+
 Upgrading Host Services
 -----------------------