What is an Ansible module—and how does it work?

An Ansible® module is a small program that performs actions on a local machine, application programming interface (API), or remote host. Modules are expressed as code, usually in Python, and contain metadata that defines when and where a specific automation task is executed and which users can execute it. There are thousands of Ansible modules available for download in repositories like Ansible automation hub and Ansible Galaxy, but you can also create custom modules yourself and share them with other Ansible users within your organization or in the larger Ansible community.

Modules can perform IT functions for a variety of use cases including networking, provisioning, security, cloud management, user management, configuration management, and communications. To understand how Ansible modules help you automate these use cases and more, it’s important to understand the relationship between modules and other key components of Ansible automation—including tasks, plays, playbooks, and roles.

• Task: Defines the action to be applied to a managed host, but does not specify the host it will be applied to. You can invoke a module within a task to be executed on a host, but that host will be defined outside of the task, at the play level.
• Play: The core unit of Ansible execution, a play includes a list of tasks and maps that list to specific managed hosts. A play also contains variables and, in more complex use cases, may contain roles.
• Ansible Playbook: Includes 1 or more plays. Playbooks are written in YAML, are human-readable, and easy to share.
• Ansible Role: Packages Ansible content—including tasks, handlers, variables, plugins, templates, and files—for use inside of a play. Ansible Roles can be imported into a play, reused in other plays or playbooks, and shared for use by other automation users.
• Collections: Bundles of Ansible content designed to help automation developers work faster and improve productivity. Collections are the preferred way to package and share modules.
• Plugins: Pieces of code that build on Ansible’s core functionality and usually execute on the control node. While modules are a type of plugin, they generally execute tasks on a target, not the control node. 

Think of it like this: If tasks are the jobs to be completed, then modules are the tools you need to actually complete those jobs. A task defines an action that needs to be done, and the module executes on a managed host to accomplish that action, collecting return values in JSON format when finished.

Modules are typically stored in a playbook’s library and run when the playbook executes the associated task, but they may also be included within a role or collection. When an Ansible Role is imported into a playbook, the modules in the role directory execute the task or tasks contained within that role. While a module written in a single play will only be used that 1 time, modules contained inside of a role will execute each time the role is called within the playbook.

The following 3 example modules are included with Ansible Core and a part of all Ansible installations:

• dnf module (ansible.builtin.dnf)- Installs, upgrades, and removes packages and groups with the dnf package manager—the default software package manager for Fedora.

• service module (ansible.builtin.service)- Manages services on remote hosts. Example actions include, but are not limited to, starting, stopping, and restarting a service.

• command module (ansible.builtin.command)- Executes commands on targets.

When existing Ansible modules are insufficient for your automation use case, you can create your own module to accomplish a specific job. Although the process for creating a module may vary depending on the complexity of the desired automation tasks, you can develop your own module by:

1. Creating a library directory in your repository.
2. Creating a module file in Python or your preferred programming language within the library directory.
3. Developing a test playbook in your library directory.
4. Executing the playbook to test the module.

Modules should be concise and aim to solve a very specific problem; this makes them easy to test, use, reuse, and share. Modules should also provide a defined interface that accepts arguments and be idempotent—meaning they shouldn’t make any changes if they detect that the current state of the node matches the desired final state.

Users who are just getting started with Ansible content development or those who want to streamline the module creation process can use a community tool like Content Builder, which generates modules and other Ansible plugins for use cases like networking, security, and cloud content.

Like other types of Ansible content, Ansible modules are designed to be shareable. With a Red Hat® Ansible Automation Platform subscription, you can package your modules in collections and upload them to Ansible automation hub or share them across your enterprise with a private automation hub. You can also distribute your modules on Ansible Galaxy, a free repository for sharing Ansible content with community users.

While modules play an essential role in playbook execution, they also hold value for organizations looking to take a more advanced, proactive approach to IT management with event-driven automation.

Event-driven automation connects data from IT events to automated actions, reducing the need for teams to take manual steps to respond or remediate. An event can be any occurrence that impacts the delivery of a service or the management of IT infrastructure.

A feature of Red Hat Ansible Automation Platform and a comprehensive solution for automation teams looking to benefit from event-driven automation, Event-Driven Ansible uses Ansible Rulebooks to respond to events with the appropriate actions you’ve defined—this includes executing playbooks, roles, templates, and modules. A rulebook uses conditional “if-this-then-that” instructions to help you automate routine tasks—such as running a remediation playbook in the case of an outage.

When data from an event source meets the conditions defined in a rulebook, Ansible Automation Platform will trigger the actions that you’ve defined, which may include running a whole playbook or running a single module to execute a very specific action—the response fully depends on what you want to happen when an event occurs and what you’ve defined in a rulebook.

The example below demonstrates how a debug module is triggered when an event from a webhook source meets the conditions defined in a rulebook.

The rulebook.yml:

---
- name: Listen for events on a webhook
  hosts: all
  ## Define our source for events
  sources:
    - ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000
  ## Define the conditions we are looking for
  rules:
    - name: Say Hello
      condition: event.payload.message == "Ansible is super cool"
  ## Define the action we should take should the condition be met
      action:
        run_playbook:
          name: say-what.yml

The playbook say-what.yml:

- hosts: localhost
  connection: local
  tasks:
    - debug:
        msg: "Thank you, my friend!"

In this case, the rulebook specifies that the say-what.yml playbook executes when the defined conditions have been met. Since the debug module is included in the say-what.yml playbook, it is run each time the playbook is executed.

As a part of Ansible Automation Platform, Event-Driven Ansible offers the event-handling capabilities you need to enable quick and efficient IT service delivery while allowing you to complete tasks without manual intervention—giving your organization time to focus on higher-value projects.

Since event-driven automation often relies on third-party monitoring tools to identify when an event occurs, making use of Ansible content that integrates with the platforms and tools you already use can make the transition to more efficient, automated workflows easier. With a Red Hat Ansible Automation Platform subscription, you gain access to thousands of bundled modules, roles, plugins, and documentation in the form of Ansible Content Collections. These include both Red Hat Ansible Certified Content and Ansible validated content from Red Hat and our partners—all available for download via Ansible automation hub.