From 2c27566d8cf31f699856abd8e0eebe2643300a8b Mon Sep 17 00:00:00 2001
From: Mark Goddard <mark@stackhpc.com>
Date: Thu, 12 Apr 2018 17:32:37 +0100
Subject: [PATCH] Add documentation for custom ansible playbooks
Change-Id: Ia00bd15d037ce3f1db66a953f9c327074e509627
Story: 2001663
Task: 12599
---
doc/source/custom-ansible-playbooks.rst | 122 ++++++++++++++++++++++++
doc/source/index.rst | 1 +
tox.ini | 2 +-
3 files changed, 124 insertions(+), 1 deletion(-)
create mode 100644 doc/source/custom-ansible-playbooks.rst
diff --git a/doc/source/custom-ansible-playbooks.rst b/doc/source/custom-ansible-playbooks.rst
new file mode 100644
index 000000000..0b77c00b5
--- /dev/null
+++ b/doc/source/custom-ansible-playbooks.rst
@@ -0,0 +1,122 @@
+========================
+Custom Ansible Playbooks
+========================
+
+Kayobe supports running custom Ansible playbooks located outside of the kayobe
+project. This provides a flexible mechanism for customising a control plane.
+Access to the kayobe variables is possible, ensuring configuration does not
+need to be repeated.
+
+Kayobe Custom Playbook API
+==========================
+
+Explicitly allowing users to run custom playbooks with access to the kayobe
+variables elevates the variable namespace and inventory to become an interface.
+This raises questions about the stability of this interface, and the guarantees
+it provides.
+
+The following guidelines apply to the custom playbook API:
+
+* Only variables defined in the kayobe configuration files under ``etc/kayobe``
+ are supported.
+* The groups defined in ``etc/kayobe/inventory/groups`` are supported.
+* Any change to a supported variable (rename, schema change, default value
+ change, or removal) or supported group (rename or removal) will follow a
+ deprecation period of one release cycle.
+* Kayobe's internal roles may not be used.
+
+Note that these are guidelines, and exceptions may be made where appropriate.
+
+Running Custom Ansible Playbooks
+================================
+
+Run one or more custom ansible playbooks::
+
+ (kayobe) $ kayobe playbook run <playbook>[, <playbook>...]
+
+Playbooks do not by default have access to the Kayobe playbook group variables,
+filter plugins, and test plugins, since these are relative to the current
+playbook's directory. This can be worked around by creating symbolic links to
+the Kayobe repository from the Kayobe configuration.
+
+Packaging Custom Playbooks With Configuration
+=============================================
+
+The kayobe project encourages its users to manage configuration for a cloud
+using version control, based on the `kayobe-config repository
+<https://github.com/stackhpc/kayobe-config>`_. Storing custom Ansible
+playbooks in this repository makes a lot of sense, and kayobe has special
+support for this.
+
+It is recommended to store custom playbooks in
+``$KAYOBE_CONFIG_PATH/ansible/``. Roles located in
+``$KAYOBE_CONFIG_PATH/ansible/roles/`` will be automatically available to
+playbooks in this directory.
+
+With this directory layout, the following commands could be used to create
+symlinks that allow access to Kayobe's filter plugins, group variables and test
+plugins:
+
+.. code-block:: console
+
+ cd ${KAYOBE_CONFIG_PATH}/ansible/
+ ln -s ../../../../kayobe/ansible/filter_plugins/ filter_plugins
+ ln -s ../../../../kayobe/ansible/group_vars/ group_vars
+ ln -s ../../../../kayobe/ansible/test_plugins/ test_plugins
+
+These symlinks can even be committed to the kayobe-config Git repository.
+
+Ansible Galaxy
+--------------
+
+Ansible Galaxy provides a means for sharing Ansible roles. Kayobe
+configuration may provide a Galaxy requirements file that defines roles to be
+installed from Galaxy. These roles may then be used by custom playbooks.
+
+Galaxy role dependencies may be defined in
+``$KAYOBE_CONFIG_PATH/ansible/requirements.yml``. These roles will be
+installed in ``$KAYOBE_CONFIG_PATH/ansible/roles/`` when bootstrapping the
+control host::
+
+ (kayobe) $ kayobe control host bootstrap
+
+And updated when upgrading the control host::
+
+ (kayobe) $ kayobe control host upgrade
+
+Example
+=======
+
+The following example adds a ``foo.yml`` playbook to a set of kayobe
+configuration. The playbook uses a Galaxy role, ``bar.baz``.
+
+Here is the kayobe configuration repository structure::
+
+ etc/kayobe/
+ ansible/
+ foo.yml
+ requirements.yml
+ roles/
+ bifrost.yml
+ ...
+
+Here is the playbook, ``ansible/foo.yml``::
+
+ ---
+ - hosts: controllers
+ roles:
+ - name: bar.baz
+
+Here is the Galaxy requirements file, ``ansible/requirements.yml``::
+
+ ---
+ - bar.baz
+
+We should first install the Galaxy role dependencies, to download the
+``bar.baz`` role::
+
+ (kayobe) $ kayobe control host bootstrap
+
+Then, to run the ``foo.yml`` playbook::
+
+ (kayobe) $ kayobe playbook run $KAYOBE_CONFIG_PATH/ansible/foo.yml
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 9e90e5b06..558196195 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -35,6 +35,7 @@ Advanced Documentation
:maxdepth: 2
control-plane-service-placement
+ custom-ansible-playbooks
Developer Documentation
-----------------------
diff --git a/tox.ini b/tox.ini
index 922c496ba..eb1014fda 100644
--- a/tox.ini
+++ b/tox.ini
@@ -106,7 +106,7 @@ deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://git.openstack.org/cgit/openstack/requirements/plain/upper-constraints.txt?h=stable/queens}
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
-commands = sphinx-build -b html doc/source doc/build/html
+commands = sphinx-build -W -b html doc/source doc/build/html
[testenv:debug]
commands = oslo_debug_helper {posargs}