IaC
Ansible — inventory, playbooks, and idempotent runs
Agentless config management with Ansible: define hosts in inventory, run ad-hoc modules or playbooks over SSH, and converge to desired state idempotently — always dry-run with --check --diff before applying.
Quick reference — reach for these first
ansible all -i INVENTORY -m pingAd-hoc reachability + Python check on every hostansible-playbook SITE.yml -i INVENTORY --check --diffDry run; print what WOULD change, no writesansible-playbook SITE.yml -i INVENTORYApply the play; converge hosts to desired stateansible-playbook SITE.yml -i INVENTORY --limit HOST --tags TAGRestrict to some hosts and some tagged tasksansible-vault encrypt SECRETS.ymlEncrypt a secrets file at rest (edit with ansible-vault edit)How an Ansible run flows: control node → inventory → managed hosts
Text equivalent: A left box labeled Control node runs ansible and ansible-playbook. It reads an Inventory (static INI/YAML or a dynamic plugin) that resolves to groups of managed hosts. Over SSH, Ansible pushes a module to each host, runs it to enforce desired state, and removes it. A dashed check-mode arrow shows --check/--diff previewing changes without writing. On a second run, modules report changed=0 because the hosts already match desired state (idempotency).
Common tasks
Task · Command · Check / expect
| Task | Command | Check / expect |
|---|---|---|
| CONFIRM target context: resolve inventory to the actual host tree | ansible-inventory -i INVENTORY --graph | Groups and host names match the environment you intend (not prod by accident) |
| Preview which hosts a pattern will touch (no changes) | ansible WEBSERVERS -i INVENTORY --list-hosts | Only the hosts you expect are listed |
| Test connectivity and remote Python | ansible all -i INVENTORY -m ping | Each host returns "ping": "pong" with SUCCESS |
| Run a safe ad-hoc command (read-only module) | ansible all -i INVENTORY -m command -a 'uptime' | rc=0 and stdout per host; command module is not idempotent, keep it read-only |
| Gather and inspect facts for one host | ansible HOST -i INVENTORY -m setup -a 'filter=ansible_distribution*' | OS/distribution facts return; use these in when: conditions |
| Validate playbook syntax before any run | ansible-playbook SITE.yml --syntax-check | Prints the playbook path with no YAML/parse errors |
| Dry run and show the diff (PREVIEW, no changes) | ansible-playbook SITE.yml -i INVENTORY --check --diff | PLAY RECAP shows would-be changed=N; nothing is actually modified |
| List the tasks/tags a play contains | ansible-playbook SITE.yml --list-tasks --list-tags | Confirms task names and tag names before using --tags |
| Apply to a single host first (blast-radius control) | ansible-playbook SITE.yml -i INVENTORY --limit HOST | changed>0 on first apply; failed=0 in PLAY RECAP |
| CHANGES PRODUCTION: run a tagged subset across a group | ansible-playbook SITE.yml -i INVENTORY --limit WEBSERVERS --tags deploy | Only deploy-tagged tasks run; handlers flush at play end |
| Escalate privileges when a task needs root | ansible-playbook SITE.yml -i INVENTORY --become --ask-become-pass | Privileged tasks succeed; prefer become: true in the play over CLI flags |
| Encrypt secrets and run with the vault password | ansible-playbook SITE.yml -i INVENTORY -e @SECRETS.yml --ask-vault-pass | Play runs; vaulted values never printed in output |
| Prove idempotency: run the SAME play a second time | ansible-playbook SITE.yml -i INVENTORY | PLAY RECAP shows changed=0 — converged, nothing to do |
Write a small play, dry-run it, apply it, then prove idempotency
check-then-apply
printf '[web]\nweb1 ansible_host=203.0.113.10 ansible_user=deploy\n' > inventory.ini
ansible-inventory -i inventory.ini --graph
# @all:
# |--@web:
# | |--web1cat > site.yml <<'YAML'
- name: Web baseline
hosts: web
become: true
tasks:
- name: Ensure nginx present
ansible.builtin.package: { name: nginx, state: present }
- name: Deploy index page
ansible.builtin.copy:
content: "hello from {{ inventory_hostname }}\n"
dest: /var/www/html/index.html
YAMLansible-playbook site.yml -i inventory.ini --syntax-check && ansible-playbook site.yml -i inventory.ini --check --diff
# PLAY RECAP
# web1 : ok=3 changed=2 unreachable=0 failed=0 (check mode)ansible-playbook site.yml -i inventory.ini
# web1 : ok=3 changed=2 unreachable=0 failed=0ansible-playbook site.yml -i inventory.ini
# web1 : ok=3 changed=0 unreachable=0 failed=0 <- changed=0 == convergedTroubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next check |
|---|---|---|---|
| Permission denied (publickey) / auth fails on connect | ssh -o BatchMode=yes USER@HOST true, then re-run with ansible ... -vvv | Whether it is an SSH key/user problem (outside Ansible) vs. an Ansible config issue | Set ansible_user / ansible_ssh_private_key_file in inventory or use --private-key; load the key into ssh-agent |
| Host flagged UNREACHABLE in the recap | ansible HOST -i INVENTORY -m ping -vvv | If the transport (DNS, port 22, firewall, host key) is the failure, not a task | Fix name resolution / network, or set ansible_host and ansible_port; accept the host key or set host_key_checking appropriately |
| A task reports changed=yes on every run (not idempotent) | Re-run with --check --diff and read which task reports the change | Whether a command/shell task is standing in for a proper module | Replace command/shell with a stateful module (copy, template, file, package, service) or add creates=/removes= guards |
| Task fails with permission denied writing/installing as non-root | Inspect the failing task for become; run that play with --become --ask-become-pass | That privilege escalation, not the module args, is missing | Add become: true (and become_user if needed) to the play or task; ensure sudo is configured on the host |
| Playbook aborts at parse time with a YAML/syntax error | ansible-playbook SITE.yml --syntax-check | The error is structural (indentation, mapping) before any host is touched | Fix the reported line; validate indentation and quoting, then re-run --syntax-check until clean |
| Runs are very slow across many hosts | Time a run and check forks: ansible-config dump | grep -i forks | Whether low parallelism or repeated fact gathering is the cost | Raise forks (-f 20 or in ansible.cfg), set gather_facts: false where unneeded, and enable fact caching / SSH pipelining |
References
- Ansible documentation (home)docs.ansible.com
- Intro to playbooksdocs.ansible.com
- How to build your inventorydocs.ansible.com
- Validating tasks: check mode and diffdocs.ansible.com
- Encrypting content with Ansible Vaultdocs.ansible.com
ansible-core 2.16+ on a Linux/macOS control node; managed hosts reachable over SSH with Python 3 present.