Ansible Collection for Ansible power users

This repo hosts Ansible collection jm1.ansible.

The collection includes content which extends Ansible's core features.

For example, action plugin jm1.ansible.execute_module allows to execute an arbitrary Ansible module whose name and parameters are expanded from Jinja2 templates:

- name: Define a module call
  set_fact:
    slurp_proc_mounts:
      name: ansible.builtin.slurp
      args:
        src: /proc/mounts
      register: slurp_output

- name: Run a module defined in a variable
  jm1.ansible.execute_module: '{{ slurp_proc_mounts }}'

- name: Print registered variable
  debug:
    var: slurp_output

Role jm1.ansible.execute_modules builds upon said action plugin to allow executing tasks which have been defined with variable duties in group_vars or host_vars as such:

duties:
- ansible.builtin.lineinfile:
    path: /etc/hosts
    regexp: '\.1\s+{{ hostname }}'
    line: "{{ '{ip} {fqdn} {hostname}'.format(ip='127.0.0.1', fqdn=fqdn, hostname=hostname) }}"
    owner: root
    group: root
    mode: '0644'

By default, Ansible offers several modules like ansible.builtin.import_tasks and ansible.builtin.include_tasks to dynamically and statically load tasks from files. But Ansible does not offer any module to load tasks from variables without this indirection through files. Ansible's block statement does not support Jinja2 templates, so Ansible does not allow to define tasks in a variable and pass this variable to block.

Included content

Click on the name of a module or role to view that content's documentation:

• Modules:
  • execute_module
• Roles:
  • execute_modules

Requirements and Installation

Installing the Collection from Ansible Galaxy

Before using the jm1.ansible collection, you need to install it with the Ansible Galaxy CLI:

ansible-galaxy collection install jm1.ansible

You can also include it in a requirements.yml file and install it via ansible-galaxy collection install -r requirements.yml, using the format:

---
collections:
  - name: jm1.ansible
    version: 2024.5.30

Usage and Playbooks

You can either call modules by their Fully Qualified Collection Name (FQCN), like jm1.ansible.execute_module, or you can call modules by their short name if you list the jm1.ansible collection in the playbook's collections, like so:

---
- name: Using jm1.ansible collection
  hosts: localhost

  collections:
    - jm1.ansible

  tasks:
    - name: Define a module call
      set_fact:
        slurp_proc_mounts:
          name: ansible.builtin.slurp
          args:
            src: /proc/mounts

    - name: Run a module defined in a variable
      execute_module: '{{ slurp_proc_mounts }}'

For documentation on how to use individual modules and other content included in this collection, please see the links in the 'Included content' section earlier in this README.

See Ansible Using collections for more details.

Contributing

There are many ways in which you can participate in the project, for example:

• Submit bugs and feature requests, and help us verify them
• Submit pull requests for new modules, roles and other content

We're following the general Ansible contributor guidelines; see Ansible Community Guide.

If you want to develop new content for this collection or improve what is already here, the easiest way to work on the collection is to clone this repository (or a fork of it) into one of the configured ANSIBLE_COLLECTIONS_PATHS and work on it there:

1. Create a directory ansible_collections/jm1;
2. In there, checkout this repository (or a fork) as ansible;
3. Add the directory containing ansible_collections to your ANSIBLE_COLLECTIONS_PATHS.

Helpful tools for developing collections are ansible, ansible-doc, ansible-galaxy, ansible-lint, flake8, make and yamllint.

OS	Install Instructions
Debian 10 (Buster)	Enable Backports. apt install ansible ansible-doc ansible-lint flake8 make yamllint
Debian 11 (Bullseye)	apt install ansible ansible-lint flake8 make yamllint
Debian 12 (Bookworm)	apt install ansible ansible-lint flake8 make yamllint
Debian 13 (Trixie)	apt install ansible ansible-lint flake8 make yamllint
Fedora	dnf install ansible python3-flake8 make yamllint
Red Hat Enterprise Linux (RHEL) 7 / CentOS 7	Enable EPEL. yum install ansible ansible-lint ansible-doc python-flake8 make yamllint
Red Hat Enterprise Linux (RHEL) 8 / CentOS 8	Enable EPEL. yum install ansible python3-flake8 make yamllint
Red Hat Enterprise Linux (RHEL) 9 / CentOS 9	Enable EPEL. yum install ansible python3-flake8 make yamllint
Ubuntu 18.04 LTS (Bionic Beaver)	Enable Launchpad PPA Ansible by Ansible, Inc.. apt install ansible ansible-doc ansible-lint flake8 make yamllint
Ubuntu 20.04 LTS (Focal Fossa)	Enable Launchpad PPA Ansible by Ansible, Inc.. apt install ansible ansible-doc ansible-lint flake8 make yamllint
Ubuntu 22.04 LTS (Jammy Jellyfish)	apt install ansible ansible-lint flake8 make yamllint
Ubuntu 24.04 LTS (Noble Numbat)	apt install ansible ansible-lint flake8 make yamllint

Have a look at the included Makefile for several frequently used commands, to e.g. build and lint a collection.

More Information

• Ansible Collection Overview
• Ansible User Guide
• Ansible Developer Guide
• Ansible Community Code of Conduct

License

GNU General Public License v3.0 or later

See LICENSE.md to see the full text.

Author

Jakob Meng @jm1 (github, galaxy, web)