Best Practice

Topics:

• The iocage binary is very complex.

• The iocage module can’t cover all use-cases. The maintenance of such complexity wouldn’t be efficient.

• For use cases not covered by the module, use the runner tasks from the role iocage.

Installation

WIP

• Install the package or port sysutils/iocage; (role:pkg)

• Activate the iocage binary; (role:activate)

• Configure iocage; (role:conf)

• Audit the installation; (role:sanity)

• Configure rc.conf and start/restart/stop/enable/disable iocage; (role:rcconf)

Workflow

WIP

• Fetch release(s) and create basejail(s); (role:runner or module)

• Create template(s); (role:data, role:runner, role:clean or module)

• Clone and start jails; (role:runner or module)

• Create dynamic inventory; (role:stat and ansible.builtin.add_host or inventory plugin)

• Manage the jails by Ansible; (playbooks)

Use cases

WIP

• No root at iocage hosts.

  A user doesn’t have root access at iocage host. Unprivileged access is sufficient to run ‘iocage list …’ and create dynamic inventory. This user then manages the jails with escalated privilege (root). See example 031.

• Root is needed at iocage hosts to list the DHCP address.

  See the options sudo and sudo_preserve_env of the inventory plugin iocage

iocage tags

An iocage tag is a key-value pair applied to a jail to hold metadata about that jail. Each tag is a label consisting of a key and an optional value. The iocage tags are stored in the dictionary iocage_tags.

Note

The iocage tags are not related to Ansible Tags in any way. In this document, a tag means an Ansible tag while iocage tag(s) always reference attribute(s) of the dictionary iocage_tags.

property notes

We use the iocage property notes to store iocage tags. Quoting from man iocage

notes="any string"
              Custom notes for miscellaneous tagging.
              Default: none
              Source: local

For example, put the notes into the dictionary clones

clones:
  test_111:
    clone_from: ansible_client
    properties:
      ip4_addr: 'em0|10.1.0.111/24'
      notes: "vmm={{ inventory_hostname }} swarm=sw_01"

, or into the dictionary swarms

swarms:
  sw_01:
    count: 3
    template: ansible_client
    properties:
      notes: "vmm={{ inventory_hostname }}"

Then, the playbook pb-iocage-ansible-clients creates jails, for example, on the host iocage_02

[iocage_02]# iocage list -l
+-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
| JID |   NAME   | BOOT | STATE | TYPE |     RELEASE     |        IP4         | IP6 |    TEMPLATE    | BASEJAIL |
+=====+==========+======+=======+======+=================+====================+=====+================+==========+
| 149 | afa9e515 | off  | up    | jail | 14.1-RELEASE-p6 | epair0b|10.1.0.122 | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
| 148 | c1670497 | off  | up    | jail | 14.1-RELEASE-p6 | epair0b|10.1.0.135 | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+
| 147 | test_111 | off  | up    | jail | 14.1-RELEASE-p6 | em0|10.1.0.111/24  | -   | ansible_client | no       |
+-----+----------+------+-------+------+-----------------+--------------------+-----+----------------+----------+

with notes

[iocage_02]# iocage get notes afa9e515
vmm=iocage_02 swarm=sw_01
[iocage_02]# iocage get notes c1670497
vmm=iocage_02 swarm=sw_01
[iocage_02]# iocage get notes test_111
vmm=iocage_02 swarm=sw_01

Note

The tasks pb-iocage-ansible-clients/swarm.yml create the iocage tag swarm automatically from the dictionary swarms keys.

See also

The example 206 Create DHCP and fixed IP jails from template

dictionary iocage_tags

In the inventory plugin vbotka.freebsd.iocage enable the option get_properties, compose the dictionary iocage_tags, and use it to create keyed_groups

get_properties: True
compose:
  iocage_tags: dict(iocage_properties.notes | split | map('split', '='))
keyed_groups:
  - prefix: swarm
    key: iocage_tags.swarm
  - prefix: vmm
    key: iocage_tags.vmm

Then, this plugin creates the dictionary iocage_tags in each jail

iocage_tags:
  swarm: sw_01
  vmm: iocage_02

and use it to create the groups

(env) > ansible-inventory -i hosts --graph
@all:
  |--@ungrouped:
  |--@swarm_sw_01:
  |  |--afa9e515
  |  |--c1670497
  |  |--test_111
  |--@vmm_iocage_02:
  |  |--afa9e515
  |  |--c1670497
  |  |--test_111

Hint

Take a look at Index and search iocage_tags to see what examples are available.