Custom Modules and Plugins

Ansible comes with a huge library of pre-built modules. Think of a module as a small, self-contained program that performs a specific task on a managed node (the server you are controlling). For example, the 'copy' module copies a file. The 'yum' module installs software. These are your default kitchen appliances. They cover most common jobs.

But real IT environments are unique. You might need to interact with a proprietary internal application that has a very specific API (Application Programming Interface — a set of rules that allows different software programs to communicate). Ansible doesn't ship with a module for that. Or you might need to read a specific log file format and make a decision based on its contents. The answer is to write your own custom module.

A custom module is a script, written in Python (the programming language Ansible uses), that follows a precise contract. Ansible runs this script on the managed node. The script must do three things: accept input, perform an action, and return JSON (JavaScript Object Notation — a structured text format for data) to Ansible that reports success, failure, or changed status. The script can be simple, like checking if a service is running, or complex, like orchestrating a multi-step database migration.

Here is a simplified example of what a custom module's output looks like:

{"changed": false, "msg": "The service was already running."}

This tells Ansible: 'I did my job, but nothing needed to change.' The key rule is that a module must be idempotent. Idempotent means you can run it a hundred times, and if the system is already in the desired state, it will do nothing and report 'changed: false'. This is crucial for Ansible's reliability.

Now, plugins are different. Plugins extend Ansible's own behaviour, not the behaviour of managed nodes. There are several types, but for EX294, you care most about 'filter' plugins and 'callback' plugins.

A filter plugin is like a custom function in a spreadsheet. It takes a piece of data (a variable) and transforms it. For example, the built-in 'to_nice_json' filter turns a variable into a human-readable JSON string. A custom filter plugin could do something like: take a server's hostname and extract the location code from the middle of it. You use filter plugins directly in your playbooks with the pipe '|' symbol.

A callback plugin changes what Ansible outputs to your screen or log file. By default, you see standard output. A custom callback plugin could make Ansible send a message to a Slack channel every time a playbook finishes, or log results to a database.

Why do these exist? Because no software vendor can predict every user's needs. Custom modules and plugins are the escape hatch. They let you adapt Ansible to your exact environment without waiting for a vendor update. The EX294 exam tests you on two things: recognising the basic framework (the directory structure and the required return format) and understanding the difference between a module and a plugin. You will not be asked to write a full custom module from scratch in the exam. You will be asked to identify the correct syntax, the required file location, and the minimum necessary code elements.

The standard structure for a custom module is a Python file placed in a 'library' directory alongside your playbook. For a plugin, it goes in a 'filter_plugins' or 'callback_plugins' directory. Ansible automatically looks for these directories when it runs. If you put your script in the right place, Ansible finds it and uses it as if it were built-in.

Understanding this concept replaces frustration with empowerment. Instead of hacking a workaround in a shell script, you write a clean, reusable, idempotent module that integrates perfectly with the rest of your Ansible automation.

Imagine you work for a mid-sized e-commerce company. You manage hundreds of servers that run the company's custom-built inventory application. This application has a proprietary API for checking stock levels and updating prices. There is no Ansible module for it because it is unique to your company. Your daily task is to update product prices across thousands of items, but only during off-peak hours to avoid user disruption.

Here is what you do step by step:

First, you identify the precise action you need. You need to send an HTTP POST request (a specific type of web request that sends data to a server) to the inventory API with a product ID and a new price. You need the module to report whether the update succeeded, whether it failed because the product was not found, or whether no change was needed (price was already correct). This forms the specification for your custom module.

Next, you write the Python script. It must accept parameters like 'product_id' and 'new_price'. It uses Python's 'requests' library to call the API. It checks the API's response code. If the response is 200 and the price changed, it returns '{"changed": true}'. If the response is 200 and the price is the same, it returns '{"changed": false}'. If the response is 404 (not found), it returns '{"failed": true, "msg": "Product not found"}'. This strict return format is critical.

You save this script in a directory called 'library' in the same folder as your playbook. Your playbook's directory structure looks like this:

- site.yml (your main playbook) - library/ - update_price.py (your custom module) - filter_plugins/ - my_filters.py (if you need custom filters)

Now, in your playbook, you use the module exactly like any built-in one:

- name: Update price for product 1234 update_price: product_id: '1234' new_price: 29.99

When you run 'ansible-playbook site.yml', Ansible discovers the library directory, finds update_price.py, and executes it. It treats it as a first-class module.

Later, you might want a custom filter plugin to format prices with a currency symbol before they appear in a report. You write a filter plugin that takes a number and returns a string like '$29.99'. You place it in 'filter_plugins/my_filters.py', and in your playbook you use it as: '{{ price | format_currency }}'.

The advantage for you as an IT professional is immense. You are not limited by the tools someone else decided you should have. You build exactly what your unique environment needs. You also learn the fundamentals of how Ansible works internally, which helps you debug problems faster and write more reliable automation. You become the person on your team who can solve problems that the standard tools cannot touch.