.. _example_020:

020 Get inventory aliases from notes
------------------------------------

Extending example :ref:`example_016`.

.. contents::
   :local:
   :depth: 1

.. index:: single: swarms; Example 020

.. index:: single: inventory alias; Example 020
.. index:: single: alias; Example 020

.. index:: single: inventory vbotka.freebsd.iocage; Example 020
.. index:: single: inventory ansible.builtin.constructed; Example 020

.. index:: single: option inventory_hostname_tag; Example 020
.. index:: single: inventory_hostname_tag; Example 020
.. index:: single: option inventory_hostname_required; Example 020
.. index:: single: inventory_hostname_required; Example 020
.. index:: single: option compose; Example 020
.. index:: single: compose; Example 020

.. index:: single: option iocage --count; Example 020


Use case
^^^^^^^^

Get the `inventory aliases`_ from the `iocage property notes`_. In the `inventory plugin
vbotka.freebsd.iocage`_, use the option ``inventory_hostname_tag`` to tell the plugin which tag to
use.

Tree
^^^^

::

  shell> tree .
  .
  ├── ansible.cfg
  ├── group_vars
  │   └── all
  │       └── swarms.yml
  ├── hosts
  │   ├── 02_iocage.yml
  │   ├── 04_iocage.yml
  │   └── 99_constructed.yml
  ├── host_vars
  │   ├── iocage_02
  │   │   └── iocage.yml
  │   └── iocage_04
  │       └── iocage.yml
  ├── iocage.ini
  ├── pb-iocage-swarms-create.yml
  ├── pb-iocage-swarms-destroy.yml
  ├── pb-test-all.yml
  └── pb-test-db.yml

Synopsis
^^^^^^^^

* At two managed nodes:

  * create jails using a template and the option ``--count``
  * at each jail, create property ``notes`` in the format ``tag1=val1 tag2=val2 ...``
  * put the inventory alias into the tag ``alias=<alias>``

* In the `inventory plugin vbotka.freebsd.iocage`_, get the inventory aliases from the tag ``alias``

* In the inventory plugin `ansible.builtin.constructed`_, create the inventory groups.

* Display the jails and groups.

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

* `inventory plugin vbotka.freebsd.iocage`_
* root privilege in the managed nodes
* templates created in :ref:`example_202`.
 
Notes
^^^^^

* The inventory files in the directory ``hosts`` are evaluated in alphabetical order.

.. seealso::

   * `Inventory aliases`_
   * `Set Jail Property`_
   * :ref:`example_016`

Templates at iocage_02
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

   [iocage_02]# iocage list -lt

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

Templates at iocage_04
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

   [iocage_04]# iocage list -lt

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

ansible.cfg
^^^^^^^^^^^

.. literalinclude:: ansible.cfg
   :language: ini

Inventory iocage.ini
^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: iocage.ini
   :language: ini

group_vars
^^^^^^^^^^

.. literalinclude:: group_vars/all/swarms.yml
   :language: yaml
   :caption:

host_vars
^^^^^^^^^

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

.. literalinclude:: host_vars/iocage_04/iocage.yml
   :language: yaml
   :caption:
  
Inventory hosts
^^^^^^^^^^^^^^^

The value of the iocage tag ``alias`` is used as the inventory alias. If the `iocage list is slow`_
use the cache.

.. literalinclude:: hosts/02_iocage.yml
   :language: yaml
   :caption:
   :emphasize-lines: 10

.. literalinclude:: hosts/04_iocage.yml
   :language: yaml
   :caption:
   :emphasize-lines: 10

.. literalinclude:: hosts/99_constructed.yml
   :language: yaml
   :caption:

Playbook pb-iocage-swarms-create.yml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: pb-iocage-swarms-create.yml
   :language: yaml

Playbook output - Create swarms
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

   (env) > ansible-playbook pb-iocage-swarms-create.yml -i iocage.ini

.. literalinclude:: out/out-03.txt
   :language: yaml
   :force:

.. hint::

   Run the below command to see the complete inventory ::

     shell> ansible-inventory -i hosts --list --yaml

Jails at iocage_02
^^^^^^^^^^^^^^^^^^

.. code-block:: console

   [iocage_02]# iocage list -l

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

Jails at iocage_04
^^^^^^^^^^^^^^^^^^

.. code-block:: console

   [iocage_04]# iocage list -l

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

Playbook pb-test-all.yml
^^^^^^^^^^^^^^^^^^^^^^^^

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

Playbook output - All groups
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

   (env) > ansible-playbook pb-test-all.yml -i hosts

.. literalinclude:: out/out-06.txt
   :language: yaml
   :force:

Playbook pb-test-db.yml
^^^^^^^^^^^^^^^^^^^^^^^

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

Playbook output - Group swarm_db
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

   (env) > ansible-playbook pb-test-db.yml -i hosts

.. literalinclude:: out/out-07.txt
   :language: yaml
   :force:

Playbook pb-iocage-swarms-destroy.yml
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: pb-iocage-swarms-destroy.yml
   :language: yaml

Playbook output - Destroy swarms
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Destroy the swarms if you don't need them any more.

.. code-block:: console

   (env) > ansible-playbook pb-iocage-swarms-destroy.yml -i iocage.ini -i hosts

.. literalinclude:: out/out-08.txt
   :language: yaml
   :force:


.. _inventory plugin vbotka.freebsd.iocage: https://galaxy.ansible.com/ui/repo/published/vbotka/freebsd/content/inventory/iocage
.. _ansible.builtin.constructed: https://docs.ansible.com/ansible/latest/collections/ansible/builtin/constructed_inventory.html
.. _inventory aliases: https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html#inventory-aliases
.. _Inventory aliases: https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html#inventory-aliases
.. _iocage property notes: https://freebsd.github.io/iocage/basic-use.html?highlight=properties#set-jail-property
.. _Set Jail Property: https://freebsd.github.io/iocage/basic-use.html?highlight=properties#set-jail-property
.. _iocage list is slow: https://forums.freebsd.org/threads/freebsd-13-1-extremally-slow.86723
