Ansible: Plugins

Ansible plugins are modular Python scripts that extend and customize the core functionalities of Ansible. They act as add-ons, allowing users to adapt Ansible to a wide set of requirements beyond its out-of-the-box capabilities.

• Purpose: Plugins help Ansible manage automation tasks in a flexible way—such as changing how connections are established, transforming data, customizing output, or dynamically generating inventory.
• How They Work: Most plugins run on the control node (where you execute Ansible), not on the managed nodes. They can be written and placed in specific directories for easy integration with playbooks and roles.
• Types of Plugins:
  • Connection Plugins: Control how Ansible connects to remote systems (e.g., SSH, WinRM, local connection).
  • Callback Plugins: Change how task output is displayed or logged.
  • Filter Plugins: Add custom Jinja2 filters for data transformations in templates.
  • Inventory Plugins: Dynamically generate inventory from external sources.
  • Lookup Plugins: Allow tasks to access external data sources or secrets at runtime.
  • Strategy Plugins: Define how tasks are executed (e.g., linear, free, custom strategies).
  • Action Plugins: Add custom processing logic to module execution.
  • Cache, Test, Vars, Become, Shell Plugins: Provide advanced options for caching results, testing conditions, handling privilege escalation, custom shells, and variable sources.
• Benefits:
  • Enhance Ansible’s automation and orchestration features.
  • Tailor workflow to match infrastructure or project needs.
  • Enable integration with custom tools, APIs, and platforms.

In summary, Ansible plugins are key to adapting Ansible for complex environments, empowering users to automate virtually any IT workflow by creating or customizing small, focused extension modules.

Ansible supports a diverse set of plugin types, each designed to extend or customize specific areas of automation. Understanding these plugin types helps you leverage Ansible’s full flexibility. Here’s a closer look, step by step:

• Action Plugins:
  • Modify or enhance the behavior of modules before they execute on remote nodes.
  • Ideal for adding custom logic or preprocessing tasks on the control node.
• Lookup Plugins:
  • Pull external data (like secrets or config items) into playbooks at runtime.
  • Commonly used for integration with key stores, files, or APIs.
• Filter Plugins:
  • Transform and manipulate data within playbooks or templates using custom Jinja2 filters.
  • Helps with format conversion, string manipulation, or complex calculations.
• Connection Plugins:
  • Control how Ansible connects to managed nodes (e.g., SSH, WinRM, containers).
  • Enable connectivity with a wide variety of platforms and devices.
• Strategy Plugins:
  • Define the order and parallelism of task execution (e.g., linear, free).
  • Useful for optimizing performance or customizing workflow.
• Callback Plugins:
  • Customize how playbook results and task events are handled or displayed.
  • Implement logging, notifications, and real-time output formatting.
• Inventory Plugins:
  • Generate dynamic inventory sources from cloud platforms, databases, or APIs.
  • Allows infrastructure to be managed as code and updated in real time.
• Vars Plugins:
  • Inject additional variables from files, APIs, or other sources into Ansible runs.
  • Enhances playbook adaptability and reusability by centralizing variable management.
• Cache Plugins:
  • Store facts and variable data to speed up repeated runs and reduce redundant work.
  • Backed by memory, files, Redis, or other storage systems.
• Shell Plugins:
  • Format and execute shell commands in the appropriate shell environment (bash, csh, PowerShell, etc.).
  • Ensures command compatibility for different remote operating systems.
• Test Plugins:
  • Provide additional test logic (Jinja2 `is` tests) for use in playbook when conditionals.
  • Helps improve playbook precision and error checking.
• Become Plugins:
  • Handle privilege escalation methods (sudo, su, doas, etc.).
  • Control how and when Ansible changes user privileges during runs.

Each plugin type is loaded automatically based on its directory and usage context, enabling modular expansion and fine-tuned control of Ansible’s automation engine.

Understanding where Ansible looks for plugins and how it loads them is essential if you want to extend or customize automation tasks. Here’s a step-by-step guide to plugin locations and loading.

1. Plugin Type Directories:
   • Each plugin type has its own directory (e.g., callback_plugins, filter_plugins, connection_plugins, etc.).
2. Default Search Locations:
   • System-wide: /usr/share/ansible/plugins/<plugin_type>/
   • User-specific: ~/.ansible/plugins/<plugin_type>/
   • Project-specific: A <plugin_type>_plugins/ directory in your Ansible project root or next to your playbooks.
   • Role-scoped: Inside a role's directory at roles/<role>/plugins/<plugin_type>/
3. Custom Directories:
   • You can add custom plugin paths using environment variables like ANSIBLE_CALLBACK_PLUGINS, ANSIBLE_FILTER_PLUGINS, etc. This allows organization-wide or custom locations for plugins.
   • Multiple paths can be set, separated by colons (:), similar to the system PATH.
4. ansible.cfg Configuration:
   • Plugin paths can also be specified in the ansible.cfg file under the [defaults] section using keys like callback_plugins, filter_plugins, etc.
5. Plugin Loading Order:
   • Ansible loads plugins from project-level, then user-level, then system-level directories. The first matching plugin is used.
6. Verification:
   • You can confirm plugin discovery by running commands like ansible-doc -t <plugin_type> <plugin_name> to review documentation and check if your plugin is loaded.

With this structure, you can scope plugins for a single project, share them with a team, or make them available across your infrastructure. This makes extending Ansible both flexible and very powerful.

