Add documentation for container hotfix playbook

Author: Alex-Welsh

doc/source/operations/hotfix-playbook.rst

@@ -0,0 +1,69 @@
+===============
+Hotfix Playbook
+===============
+
+Using the Container Hotfix Playbook
+===================================
+
+The StackHPC Kayobe configuration contains a playbook called
+``hotfix-containers.yml`` which can be used to execute commands on, and copy
+files into, a given set of containers.
+
+This playbook will first copy across any hotfix files, and then run the
+hotfix command. If either of these are not specified, the corresponding step
+will be skipped.
+
+This playbook is designed for use in high-severity hotfixes ONLY and should not
+be used for regular operations.
+
+The playbook can be invoked with:
+
+.. code-block:: console
+
+  kayobe playbook run ${KAYOBE_CONFIG_PATH}/ansible/hotfix-containers.yml
+
+Playbook variables:
+-------------------
+
+* ``container_hotfix_command``: A command to run on each of the target
+  containers. Default is an empty string.
+
+* ``container_hotfix_files``: A list of files to copy into each target
+  container. Consists of a list of dicts with keys ``src`` and ``dest``.
+  Default is an empty list.
+
+* ``container_hotfix_container_regex``: Regex to match container names against.
+  Must match the entire name e.g. "nova" or "nova*" will result in only
+  matching a single container called "nova". To properly match every container
+  starting with "nova", the regex must be "nova.*" Default is an empty string.
+
+* ``container_hotfix_restart_containers``: Whether to restart containers after
+  applying the hotfix. Default is False.
+
+* ``container_hotfix_become``: Create files and exec as root in the target
+  containers. Default is False.
+
+
+It is strongly recommended that you write your container_hotfix_* variables
+to a file, then add them as an extra var. e.g:
+
+.. code-block:: console
+
+  kayobe playbook run ${KAYOBE_CONFIG_PATH}/ansible/hotfix-containers.yml -e "@~/vars.yml"
+
+
+Example Variables file
+----------------------
+
+.. code-block:: yaml
+
+    ---
+    container_hotfix_command: "/tmp/quick-fix.sh"
+    container_hotfix_files:
+      - src: "~/quick-fix.sh"
+        dest: "/tmp/quick-fix.sh"
+      - src: "/home/stackhpc/new_nova_conf.conf"
+        dest: "/etc/nova/nova.conf"
+    container_hotfix_container_regex: "nova.*"
+    container_hotfix_restart_containers: True
+    container_hotfix_become: True

doc/source/operations/index.rst

@@ -9,3 +9,4 @@ This guide is for operators of the StackHPC Kayobe configuration project.
 
    rabbitmq
    octavia
+   hotfix-containers

etc/kayobe/ansible/hotfix-containers.yml

@@ -3,55 +3,8 @@
 # If you're considering using this for regular operations, please consider
 # developing a more suitable solution instead.
 #
-# This playbook will first copy across any hotfix files, and then run the
-# hotfix command. If either of these are not specified, the corresponding step
-# will be skipped.
-#
-# It is strongly recommended that you write your container_hotfix_* variables
-# to a file, then add them as an extra var. e.g:
-# kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/hotfix-containers.yml -e "@~/vars.yml"
-
-# Vars:
-# container_hotfix_command
-#   Type:    string
-#   Desc:    Command to run in a set of containers
-#   Default: ""
-#
-# container_hotfix_files
-#   Type:    list of dict containing src,dest
-#   Desc:    Files to copy into the destination containers
-#   Default: []
-#
-# container_hotfix_container_regex
-#   Type:    string
-#   Desc:    Regex to match container names against. Must match the entire name
-#            e.g. "nova" or "nova*" will result in only matching a single
-#            container called "nova". To properly match every container
-#            starting with "nova", the regex must be "nova.*"
-#   Default: ""
-#
-# container_hotfix_restart_containers
-#   Type:    bool
-#   Desc:    Whether to restart containers after applying the hotfix
-#   Default: False
-#
-# container_hotfix_become
-#   Type:    bool
-#   Desc:    Create files and exec as root in the destination container(s)
-#   Default: False
-
-# Example vars.yml:
-# ---
-# container_hotfix_command: "/tmp/quick-fix.sh"
-# container_hotfix_files:
-#   - src: "~/quick-fix.sh"
-#     dest: "/tmp/quick-fix.sh"
-#   - src: "/home/stackhpc/new_nova_conf.conf"
-#     dest: "/etc/nova/nova.conf"
-# container_hotfix_container_regex: "nova.*"
-# container_hotfix_restart_containers: True
-# container_hotfix_become: True
-
+# See https://stackhpc-kayobe-config.readthedocs.io/en/stackhpc-yoga/operations/hotfix-containers.html
+# for more information.
 
 - name: Hotfix containers
   hosts: overcloud