kevinveenbirkenbachandClaude Opus 5.5
4fcf097e5b
The NFS backup rsynced the whole export and honoured only one exclude, the shared backup root. Volumes declared `backup: false` were copied anyway and then pulled a second time by remote-2-local; in the swarm DR drill of Magento#0 (run 40625679270) docs_sites alone (a full repo clone plus its prepared and work trees) took about 15.5 GiB per copy and filled the runner. The volume backup already skipped these through the backup_volume lookup; only the NFS path ignored the declaration. - utils/storage/nfs.py: volume_dir() names the state directory a volume binds to (pinned name or key), shared with compose_volumes; backup_disabled_dirs() returns every NFS-backed `backup: false` volume dir that no backed-up volume also binds to. - The role-local lookup backup_nfs_excludes feeds them into BKP_NFS_2_LOCAL_EXCLUDES next to the backup root; script.sh takes any number of excludes. Compose installs still pass only the backup root. - recover.py protects every live state directory the snapshot does not hold, so `rsync --delete` keeps the excluded volumes (model weights, the docs tree, caches) and volumes created after the snapshot instead of wiping them. - The swarm DR drill restores BACKUP_NFS_VOLUME, the first NFS volume not declared `backup: false`; PRIMARY_NFS_VOLUME stays for the drain tests. BookWyrm now drills bookwyrm_media; decidim, fusiondirectory, meta, coturn, svc-registry-cache and svc-registry-docker have nothing backed up on NFS and skip the drill. Measured: compose_volumes renders identically before and after for 291 roles across compose/swarm x local/nfs (1940 of 1940); the 15 excluded directories are exactly the backup-disabled device dirs; the systemd unit renders shell-safe on ansible-core 2.20 and 2.21 and stays byte-identical in compose and swarm-local. A new unit test runs the real script.sh over two generations and the real recover.py back into the export, and fails without the restore protection. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 unifiedmeta/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/actionfilter_plugins = ./plugins/filterlookup_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: docs.ansible.com
- Ansible plugin index (all types): docs.ansible.com
- Ansible
ansible-docplugin types:ansible-doc -t ...