/devops-ansible

name: devops-ansible
description: 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 (fuse-security:security-expert).
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)"
user-invocable: true
references:
  - references/versions-support.md
  - references/inventory-variables.md
  - references/playbooks-roles-collections.md
  - references/idempotency-handlers-errors.md
  - references/safe-run-protocol.md
  - references/vault-secrets.md
  - references/performance-tuning.md
  - references/testing-lint-molecule.md
  - references/execution-environments.md
  - references/ansible-vs-iac-awx.md
  - references/templates/ansible.cfg
  - references/templates/inventory.yml
  - references/templates/group_vars-all.yml
  - references/templates/site-rolling-update.yml
  - references/templates/requirements.yml
  - references/templates/ansible-lint.yml
  - references/templates/role-skeleton/tasks/main.yml
  - references/templates/role-skeleton/handlers/main.yml
  - references/templates/role-skeleton/defaults/main.yml
  - references/templates/role-skeleton/meta/main.yml
  - references/templates/role-skeleton/templates/service.conf.j2
  - references/templates/molecule/molecule.yml
  - references/templates/molecule/inventory/hosts.yml
  - references/templates/molecule/converge.yml
  - references/templates/molecule/verify.yml
  - references/templates/execution-environment.yml
  - references/templates/ansible-navigator.yml
related-skills:
  - devops-iac
  - devops-linux
  - devops-secrets
  - devops-cicd
  - devops-proxmox
  - devops-openstack
  - devops-virtualization
  - devops-docker

<objective> Covers configuration management with Ansible: picking versions, structuring a project, inventory and variables, playbooks, roles and collections, idempotent tasks, handlers and error handling, Vault, safe execution against real hosts (check mode, diff, limit, rolling batches), performance, testing (ansible-lint, Molecule) and execution environments. Does not cover Terraform/OpenTofu (devops-iac), host-level Linux administration (devops-linux), CI pipelines (devops-cicd) or external secret stores (devops-secrets); AWX/AAP is a pointer only. </objective>

DevOps Ansible

Agent Workflow (MANDATORY)

Before ANY playbook, role or inventory change, spawn in parallel, one `Agent` call each with a `name`:

1. **fuse-ai-pilot:explore-codebase** - find `ansible.cfg`, `inventories/`, `roles/`, `collections/requirements.yml`, `group_vars/`, vault files 2. **fuse-ai-pilot:research-expert** - verify module options for the installed collection versions at docs.ansible.com 3. **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](references/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](references/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

1. **Version first** - `ansible --version` and `ansible-galaxy collection list` before writing a task; module options differ per collection version; unknown option = `ansible-doc <fqcn>` 2. **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) 3. **Production runs are proposed, not run** - s