From 78dfa05258e88026fec7e6a04e29d7192300a7fd Mon Sep 17 00:00:00 2001 From: Will Miller Date: Fri, 14 Sep 2018 11:59:10 +0000 Subject: [PATCH] Update documentation * Improve comments in tenks_update_state * Add limitations section to README * Add hosts blurb to README * Add reconfiguration blurb to README --- README.md | 33 ++++++++++++++++++++ ansible/action_plugins/tenks_update_state.py | 13 ++++++-- 2 files changed, 43 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 11d5cbd..2033467 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,22 @@ installed inside it, Tenks' role dependencies can be installed by `ansible-galaxy install --role-file=requirements.yml --roles-path=ansible/roles/`. +### Hosts + +Tenks uses Ansible inventory to manage hosts. A multi-host setup is therefore +supported, although the default hosts configuration will deploy an all-in-one +setup on the host where the `ansible-playbook` command is executed +(`localhost`). + +* Configuration management of the Tenks cluster is always performed on + `localhost`. +* The `hypervisors` group should not directly contain any hosts. Its sub-groups + must contain one or more system. Systems in its sub-groups will host a subset + of the noides deployed by Tenks. + + * The `libvirt` group is a sub-group of `hypervisors`. Systems in this + group will act as hypervisors using the Libvirt provider. + ### Configuration An override file should be created to configure Tenks. Any variables specified @@ -69,6 +85,23 @@ want to run. The current playbooks can be seen in the Ansible structure diagram in the *Development* section. Bear in mind that you will have to set `cmd` in your override file if you are running any of the sub-playbooks individually. +Once a cluster has been deployed, it can be reconfigured by modifying the Tenks +configuration and rerunning `deploy.yml`. Node specs can be changed (including +increasing/decreasing the number of nodes); node types can also be +reconfigured. Existing nodes will be preserved where possible. + +## Limitations + +The following is a non-exhaustive list of current known limitations of Tenks: + +* When using the Libvirt provider (currently the only provider), Tenks + hypervisors cannot co-exist with a containerised Libvirt daemon (for example, + as deployed by Kolla in the nova-libvirt container). Tenks will configure an + uncontainerised Libvirt daemon instance on the hypervisor, and this may + conflict with an existing containerised daemon. A workaround is to disable + the Nova virtualised compute service on each Tenks hypervisor if it is + present (for example, `docker stop nova_libvirt`) before running Tenks. + ## Development A diagram representing the Ansible structure of Tenks can be seen below. Blue diff --git a/ansible/action_plugins/tenks_update_state.py b/ansible/action_plugins/tenks_update_state.py index 8c1e162..2efa503 100644 --- a/ansible/action_plugins/tenks_update_state.py +++ b/ansible/action_plugins/tenks_update_state.py @@ -28,7 +28,11 @@ import six class ActionModule(ActionBase): def run(self, tmp=None, task_vars=None): """ - Schedule specifications of nodes by type onto hypervisors. + Produce a dict of Tenks state. + + Actions include: + * Generating indices for physical networks for each hypervisor. + * Scheduling specifications of nodes by type onto hypervisors. The following task vars are accepted: :hypervisor_vars: A dict of hostvars for each hypervisor, keyed @@ -40,8 +44,11 @@ class ActionModule(ActionBase): node names. :vol_name_prefix: A string with which to prefix all sequential volume names. - :returns: A dict containing lists of node details, keyed by the - hostname of the hypervisor to which they are scheduled. + :state: A dict of existing Tenks state (as produced by a previous + run of this module), to be taken into account in this run. + Optional. + :returns: A dict of Tenks state for each hypervisor, keyed by the + hostname of the hypervisor to which the state refers. """ result = super(ActionModule, self).run(tmp, task_vars) # Initialise our return dict.