Improve docs on updating the Ansible control host

Also reorder upgrade documentation to make it clear that configuration
migration is something that should be done as a preparatory task.

Change-Id: I97ada3c6fd94a9ab7b5add97e90717f2a56bc8f3
Story: 2006677
Task: 36953

doc/source/administration/general.rst

@@ -2,6 +2,30 @@
 General Administration
 ======================
 
+Updating the Control Host
+=========================
+
+There are several pieces of software and configuration that must be installed
+and synchronised on the Ansible Control host:
+
+* Kayobe configuration
+* Kayobe Python package
+* Ansible Galaxy roles
+* Kolla Ansible Python package
+
+A change to the configuration may require updating the Kolla Ansible Python
+package. Updating the Kayobe Python package may require updating the Ansible
+Galaxy roles. It's not always easy to know which of these are required, so the
+simplest option is to apply all of the following steps when any of the above
+are changed.
+
+#. :ref:`Update Kayobe configuration <upgrading-kayobe-configuration>` to the
+   required commit
+#. :ref:`Upgrade the Kayobe Python package <upgrading-kayobe>` to the required
+   version
+#. :ref:`Upgrade the Ansible control host <upgrading-control-host>` to
+   synchronise the Ansible Galaxy roles and Kolla Ansible Python package.
+
 Running Kayobe Playbooks on Demand
 ==================================
 

doc/source/deployment.rst

@@ -18,6 +18,7 @@ performed here include:
 - Install Ansible and role dependencies from Ansible Galaxy.
 - Generate an SSH key if necessary and add it to the current user's authorised
   keys.
+- Install Kolla Ansible locally at the configured version.
 
 To bootstrap the Ansible control host::
 

doc/source/upgrading.rst

@@ -12,6 +12,74 @@ Preparation
 Before you start, be sure to back up any local changes, configuration, and
 data.
 
+Migrating Kayobe Configuration
+------------------------------
+
+Kayobe configuration options may be changed between releases of kayobe. Ensure
+that all site local configuration is migrated to the target version format. If
+using the `kayobe-config <https://opendev.org/openstack/kayobe-config>`_ git
+repository to manage local configuration, this process can be managed via git.
+For example, to fetch version 1.0.0 of the configuration from the ``origin``
+remote and merge it into the current branch::
+
+    $ git fetch origin 1.0.0
+    $ git merge 1.0.0
+
+The configuration should be manually inspected after the merge to ensure that
+it is correct.  Any new configuration options may be set at this point.  In
+particular, the following options may need to be changed if not using their
+default values:
+
+* ``kolla_openstack_release``
+* ``kolla_sources``
+* ``kolla_build_blocks``
+* ``kolla_build_customizations``
+
+Once the configuration has been migrated, it is possible to view the global
+variables for all hosts::
+
+    (kayobe) $ kayobe configuration dump
+
+The output of this command is a JSON object mapping hosts to their
+configuration.  The output of the command may be restricted using the
+``--host``, ``--hosts``, ``--var-name`` and ``--dump-facts`` options.
+
+If using the ``kayobe-env`` environment file in ``kayobe-config``, this should
+also be inspected for changes and modified to suit the local ansible control
+host environment if necessary. When ready, source the environment file::
+
+    $ source kayobe-env
+
+The `Kayobe release notes <https://docs.openstack.org/releasenotes/kayobe/>`__
+provide information on each new release. In particular, the *Upgrade Notes* and
+*Deprecation Notes* sections provide information that might affect the
+configuration migration.
+
+All changes made to the configuration should be committed and pushed to the
+hosting git repository.
+
+.. _upgrading-kayobe-configuration:
+
+Updating Kayobe Configuration
+=============================
+
+Ensure that the Kayobe configuration is checked out at the required commit.
+
+First, ensure that there are no uncommitted local changes to the repository::
+
+    $ cd <base_path>/src/kayobe-config/
+    $ git status
+
+Pull down changes from the hosting repository. For example, to fetch changes
+from the ``master`` branch of the ``origin`` remote::
+
+    $ git checkout master
+    $ git pull --ff-only origin master
+
+Adjust this procedure to suit your environment.
+
+.. _upgrading-kayobe:
+
 Upgrading Kayobe
 ================
 
@@ -74,43 +142,7 @@ see :ref:`installation-editable` for details)::
     (kayobe) $ cd <base_path>/src/kayobe
     (kayobe) $ pip install -U -e .
 
-Migrating Kayobe Configuration
-------------------------------
-
-Kayobe configuration options may be changed between releases of kayobe. Ensure
-that all site local configuration is migrated to the target version format. If
-using the `kayobe-config <https://opendev.org/openstack/kayobe-config>`_ git
-repository to manage local configuration, this process can be managed via git.
-For example, to fetch version 1.0.0 of the configuration from the ``origin``
-remote and merge it into the current branch::
-
-    $ git fetch origin 1.0.0
-    $ git merge 1.0.0
-
-The configuration should be manually inspected after the merge to ensure that
-it is correct.  Any new configuration options may be set at this point.  In
-particular, the following options may need to be changed if not using their
-default values:
-
-* ``kolla_openstack_release``
-* ``kolla_sources``
-* ``kolla_build_blocks``
-* ``kolla_build_customizations``
-
-Once the configuration has been migrated, it is possible to view the global
-variables for all hosts::
-
-    (kayobe) $ kayobe configuration dump
-
-The output of this command is a JSON object mapping hosts to their
-configuration.  The output of the command may be restricted using the
-``--host``, ``--hosts``, ``--var-name`` and ``--dump-facts`` options.
-
-If using the ``kayobe-env`` environment file in ``kayobe-config``, this should
-also be inspected for changes and modified to suit the local ansible control
-host environment if necessary. When ready, source the environment file::
-
-    $ source kayobe-env
+.. _upgrading-control-host:
 
 Upgrading the Ansible Control Host
 ==================================
@@ -121,6 +153,7 @@ performed here include:
 - Install updated Ansible role dependencies from Ansible Galaxy.
 - Generate an SSH key if necessary and add it to the current user's authorised
   keys.
+- Upgrade Kolla Ansible locally to the configured version.
 
 To upgrade the Ansible control host::