From 410466bb5ced328540724fda70bd14fe0197b1a9 Mon Sep 17 00:00:00 2001 From: Mark Goddard 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 1a7235096..55d7aadb4 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 ` to the + required commit +#. :ref:`Upgrade the Kayobe Python package ` to the required + version +#. :ref:`Upgrade the Ansible 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 6f4ee6afc..dda20eda2 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 cf0be2707..ed0546920 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 `_ 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 `__ +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 /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 /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 `_ 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::