mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-08 11:46:35 +00:00
kevinveenbirkenbachandClaude Opus 4.7
16bdbf03d7
Three classes of drift cleaned up across 85 .md files:
- Em-dashes: replaced ` — ` with the contextually correct separator
(colon for `term: explanation`, period to split clauses across
sentences/source lines, parentheses for asides, semicolon for
tight-linked continuations). Two intentional exceptions remain
in `docs/contributing/documentation.md` (the rule literal) and
inside a fenced ```sh block in `docs/contributing/actions/debugging/ci.md`.
- SPOT self-labels: rewrote "This is the SPOT for X" to describe
the subject directly ("This directory holds X" / "This file
describes X"). Cross-references to other artefacts' canonical
role remain unchanged.
- Heading-emoji position: moved leading-emoji headings (`# 🧩 Title`)
to trailing position (`# Title 🧩`) per the headline rule that
emojis MUST come after the title text.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
119 lines
4.2 KiB
Markdown
119 lines
4.2 KiB
Markdown
# 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 ...`
|