===============================
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.
  If a container is meant to exit after running a script (defined in
  EntryPoint), we can check its return code and fail if the code isn't
  expected. It can be done with `tripleo_container_manage_valid_exit_code`.
  If defined to a list of integers, the role will wait for the container to be
  exited and then checks the return code.

  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       | `*.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                   |
+------------------------------------------------+-----------------------------+----------------------------+
| tripleo_container_manage_config_overrides      | {}                          | Allows to override any     |
|                                                |                             | container configuration    |
+------------------------------------------------+-----------------------------+----------------------------+
| tripleo_container_manage_clean_orphans         | true                        | Option to clean orphans    |
+------------------------------------------------+-----------------------------+----------------------------+
| tripleo_container_manage_valid_exit_code       | []                          | Allow to check if a        |
|                                                |                             | container returned the     |
|                                                |                             | exit code in parameter.    |
|                                                |                             | Must be a list. e.g. [0,3] |
+------------------------------------------------+-----------------------------+----------------------------+

Debug
~~~~~

The role allows you to perform specific actions on a given container.
This can be used to:

* Run a container with a specific one-off configuration.
* Output the container commands that are run to to manage containers lifecycle.
* Output the changes that would have been made on containers by Ansible.

.. note:: 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 which
overrides the image setting in one-off.

.. code-block:: YAML

    - hosts: localhost
      become: true
      tasks:
        - 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: 'haproxy.json'
                tripleo_container_manage_config: "/var/lib/tripleo-config/container-startup-config/step_1"
                tripleo_container_manage_config_id: "tripleo_step1"
                tripleo_container_manage_clean_orphans: false
                tripleo_container_manage_config_overrides:
                  haproxy:
                    image: docker.io/tripleomaster/centos-binary-haproxy:hotfix

If Ansible is run 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.

.. code-block:: bash

    $ ansible-playbook haproxy.yaml --check

Adding the diff mode will output the changes what would have been made on
containers by Ansible.

.. code-block:: bash

    $ ansible-playbook haproxy.yaml --check --diff

The ``tripleo_container_manage_clean_orphans`` parameter is optional
and can be set to `false` to not clean orphaned containers for a
config_id. It can be used to manage a single container without
impacting other running containers with same config_id.

The ``tripleo_container_manage_config_overrides`` parameter is optional
and can be used to override a specific container attribute like the image
or the container user. The parameter takes a dictionary where each key is the
container name and its parameters that we want to override. These parameters
have to exist and are the ones that define the container configuration in
TripleO Heat Templates. Note that it doesn't write down the overrides in the
JSON file so if an update / upgrade is executed, the container will be
re-configured with the configuration that is in the JSON file.

.. _podman_container: https://docs.openstack.org/tripleo-ansible/latest/modules/modules-podman_container.html