Example directory structure:
my-ansible-project/
├── playbooks/
│   └── site.yml
├── callback_plugins/
│   └── my_custom_callback.py
├── filter_plugins/
│   └── myfilters.py
└── roles/
    └── net_tools/
        └── plugins/
            └── connection_plugins/
                └── my_conn.py

Developing a custom Ansible plugin empowers you to address unique automation needs, streamline workflows, or integrate with systems not covered by default plugins. Here is a step-by-step approach to creating and using your own plugin:

1. Select the Plugin Type:
   • Decide which type of plugin you need (Action, Callback, Lookup, Filter, Inventory, etc.). Each type serves a specific purpose within Ansible.
2. Prepare Your Development Environment:
   • Ensure you have Python installed (Ansible plugins are written in Python).
   • Create or identify the correct subdirectory in your project (e.g., filter_plugins/, callback_plugins/).
3. Write the Plugin Code:
   • Start with a template or minimal Python file based on the chosen plugin type’s requirements.
   • Implement the core logic in your plugin class, inheriting from the appropriate Ansible base class.
   • Add inline documentation (docstrings) and, if required, a DOCUMENTATION block for Ansible to parse help text.
4. Place the Plugin:
   • Save your plugin in the corresponding directory. For project-level usage, keep it within your project’s plugin folder; for global usage, use ~/.ansible/plugins/<type>_plugins/ or /usr/share/ansible/plugins/<type>_plugins/.
5. Configure Ansible (if needed):
   • If your plugin isn’t in a default search location, specify its path using an environment variable or in ansible.cfg (e.g., filter_plugins = ./filter_plugins).
6. Test Your Plugin:
   • Use it in a playbook or call ansible-doc -t <type> <plugin_name> to check if it’s discoverable and the documentation loads correctly.
   • Debug and refine as needed, checking log output or playbook results.
7. Optional: Prepare for Sharing:
   • Package the plugin and documentation for sharing as a role or part of an Ansible Collection if you want to distribute it widely.

Here’s a simple folder example showing where you might place a custom plugin:

my-ansible-project/
├── playbooks/
│   └── main.yml
├── filter_plugins/
│   └── my_custom_filter.py
└── callback_plugins/
    └── output_prettifier.py

Creating a custom plugin is a straightforward process that unlocks powerful extensibility within Ansible—tailoring automation to your precise requirements.

Organizing your project and plugins is key to maintaining clarity and scalability in an Ansible automation environment. Here’s a step-by-step breakdown of a practical plugin directory structure:

1. Project Root:
   • The top-level directory houses your main playbooks and custom plugin folders.
2. Playbooks:
   • Place your primary orchestration files inside a playbooks/ or directly at the root (e.g., site.yml, main.yml).
3. Plugin-Focused Folders:
   • Add custom plugins in subfolders named for each type (e.g., filter_plugins/, callback_plugins/, inventory_plugins/).
   • This approach makes your project portable and keeps plugins discoverable without additional configuration.
4. Roles:
   • Roles bundle logic, files, and can include their own plugin folders (under roles/<role_name>/plugins/<plugin_type>/).
5. Inventory and Vars:
   • Keep inventory and group/host variable files in their respective subdirectories for organization.

my-ansible-project/
├── playbooks/
│   └── site.yml
├── callback_plugins/
│   └── my_custom_callback.py
├── filter_plugins/
│   └── myfilters.py
├── inventory_plugins/
│   └── mydynamic_inventory.py
├── group_vars/
│   └── all.yml
├── host_vars/
│   └── web01.yml
└── roles/
    └── net_tools/
        └── plugins/
            └── connection_plugins/
                └── my_conn_plugin.py

This organization ensures that your custom plugins are loaded automatically by Ansible, and makes collaboration and role-sharing straightforward. Keeping plugins with your project also enables version control and easy transfer to other environments or teams.

Ansible provides straightforward ways to discover what plugins are available in your environment, making it easy to explore built-in capabilities or confirm installation of custom extensions. Here’s a step-by-step process:

1. Using the ansible-doc Command:
   • The ansible-doc command is the primary tool for listing and viewing details of available plugins.
   • To list all plugins of a certain type:

     ansible-doc -t <plugin_type> -l

     Replace <plugin_type> with the desired type (e.g., filter, lookup, strategy, connection, etc.).
   • For example, to see all callback plugins:

     ansible-doc -t callback -l

2. Viewing Plugin Documentation:
   • For detailed information and usage examples for a specific plugin, use:

     ansible-doc -t <plugin_type> <plugin_name>

     This displays available options, configuration, and documentation for that plugin.
   • Example:

     ansible-doc -t lookup file

3. Exploring Other Plugin Types:
   • Substitute plugin_type with any desired type. Common plugin types include: action, become, callback, cache, connection, filter, inventory, lookup, strategy, test, vars, and shell.
   • Example to list all filter plugins:

     ansible-doc -t filter -l

4. Verifying Plugin Discovery Paths:
   • Ensure your custom plugins are placed in recognized directories so that ansible-doc discovers them.
   • Custom directory paths can be set via the configuration file or environment variables, as explained in the previous sections.
5. Helpful Tips:
   • Use ansible-doc -h to see all available options and usage patterns for discovery.
   • The -s flag produces a playbook snippet for select plugin types, aiding rapid integration.

With these built-in commands, you can efficiently browse, learn about, and leverage the full library of Ansible plugins—enabling greater automation, extension, and customization.