DevOps Ansible
Agent Workflow (MANDATORY)
Before ANY playbook, role or inventory change, spawn in parallel, one spawn_agent call each:
- explore-codebase - find
ansible.cfg, inventories/, roles/, collections/requirements.yml, group_vars/, vault files
- research-expert - verify module options for the installed collection versions at docs.ansible.com
- mcp__context7__query-docs -
/websites/ansible_projects_ansible, /ansible/ansible-lint, /ansible/molecule
Then read the environment read-only (ansible --version, ansible-galaxy collection list, ansible-inventory --graph, ansible-doc <fqcn>).
After changes, run sniper; against real hosts follow safe-run-protocol.md.
Versions (checked 2026-11-10)
ansible-core 2.22.0 is the latest (PyPI; needs Python >= 3.13 on the control node). The community package ansible 14.6.0 pins ansible-core ~=2.21.6 and needs Python >= 3.12; package 15.0.0 (on 2.22) is unreleased. ansible-core keeps the latest release plus two older ones. Details, Python matrix and sources: versions-support.md.
Pinned versions:
ansible-core: "2.22.0 (maintained lines 2.22, 2.21, 2.20; 2.19 EOL Nov 2026)"
ansible-community-package: "14.6.0 (ansible-core ~=2.21.6; 15.0.0 in development on 2.22)"
ansible-lint: "26.11.0"
molecule: "26.11.0"
ansible-navigator: "26.11.0"
ansible-builder: "3.2.0 (EE definition schema version 3)"
Overview
| Area |
Decision in one line |
| Install |
ansible package for batteries included; ansible-core + pinned requirements.yml for reproducible control nodes; EE container for CI |
| Inventory |
YAML files per environment, group_vars/ and host_vars/ next to them; dynamic inventory through plugins, not scripts |
| Content |
FQCN everywhere; roles for reusable units; collections pinned by version range in requirements.yml |
| Tasks |
Native modules first; command/shell only with changed_when/failed_when; state: present over latest |
| Run |
--check --diff --limit first, then canary host, then serial batches with max_fail_percentage |
| Secrets |
Vault with --vault-id labels or an external store; no_log: true on tasks handling secrets; diff: false on secret files |
| Quality |
ansible-lint profile production, Molecule with an idempotence step |
Critical Rules
- Version first -
ansible --version and ansible-galaxy collection list before writing a task; module options differ per collection version; unknown option = ansible-doc <fqcn>
- Check, diff, limit before any real run -
ansible-playbook --check --diff --limit <host>; check mode is a prediction, not a guarantee (modules without check support are skipped)
- Production runs are proposed, not run - show playbook, inventory,
--limit, tags, --become scope and expected changes, wait for the user's go (safe-run-protocol.md)
- Canary then rolling - one host, then
serial: [1, 5, 10] with max_fail_percentage; never hosts: all plus strategy: free on a stateful tier
- Idempotent or it does not ship - second run reports
changed=0; command/shell without changed_when is a defect (idempotency-handlers-errors.md)
- Never print or commit a secret - vault passwords out of the repo,
no_log: true, names and keys only in reports (vault-secrets.md)
- Never invent a module, option or collection - cite the docs.ansible.com or collection page; unknown = "not verified"
Architecture
infra-ansible/
├── ansible.cfg # inventory path, roles_path, collections_path, forks, pipelining
├── collections/requirements.yml # pinned collections (and roles)
├── inventories/
│ ├── production/{hosts.yml,group_vars/,host_vars/}
│ └── staging/{hosts.yml,group_vars/,host_vars/}
├── playbooks/site.yml # imports per-tier playbooks
├── roles/<role>/{tasks,handlers,defaults,vars,templates,files,meta}/
├── molecule/default/ # per-role or per-collection scenarios
├── .ansible-lint # profile and skip/warn lists
└── execution-environment.yml # only when running in an EE
Reference Guide
Concepts
| Topic |
Reference |
When to Consult |
| Versions and support |
versions-support.md |
Choosing core/package, Python on control and managed nodes |
| Inventory and variables |
inventory-variables.md |
Static/dynamic inventory, precedence, groups |
| Playbooks, roles, collections |
playbooks-roles-collections.md |
Layout, FQCN, galaxy, requirements.yml, Jinja2 |
| Idempotency and errors |
idempotency-handlers-errors.md |
changed_when, handlers, block/rescue/always, tags |
| Safe execution |
safe-run-protocol.md |
ANY run against real hosts, become, reboot, state: absent |
| Vault and secrets |
vault-secrets.md |
Encrypting values, vault ids, no_log |
| Performance |
performance-tuning.md |
forks, pipelining, fact caching, strategies |
| Testing |
testing-lint-molecule.md |
ansible-lint profiles, Molecule, ansible-test |
| Execution environments |
execution-environments.md |
ansible-navigator, ansible-builder |
| Ansible vs IaC, AWX |
ansible-vs-iac-awx.md |
Tool choice, handoff to devops-iac |
Templates
| Template |
When to Use |
| ansible.cfg |
New project defaults: forks, pipelining, fact cache |
| inventory.yml |
YAML inventory with groups, ranges and group vars |
| group_vars-all.yml |
Variables with the vault_ indirection pattern |
| site-rolling-update.yml |
Rolling update: serial, max_fail_percentage, block/rescue |
| requirements.yml |
Pinned collections and roles |
| ansible-lint.yml |
Lint config (copy to .ansible-lint) |
| role-skeleton/ |
New role: tasks, handlers, defaults, meta, template |
| molecule/ |
Ansible-native Molecule scenario |
| execution-environment.yml |
ansible-builder v3 definition |
| ansible-navigator.yml |
Navigator settings with an EE |
Other files of the directory templates above: role-skeleton/handlers/main.yml, role-skeleton/defaults/main.yml, role-skeleton/meta/main.yml, role-skeleton/templates/service.conf.j2, molecule/inventory/hosts.yml, molecule/converge.yml, molecule/verify.yml.
Quick Reference
ansible --version; ansible-galaxy collection list # versions first
ansible-inventory -i inventories/staging --graph # what the inventory resolves to
ansible-doc ansible.builtin.template # option names for the installed version
ansible-lint # from the project root
ansible-playbook -i inventories/staging playbooks/site.yml --syntax-check
ansible-playbook -i inventories/staging playbooks/site.yml --check --diff --limit web01 # read-only prediction
ansible-playbook -i inventories/production playbooks/site.yml --limit web01 # after the user's go
Best Practices
DO
- Pin collections (
version: ">=x,<y") and the ansible-core line in CI; install from requirements.yml
- Keep one inventory directory per environment so
group_vars never leak across them
- Add
no_log: true to tasks that handle credentials and diff: false where --diff would print them
- Use
ansible.builtin.assert for pre-flight guards (target group, free disk, version) inside pre_tasks
DON'T
- Run
ansible-playbook against production from a prompt without --limit and the user's go
- Use
ignore_errors: true to hide a failing task; use failed_when or block/rescue
- Use
state: latest for packages in production plays
- Rely on
-e extra vars for routine config: they beat every other variable source
Related skills
- devops-iac
- devops-linux
- devops-secrets
- devops-cicd
- devops-proxmox
- devops-openstack
- devops-virtualization
- devops-docker
1---2name: devops-ansible-23description: Use when writing, reviewing, testing or running Ansible - choosing ansible-core and community package versions (control node and managed node Python), static and dynamic inventory with group_vars/host_vars, variable precedence, playbooks, roles and collections (ansible-galaxy, requirements.yml, FQCN), idempotency (changed_when/failed_when), handlers, tags, Jinja2 templates, Ansible Vault and no_log, privilege escalation, check mode and diff mode, --limit, serial/rolling updates and max_fail_percentage, block/rescue/always, performance (forks, pipelining, fact caching, strategy), ansible-lint, Molecule, execution environments (ansible-navigator, ansible-builder), project layout, and Ansible versus Terraform/OpenTofu. Not for Terraform/OpenTofu state and modules (devops-iac), Linux host internals (devops-linux), CI pipeline authoring (devops-cicd), secret stores (devops-secrets), Proxmox or OpenStack platform internals (devops-proxmox, devops-openstack) or a security hardening audit (security-expert).4metadata:5 source: https://skillmd.com/skills/fusengine/devops-ansible-26---78<objective>9Covers configuration management with Ansible: picking versions, structuring a10project, inventory and variables, playbooks, roles and collections, idempotent11tasks, handlers and error handling, Vault, safe execution against real hosts12(check mode, diff, limit, rolling batches), performance, testing (ansible-lint,13Molecule) and execution environments. Does not cover Terraform/OpenTofu14(devops-iac), host-level Linux administration (devops-linux), CI pipelines15(devops-cicd) or external secret stores (devops-secrets); AWX/AAP is a pointer only.16</objective>1718# DevOps Ansible1920## Agent Workflow (MANDATORY)2122Before ANY playbook, role or inventory change, spawn in parallel, one `spawn_agent` call each:23241. **explore-codebase** - find `ansible.cfg`, `inventories/`, `roles/`, `collections/requirements.yml`, `group_vars/`, vault files252. **research-expert** - verify module options for the installed collection versions at docs.ansible.com263. **mcp__context7__query-docs** - `/websites/ansible_projects_ansible`, `/ansible/ansible-lint`, `/ansible/molecule`2728Then read the environment read-only (`ansible --version`, `ansible-galaxy collection list`, `ansible-inventory --graph`, `ansible-doc <fqcn>`).29After changes, run **sniper**; against real hosts follow [safe-run-protocol.md](references/safe-run-protocol.md).3031## Versions (checked 2026-11-10)3233ansible-core 2.22.0 is the latest (PyPI; needs Python >= 3.13 on the control node). The community package `ansible` 14.6.0 pins `ansible-core ~=2.21.6` and needs Python >= 3.12; package 15.0.0 (on 2.22) is unreleased. ansible-core keeps the latest release plus two older ones. Details, Python matrix and sources: [versions-support.md](references/versions-support.md).3435Pinned versions:3637```yaml38ansible-core: "2.22.0 (maintained lines 2.22, 2.21, 2.20; 2.19 EOL Nov 2026)"39ansible-community-package: "14.6.0 (ansible-core ~=2.21.6; 15.0.0 in development on 2.22)"40ansible-lint: "26.11.0"41molecule: "26.11.0"42ansible-navigator: "26.11.0"43ansible-builder: "3.2.0 (EE definition schema version 3)"44```4546## Overview4748| Area | Decision in one line |49|------|----------------------|50| **Install** | `ansible` package for batteries included; `ansible-core` + pinned `requirements.yml` for reproducible control nodes; EE container for CI |51| **Inventory** | YAML files per environment, `group_vars/` and `host_vars/` next to them; dynamic inventory through plugins, not scripts |52| **Content** | FQCN everywhere; roles for reusable units; collections pinned by version range in `requirements.yml` |53| **Tasks** | Native modules first; `command`/`shell` only with `changed_when`/`failed_when`; `state: present` over `latest` |54| **Run** | `--check --diff --limit` first, then canary host, then `serial` batches with `max_fail_percentage` |55| **Secrets** | Vault with `--vault-id` labels or an external store; `no_log: true` on tasks handling secrets; `diff: false` on secret files |56| **Quality** | `ansible-lint` profile `production`, Molecule with an idempotence step |5758## Critical Rules59601. **Version first** - `ansible --version` and `ansible-galaxy collection list` before writing a task; module options differ per collection version; unknown option = `ansible-doc <fqcn>`612. **Check, diff, limit before any real run** - `ansible-playbook --check --diff --limit <host>`; check mode is a prediction, not a guarantee (modules without check support are skipped)623. **Production runs are proposed, not run** - show playbook, inventory, `--limit`, tags, `--become` scope and expected changes, wait for the user's go ([safe-run-protocol.md](references/safe-run-protocol.md))634. **Canary then rolling** - one host, then `serial: [1, 5, 10]` with `max_fail_percentage`; never `hosts: all` plus `strategy: free` on a stateful tier645. **Idempotent or it does not ship** - second run reports `changed=0`; `command`/`shell` without `changed_when` is a defect ([idempotency-handlers-errors.md](references/idempotency-handlers-errors.md))656. **Never print or commit a secret** - vault passwords out of the repo, `no_log: true`, names and keys only in reports ([vault-secrets.md](references/vault-secrets.md))667. **Never invent a module, option or collection** - cite the docs.ansible.com or collection page; unknown = "not verified"6768## Architecture6970```71infra-ansible/72├── ansible.cfg # inventory path, roles_path, collections_path, forks, pipelining73├── collections/requirements.yml # pinned collections (and roles)74├── inventories/75│ ├── production/{hosts.yml,group_vars/,host_vars/}76│ └── staging/{hosts.yml,group_vars/,host_vars/}77├── playbooks/site.yml # imports per-tier playbooks78├── roles/<role>/{tasks,handlers,defaults,vars,templates,files,meta}/79├── molecule/default/ # per-role or per-collection scenarios80├── .ansible-lint # profile and skip/warn lists81└── execution-environment.yml # only when running in an EE82```8384## Reference Guide8586### Concepts8788| Topic | Reference | When to Consult |89|-------|-----------|-----------------|90| **Versions and support** | [versions-support.md](references/versions-support.md) | Choosing core/package, Python on control and managed nodes |91| **Inventory and variables** | [inventory-variables.md](references/inventory-variables.md) | Static/dynamic inventory, precedence, groups |92| **Playbooks, roles, collections** | [playbooks-roles-collections.md](references/playbooks-roles-collections.md) | Layout, FQCN, galaxy, requirements.yml, Jinja2 |93| **Idempotency and errors** | [idempotency-handlers-errors.md](references/idempotency-handlers-errors.md) | changed_when, handlers, block/rescue/always, tags |94| **Safe execution** | [safe-run-protocol.md](references/safe-run-protocol.md) | ANY run against real hosts, become, reboot, state: absent |95| **Vault and secrets** | [vault-secrets.md](references/vault-secrets.md) | Encrypting values, vault ids, no_log |96| **Performance** | [performance-tuning.md](references/performance-tuning.md) | forks, pipelining, fact caching, strategies |97| **Testing** | [testing-lint-molecule.md](references/testing-lint-molecule.md) | ansible-lint profiles, Molecule, ansible-test |98| **Execution environments** | [execution-environments.md](references/execution-environments.md) | ansible-navigator, ansible-builder |99| **Ansible vs IaC, AWX** | [ansible-vs-iac-awx.md](references/ansible-vs-iac-awx.md) | Tool choice, handoff to devops-iac |100101### Templates102103| Template | When to Use |104|----------|-------------|105| [ansible.cfg](references/templates/ansible.cfg) | New project defaults: forks, pipelining, fact cache |106| [inventory.yml](references/templates/inventory.yml) | YAML inventory with groups, ranges and group vars |107| [group_vars-all.yml](references/templates/group_vars-all.yml) | Variables with the `vault_` indirection pattern |108| [site-rolling-update.yml](references/templates/site-rolling-update.yml) | Rolling update: serial, max_fail_percentage, block/rescue |109| [requirements.yml](references/templates/requirements.yml) | Pinned collections and roles |110| [ansible-lint.yml](references/templates/ansible-lint.yml) | Lint config (copy to `.ansible-lint`) |111| [role-skeleton/](references/templates/role-skeleton/tasks/main.yml) | New role: tasks, handlers, defaults, meta, template |112| [molecule/](references/templates/molecule/molecule.yml) | Ansible-native Molecule scenario |113| [execution-environment.yml](references/templates/execution-environment.yml) | ansible-builder v3 definition |114| [ansible-navigator.yml](references/templates/ansible-navigator.yml) | Navigator settings with an EE |115116Other files of the directory templates above: [role-skeleton/handlers/main.yml](references/templates/role-skeleton/handlers/main.yml), [role-skeleton/defaults/main.yml](references/templates/role-skeleton/defaults/main.yml), [role-skeleton/meta/main.yml](references/templates/role-skeleton/meta/main.yml), [role-skeleton/templates/service.conf.j2](references/templates/role-skeleton/templates/service.conf.j2), [molecule/inventory/hosts.yml](references/templates/molecule/inventory/hosts.yml), [molecule/converge.yml](references/templates/molecule/converge.yml), [molecule/verify.yml](references/templates/molecule/verify.yml).117118## Quick Reference119120```bash121ansible --version; ansible-galaxy collection list # versions first122ansible-inventory -i inventories/staging --graph # what the inventory resolves to123ansible-doc ansible.builtin.template # option names for the installed version124ansible-lint # from the project root125ansible-playbook -i inventories/staging playbooks/site.yml --syntax-check126ansible-playbook -i inventories/staging playbooks/site.yml --check --diff --limit web01 # read-only prediction127ansible-playbook -i inventories/production playbooks/site.yml --limit web01 # after the user's go128```129130## Best Practices131132### DO133- Pin collections (`version: ">=x,<y"`) and the ansible-core line in CI; install from `requirements.yml`134- Keep one inventory directory per environment so `group_vars` never leak across them135- Add `no_log: true` to tasks that handle credentials and `diff: false` where `--diff` would print them136- Use `ansible.builtin.assert` for pre-flight guards (target group, free disk, version) inside `pre_tasks`137138### DON'T139- Run `ansible-playbook` against `production` from a prompt without `--limit` and the user's go140- Use `ignore_errors: true` to hide a failing task; use `failed_when` or `block/rescue`141- Use `state: latest` for packages in production plays142- Rely on `-e` extra vars for routine config: they beat every other variable source143144---145146## Related skills147148- devops-iac149- devops-linux150- devops-secrets151- devops-cicd152- devops-proxmox153- devops-openstack154- devops-virtualization155- devops-docker