ansible-iocage

iocage module for Ansible.

Use current branch

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.

Description

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

Requirements (on the node)

lang/python >= 3.6
sysutils/iocage

Installation

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.

Standalone installation

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']

Install the collection vbotka.freebsd from Ansible Galaxy

shell> ansible-galaxy collection install vbotka.freebsd

Documentation

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

Example

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']

Use-cases

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"

Tests

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

Advanced tests

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

Variables and parameters of the tests

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.

Name		Name	Last commit message	Last commit date
Latest commit History 159 Commits
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
__init__.py		__init__.py
iocage.py		iocage.py

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ansible-iocage

Use current branch

Description

Requirements (on the node)

Installation

Standalone installation

Install the collection vbotka.freebsd from Ansible Galaxy

Documentation

Example

Use-cases

Tests

Advanced tests

Variables and parameters of the tests

See also

About

Releases

Packages

Languages

License

pizza0rodeo/ansible-iocage

Folders and files

Latest commit

History

Repository files navigation

ansible-iocage

Use current branch

Description

Requirements (on the node)

Installation

Standalone installation

Install the collection vbotka.freebsd from Ansible Galaxy

Documentation

Example

Use-cases

Tests

Advanced tests

Variables and parameters of the tests

See also

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages