Browse Source

Merge "Initial documentation for tripleo-container-manage role" into stable/train

changes/20/706620/1
Zuul Gerrit Code Review 2 weeks ago
parent
commit
51d4031818
1 changed files with 134 additions and 0 deletions
  1. +134
    -0
      doc/source/roles/role-tripleo-container-manage.rst

+ 134
- 0
doc/source/roles/role-tripleo-container-manage.rst View File

@@ -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

Loading…
Cancel
Save