DevOps Ansible
Agent Workflow (MANDATORY)
Before ANY playbook, role or inventory change, spawn in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - find
ansible.cfg,inventories/,roles/,collections/requirements.yml,group_vars/, vault files - fuse-ai-pilot: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 fuse-ai-pilot: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.
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 --versionandansible-galaxy collection listbefore 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,--becomescope and expected changes, wait for the user's go (safe-run-protocol.md) - Canary then rolling - one host, then
serial: [1, 5, 10]withmax_fail_percentage; neverhosts: allplusstrategy: freeon a stateful tier - Idempotent or it does not ship - second run reports
changed=0;command/shellwithoutchanged_whenis 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 |
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 fromrequirements.yml - Keep one inventory directory per environment so
group_varsnever leak across them - Add
no_log: trueto tasks that handle credentials anddiff: falsewhere--diffwould print them - Use
ansible.builtin.assertfor pre-flight guards (target group, free disk, version) insidepre_tasks
DON'T
- Run
ansible-playbookagainstproductionfrom a prompt without--limitand the user's go - Use
ignore_errors: trueto hide a failing task; usefailed_whenorblock/rescue - Use
state: latestfor packages in production plays - Rely on
-eextra vars for routine config: they beat every other variable source
