Plays, Playbooks, Roles, Variables and Facts
Playbook anatomy
A playbook is a YAML list of plays. Each play names a hosts pattern plus tasks or roles, and may set become, vars, vars_files, gather_facts, serial, pre_tasks, post_tasks, handlers and tags. Tasks call one module with name: and arguments.
Handlers
A handler is notified only when the notifying task reports changed, and runs once at the end of the play no matter how many tasks notified it. meta: flush_handlers forces them to run earlier. The notify string must match the handler name exactly.
Roles
ansible-galaxy init myrole scaffolds tasks/main.yml, handlers/main.yml, defaults/main.yml, vars/main.yml, files/, templates/, meta/main.yml and tests/. files/ and templates/ are searched automatically, so src: app.conf.j2 needs no path.
Variable precedence (low to high, abbreviated)
role defaults → inventory group_vars/all → group_vars/<group> → host_vars → gathered facts → play vars → play vars_files → role vars → block vars → task vars → include_vars → set_fact/registered vars → extra vars (-e).
Facts
Gathered facts live in ansible_facts; reference them as ansible_facts['distribution']. gather_facts: false plus a targeted setup task speeds runs. Custom facts dropped in /etc/ansible/facts.d/*.fact appear under ansible_facts['local'].
Traps
when: takes a bare Jinja expression - when: ansible_facts['os_family'] == 'RedHat', never wrapped in {{ }}. Role defaults are the weakest variables (easy to override) while vars/main.yml is strong. register yields a dict: use .stdout, .rc, or .results for loops.
Rule of thumb
Put tunable values in defaults/main.yml and rarely-changed values in vars/main.yml; anything a user must be able to override belongs in defaults.