From bf6132bf5dedf4b49989d6dde5b5d7e46f89b218 Mon Sep 17 00:00:00 2001 From: Emilien Macchi Date: Wed, 8 Jan 2020 12:12:35 -0500 Subject: [PATCH] Initial documentation for tripleo-container-manage role Change-Id: Id60123cdeb921879cf0b92288dc7bc3a5d4ef599 (cherry picked from commit f5139d4dccc149f09cc5b0330892a25d50f36329) --- .../roles/role-tripleo-container-manage.rst | 134 ++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/doc/source/roles/role-tripleo-container-manage.rst b/doc/source/roles/role-tripleo-container-manage.rst index 3593307c0..c5e040285 100644 --- a/doc/source/roles/role-tripleo-container-manage.rst +++ b/doc/source/roles/role-tripleo-container-manage.rst @@ -4,3 +4,137 @@ Role - tripleo-container-manage .. ansibleautoplugin:: :role: tripleo_ansible/roles/tripleo-container-manage + +Usage +~~~~~ + +Note that right now, only Podman is supported by this role. Docker support is +in the roadmap though. + +This Ansible role allows to do the following tasks: + +* Collect container configs data, generated by TripleO Heat Templates. + This data is used as a source of truth on which configuration we expect to + apply with this role. It means that if a container is already managed by + this role, no matter its state now, the configs data will reconfigure the + container if needed. + +* Manage systemd shutdown files. + It takes care of cleaning up the Paunch services and files and create + the TripleO Container systemd service, required for service ordering when + it comes to shutdown or start a node. It also manages the netns-placeholder + service. + +* Delete containers that aren't needed anymore or that will need to be + re-configured. It uses a custom filter, named needs_delete() which has a set + of rules which allow to determine if whether or not the container needs to be + deleted. + These reasons will make the containers not deleted: + + * The container is not managed by tripleo_ansible. + + * The container config_id doesn't match with the one in input. + + Once the previous conditions checked, then these reasons will make the + containers deleted: + + * The container has no config_data. + + * The container has a config_data which doesn't match the one in input. + + Note that when a container is removed, the role also disable and remove + the systemd services and healtchecks if present. + +* Create containers in a specific order defined by start_order container + config, where default is 0. + + * If the container is an exec, we'll run a dedicated playbook for execs, + using async so multiple execs can be run at the same time. + + * Otherwise, the `podman_container`_ is used, in async, to create the + containers. + If the container has a `restart` policy, we'll configure the systemd + service. + If the container has a `healthcheck` script, we'll configure the systemd + healthcheck service. + + Note: `tripleo_container_manage_concurrency` parameter is set to 1 by + default, and putting higher value than 2 can be expose issue with Podman + locks. + + Here is an example of a playbook: + +.. code-block:: YAML + + - name: Manage step_1 containers using tripleo-ansible + block: + - name: "Manage containers for step 1 with tripleo-ansible" + include_role: + name: tripleo-container-manage + vars: + tripleo_container_manage_systemd_order: true + tripleo_container_manage_config: "/var/lib/tripleo-config/container-startup-config/step_1" + tripleo_container_manage_config_id: "tripleo_step1" + +Roles variables +~~~~~~~~~~~~~~~ + ++------------------------------------------------+-----------------------------+----------------------------+ +| Name | Default Value | Description | ++================================================+=============================+============================+ +| tripleo_container_manage_cli | podman | Container CLI | ++------------------------------------------------+-----------------------------+----------------------------+ +| tripleo_container_manage_concurrency | 1 | Number of containers | +| | | managed at same time | ++------------------------------------------------+-----------------------------+----------------------------+ +| tripleo_container_manage_config | /var/lib/tripleo-config/ | Container config path | ++------------------------------------------------+-----------------------------+----------------------------+ +| tripleo_container_manage_config_id | tripleo | Config ID | ++------------------------------------------------+-----------------------------+----------------------------+ +| tripleo_container_manage_config_patterns | `hashed-*.json` | Bash REGEX to find configs | ++------------------------------------------------+-----------------------------+----------------------------+ +| tripleo_container_manage_debug | false | Debug toggle | ++------------------------------------------------+-----------------------------+----------------------------+ +| tripleo_container_manage_healthcheck_disable | false | Allow to disable | +| | | Healthchecks | ++------------------------------------------------+-----------------------------+----------------------------+ +| tripleo_container_manage_log_path | /var/log/containers/stdouts | Containers stdouts path | ++------------------------------------------------+-----------------------------+----------------------------+ +| tripleo_container_manage_systemd_order | false | Manage systemd shutdown | +| | | ordering | ++------------------------------------------------+-----------------------------+----------------------------+ + +Check mode +~~~~~~~~~~ + +If Ansible is in check mode, no container will be removed nor created, +however at the end of the playbook a list of commands will be displayed to show +what would have been run. +This is useful for debug purposes, as it was something that one could do with +`paunch debug` command. + +Example with one container +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To manage a single container, you need to know 2 things: + +* At which step the container is deployed. + +* The name of the generated JSON file for container config. + +Here is an example of a playbook to manage HAproxy container at step 1: + +.. code-block:: YAML + + - name: Manage step_1 containers using tripleo-ansible + block: + - name: "Manage HAproxy container at step 1 with tripleo-ansible" + include_role: + name: tripleo-container-manage + vars: + tripleo_container_manage_systemd_order: true + tripleo_container_manage_config_patterns: 'hashed-haproxy.json' + tripleo_container_manage_config: "/var/lib/tripleo-config/container-startup-config/step_1" + tripleo_container_manage_config_id: "tripleo_step1" + +.. _podman_container: https://docs.openstack.org/tripleo-ansible/latest/modules/modules-podman_container.html