Ansible Plugins (plugins/) 🧩

This document is the central reference for plugin types and plugin placement in Infinito.Nexus.

Not to be confused with application addons. This plugins/ directory holds Ansible plugins (action / filter / lookup) that extend the automation engine itself. Some applications also call their own extensions “plugins” (e.g. Nextcloud, WordPress). Those application-level extensions, whatever the app calls them natively, are declared through the unified meta/addons/ contract, documented in Unified Addons. An app “plugin” is an addon; an Ansible plugin lives here.

Current Project Layout 🗂️

plugins/
├── action/   # custom action plugins
├── filter/   # custom Jinja2 filters
└── lookup/   # custom lookup plugins

Configured plugin paths in this repository are defined in ansible.cfg:

  • action_plugins = ./plugins/action

  • filter_plugins = ./plugins/filter

  • lookup_plugins = ./plugins/lookup

All Common Ansible Plugin Types 📚

The table below summarizes common Ansible plugin types and their conventional directory names.

Emoji

Plugin Type

Conventional Directory

Purpose

⚙️

action

action_plugins/ or plugins/action/

Wrap/extend module execution behavior at task runtime.

🔐

become

become_plugins/

Implement privilege escalation methods.

💾

cache

cache_plugins/

Persist gathered facts and cached data between runs.

📣

callback

callback_plugins/

React to play/task events (logging, reporting, notifications).

🖧

cliconf

cliconf_plugins/

Define CLI command transport behavior (mainly network platforms).

🔌

connection

connection_plugins/

Control how Ansible connects to targets (ssh, local, etc.).

🔍

filter

filter_plugins/ or plugins/filter/

Add Jinja2 filters for data transformation.

🌐

httpapi

httpapi_plugins/

API transport layer over HTTP(S), mainly for network devices.

🧭

inventory

inventory_plugins/

Build dynamic inventories from APIs, services, or files.

👉

lookup

lookup_plugins/ or plugins/lookup/

Resolve dynamic values during playbook processing.

🛰️

netconf

netconf_plugins/

NETCONF transport integration for network automation.

🐚

shell

shell_plugins/

Adjust shell command wrapping/execution behavior.

🧠

strategy

strategy_plugins/

Customize task scheduling/execution strategy.

✅

test

test_plugins/

Add Jinja2 tests used in conditions and templates.

📦

vars

vars_plugins/

Load variables from custom sources.

Which Plugin Type to Use 🧭

action ⚙️

Use when task execution behavior itself must be changed or wrapped.

Examples:

  • centralized retry logic (uri_retry.py),

  • argument normalization before module dispatch,

  • pre/post task orchestration.

filter 🔍

Use for pure data transformation in Jinja2 expressions.

Examples:

  • mapping/normalizing dictionaries,

  • deriving computed fields for templates,

  • deterministic formatting helpers.

lookup 👉

Use when a value must be dynamically resolved at runtime.

Examples:

  • computing IDs from role metadata,

  • resolving paths/version data,

  • reading structured project data for templates/tasks.

callback 📣

Use to hook into execution events and shape output/reporting.

inventory 🧭

Use when host/group data should come from a dynamic source.

strategy 🧠

Use to alter how tasks are scheduled/executed across hosts.

vars 📦

Use to load variables from custom backends.

connection, become, shell 🔌🔐🐚

Use to customize low-level execution and privilege mechanics.

cache 💾

Use to persist facts/results across runs for performance and consistency.

cliconf, httpapi, netconf 🖧🌐🛰️

Use in network automation contexts requiring protocol-specific transport behavior.

test ✅

Use to add custom Jinja2 test operators for conditional logic.

Best Practices 🧪

  • Keep plugin interfaces explicit and stable.

  • Keep plugin logic focused; move shared logic to utils/.

  • Add unit tests for plugin behavior and integration tests for end-to-end flows.

  • Prefer deterministic outputs and avoid hidden global state.

  • Document any plugin-specific task arguments in the plugin docstring and README.

References 🔗