iocage module for Ansible.
Upstream is too late with accepting PRs. No patches were accepted since September 2021. Therefor, the development is not submitted to the upstream anymore. Use the current branch https://github.com/vbotka/ansible-iocage/tree/current until this problem is resolved.
This module is an Ansible 'wrapper' of the iocage command.
- Works with Python3 iocage
- Release of a jail is the same as the release of the host if not specified
- Release is automatically fetched if missing
- lang/python >= 3.6
- sysutils/iocage
The module can be installed either as a standalone module or as a part of the collection vbotka.freebsd. Do not mix the installations of the collection and the standalone module.
Put the file iocage.py to DEFAULT_MODULE_PATH
shell> ansible-config dump|grep DEFAULT_MODULE_PATH
DEFAULT_MODULE_PATH(default) = ['/home/admin/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
shell> ansible-galaxy collection install vbotka.freebsd
Only the inline documentation of the module is available. Run the command
shell> ansible-doc -t module iocage
Read the iocage documentation at readthedocs.io
No option of the module is required. Without any option the module gathers facts about the jails. For example the play below
shell> cat playbook.yml
- hosts: srv.example.net
tasks:
- iocage:
- debug:
msg: |-
iocage_releases = {{ ansible_facts.iocage_releases }}
iocage_templates.keys() = {{ ansible_facts.iocage_templates.keys()|list }}
iocage_jails.keys() = {{ ansible_facts.iocage_jails.keys()|list }}
gives
shell> ansible-playbook playbook.yml
...
msg: |-
iocage_releases = ['13.0-RELEASE']
iocage_templates.keys() = []
iocage_jails.keys() = ['NewJail', 'test_31', 'test_basejail_13_0_RELEASE']
- Fetch 13.0-RELEASE
iocage: state=fetched release=13.0-RELEASE
- Fetch host's RELEASE
iocage: state=fetched
- Fetch the base component of host's RELEASE only
iocage: state=fetched components=base.txz
- Fetch host's RELEASE, limited to base and doc components
iocage: state=fetched components=base.txz,doc.txz
- Create basejail
iocage: state=basejail name="foo" release=13.0-RELEASE
- Create template
iocage:
state: template
name: mytemplate
properties:
ip4_addr: 'lo0|10.1.0.1'
resolver: 'nameserver 127.0.0.1'
- Clone existing jail
iocage:
state: present
name: "foo"
clone_from: "mytemplate"
pkglist: /path/to/pkglist.json
properties:
ip4_addr: 'lo0|10.1.0.5'
boot: "on"
allow_sysvipc: 1
defaultrouter: '10.1.0.1'
host_hostname: 'myjail.my.domain'
- Create jail (without cloning)
iocage:
state: present
name: "foo"
pkglist: /path/to/pkglist.json
properties:
ip4_addr: 'lo0|10.1.0.5'
boot: "on"
allow_sysvipc: 1
defaultrouter: '10.1.0.1'
host_hostname: 'myjail.my.domain'
- Ensure jail is started
iocage: state=started name="foo"
- Ensure jail is stopped
iocage: state=stopped name="foo"
- Restart existing jail
iocage: state=restarted name="myjail"
- Execute command in (running) jail
iocage: state=exec name="myjail" user="root" cmd="service sshd start"
- Destroy jail
iocage: state=absent name="myjail"
- Set attributes on jail
iocage:
state: set
name: "myjail"
properties:
template: "yes"
The project comes with set of tests stored in the directory test/tasks. Run the complete collection of the tests at localhost
shell> cd test
shell> ansible-playbook -M . iocage_test.yml
This should display a report similar to this one
PLAY RECAP ***********************************************************************
localhost: ok=158 changed=17 unreachable=0 failed=0 skipped=65 rescued=6 ignored=0
Custom stats will provide you with more details if you run the tests on multiple nodes. See ansible.builtin.set_stats. For example run the complete collection of the tests on two nodes test_23 and test_29
shell> ANSIBLE_SHOW_CUSTOM_STATS=true ansible-playbook iocage_test.yml -M . -e my_hosts=test_23,test_29
This should display a report similar to this one
PLAY RECAP ***********************************************************************
test_23: ok=207 changed=17 unreachable=0 failed=0 skipped=28 rescued=6 ignored=0
test_29: ok=207 changed=17 unreachable=0 failed=0 skipped=28 rescued=6 ignored=0
CUSTOM STATS: ********************************************************************
test_23: a1: Aug 29 21:46:23 a2: Aug 29 21:52:12 ok: 35
test_29: a1: Aug 29 21:46:23 a2: Aug 29 22:03:57 ok: 35
Most of the tests and groups are generated from templates (see directory templates) by the dictionaries iocage_test_db and iocage_group_db stored in the files in directory vars. Do not edit the tasks and groups manually. Modify or create new templates and dictionaries, and run the playbook configure.yml. For example, add new group of tests in vars/groups.d/group_present_absent_restart.yml
---
group_present_absent_restart:
template: group
tests:
- test: test_present
- test: test_absent
- test: test_restart_crash
Run playbook configure.yml and create the group group_present_absent_restart
shell> ansible-playbook configure.yml -e my_groups=group_present_absent_restart -t create_groups,create_iocage_test
...
TASK [Create group files in directory tasks] *******************************************
ok: [localhost] => (item=group_present_absent_restart)
TASK [Create playbook iocage_test.yml] *************************************************
ok: [localhost]
Create file with the parameters of the tests, e.g. run the tests on the nodes test_23,test_29, use jail test_31, enable debug, and set strategy free
shell> cat extra_vars/test_31-debug-n2.yml
---
my_hosts: test_23,test_29
my_jname: test_31
my_debug: true
my_strategy: free
Run the tests and display custom stats
shell> ANSIBLE_SHOW_CUSTOM_STATS=true ansible-playbook iocage_test.yml -M . -e @extra_vars/test_31-debug-n2.yml -t group_present_absent_restart
This should display a report similar to this abridged one
PLAY [test_23,test_29] *****************************************************************
TASK [>>> TEST START: test_present: Check if test_31 can be created] *******************
ok: [test_23] =>
result.msg: |-
Jail 'test_31' was created with properties {}.
/usr/local/bin/iocage create -n test_31 -r 13.0-RELEASE
ok: [test_29] =>
result.msg: |-
Jail 'test_31' was created with properties {}.
/usr/local/bin/iocage create -n test_31 -r 13.0-RELEASE
ok: [test_23] => changed=false
msg: |-
[OK] test_present: Passed: Jail 'test_31' was created with properties {}.
ok: [test_29] => changed=false
msg: |-
[OK] test_present: Passed: Jail 'test_31' was created with properties {}.
TASK [>>> TEST START: test_absent: Check if jail test_31 can be destroyed] *************
ok: [test_23] =>
result.msg: Jail 'test_31' was destroyed., Jail test_31 removed from iocage_jails.
ok: [test_29] =>
result.msg: Jail 'test_31' was destroyed., Jail test_31 removed from iocage_jails.
ok: [test_23] => changed=false
msg: '[OK] test_absent: Passed: Jail ''test_31'' was destroyed., Jail test_31 removed from iocage_jails.'
ok: [test_29] => changed=false
msg: '[OK] test_absent: Passed: Jail ''test_31'' was destroyed., Jail test_31 removed from iocage_jails.'
TASK [>>> TEST START: test_restart_crash: Check if jail test_31 can not be restarted] **
fatal: [test_23]: FAILED! => changed=false
msg: Jail 'test_31' doesn't exist
fatal: [test_29]: FAILED! => changed=false
msg: Jail 'test_31' doesn't exist
ok: [test_23] => changed=false
msg: '[OK] test_restart_crash: Passed: Jail ''test_31'' doesn''t exist'
ok: [test_29] => changed=false
msg: '[OK] test_restart_crash: Passed: Jail ''test_31'' doesn''t exist'
CUSTOM STATS: **************************************************************************
test_23: a1: Aug 25 23:26:31 a2: Aug 25 23:27:01 ok: 3
test_29: a1: Aug 25 23:26:31 a2: Aug 25 23:28:06 ok: 3
In this framework, there are three sources of the tests' parameters
-
Hard-coded parameters in the test files and group files. If you want to customize them change the data in vars/ and run the playbook configure.yml. You can also add you own tests and group files preferably in the form of the data in vars/ and templates/. Add templates if needed.
-
Defaults in the playbook iocage_test.yml. If you want to customize them change the template iocage_test.yml.j2 and run the playbook configure.yml.
-
Extra vars on the command line. See examples in the directory extra_vars/ on how to create files with extra variables.
Except of this you can customize the variables at any other precedence you want to, of course.