# 🧩 Ansible Plugins (`plugins/`)

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

## 🗂️ Current Project Layout

```text
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

- Ansible plugin development: <https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html>
- Ansible plugin index (all types): <https://docs.ansible.com/ansible/latest/plugins/plugins.html>
- Ansible `ansible-doc` plugin types: `ansible-doc -t ...`