From 410466bb5ced328540724fda70bd14fe0197b1a9 Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Mon, 11 Nov 2019 14:11:04 +0000
Subject: [PATCH] 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 | 24 ++++++
doc/source/deployment.rst | 1 +
doc/source/upgrading.rst | 107 +++++++++++++++++---------
3 files changed, 95 insertions(+), 37 deletions(-)
diff --git a/doc/source/administration/general.rst b/doc/source/administration/general.rst
index 1a723509..55d7aadb 100644
--- a/doc/source/administration/general.rst
+++ b/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
==================================
diff --git a/doc/source/deployment.rst b/doc/source/deployment.rst
index 6f4ee6af..dda20eda 100644
--- a/doc/source/deployment.rst
+++ b/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::
diff --git a/doc/source/upgrading.rst b/doc/source/upgrading.rst
index cf0be270..ed054692 100644
--- a/doc/source/upgrading.rst
+++ b/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::
--
GitLab