.. _example_013:

013 Tags and custom groups.
---------------------------

Extending example 010.

.. contents:: Table of Contents
   :depth: 2


Tree
^^^^

::

   shell> tree .
   .
   ├── ansible.cfg
   ├── hosts
   │   ├── 01_iocage.yml
   │   └── 02_iocage.yml
   ├── host_vars
   │   ├── iocage_01
   │   │   └── iocage.yml
   │   └── iocage_02
   │       └── iocage.yml
   ├── iocage-hosts.ini
   ├── pb-all.yml
   ├── pb-ansible-client.yml
   ├── pb-iocage-base.yml
   ├── pb-iocage-clone.yml
   └── pb-test.yml


Synopsis
^^^^^^^^

* Use the property *notes* to create tags:

  * Add the property ``notes: "vmm={{ inventory_hostname }}"``
  * In the inventory plugin, compose *iocage_tags*
  * In the inventory plugin, create groups *vmm_\** from *iocage_tags.vmm*

* On two iocage hosts:

  * iocage_01
  * iocage_02

  In the playbook *pb-iocage-base.yml*, use the module *vbotka.freebsd.iocage* to:

  * create basejail *ansible_client*

  In the playbook *pb-iocage-clone.yml*, use the module *vbotka.freebsd.iocage* to:

  * clone 3 jails from the basejail *ansible_client*

  In the playbooks:

  * pb-all.yml
  * pb-ansible-client.yml
  * pb-test.yml

  use the inventory plugin *vbotka.freebsd.iocage* to:

  * create the inventory groups and compose variables.
  * create the dictionary *iocage_tags* from *iocage_properties.notes*
  * display hosts, composed variables, and groups.
  * comment on hosts potentially overriding each other silently.


Requirements
^^^^^^^^^^^^

* Module *vbotka.freebsd.iocage*
* Inventory *vbotka.freebsd.iocage*
* root privilege on the iocage hosts
* Activated *iocage*
* Fetched releases

hosts/01_iocage.yml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Enable ``get_properties: True`` to create the dictionary *iocage_properties*. Then, the dictionary
*iocage_tags* can be created from *iocage_properties.notes*

.. literalinclude:: hosts/01_iocage.yml
    :language: yaml
    :emphasize-lines: 6,12,21

hosts/02_iocage.yml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Enable `'get_properties: True'`

.. literalinclude:: hosts/02_iocage.yml
    :language: yaml
    :emphasize-lines: 6,12,21

host_vars/iocage_01/iocage.yml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: host_vars/iocage_01/iocage.yml
    :language: yaml

host_vars/iocage_02/iocage.yml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: host_vars/iocage_02/iocage.yml
    :language: yaml

.. note:: The structure of *notes* is up to you. If you change it fit the declaration of
          *iocage_tags* in the inventory.

Playbook *pb-iocage-base.yml*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: pb-iocage-base.yml
    :language: yaml

Playbook output
^^^^^^^^^^^^^^^

.. literalinclude:: out/out-01.txt
    :language: bash

Playbook *pb-iocage-clone.yml*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: pb-iocage-clone.yml
    :language: yaml

Playbook output
^^^^^^^^^^^^^^^

.. literalinclude:: out/out-02.txt
    :language: bash

Playbook *pb-all.yml*
^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: pb-all.yml
    :language: yaml

Playbook output
^^^^^^^^^^^^^^^

.. literalinclude:: out/out-03.txt
    :language: bash

.. note::

   * The inventory files in *hosts* are evaluated in alphabetical order.

   * The jail *ansible_client* from *iocage_02* overrides the one from *iocage_01*

   * See the special variable `groups <https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html#term-groups>`_

Playbook *pb-ansible-client.yml*
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: pb-ansible-client.yml
    :language: yaml

Playbook output
^^^^^^^^^^^^^^^

.. literalinclude:: out/out-05.txt
    :language: bash

.. note::

   * The structure of the inventory hosts and groups is flat. The jail(host) *ansible-client* in all
     groups is the same.

   * See the special variable `group_names <https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html#term-group_names>`_

.. warning:: There are no internal checks of the hosts overriding each other. The consistency is up to you.

Playbook *pb-test.yml*
^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: pb-test.yml
    :language: yaml

Playbook output
^^^^^^^^^^^^^^^

.. literalinclude:: out/out-04.txt
    :language: bash
