What a Playbook Actually Is
An Ansible playbook is a YAML file containing one or more 'plays'. Each play maps a group of hosts (drawn from your inventory) to a set of tasks that should be executed against them, in order, from top to bottom. Because it is plain YAML, a playbook is both human-readable documentation and an executable automation script at the same time.
Cricket analogy: A playbook is like a match-day team sheet handed to the twelfth man: it lists exactly which fielders (hosts) take which positions and in what batting order (task sequence), just as MS Dhoni would set field placements before each over.
Top-Level Keys in a Play
Each play typically begins with 'name' (a description shown in output), 'hosts' (the inventory group or pattern to target), and optional keys such as 'become' (privilege escalation), 'vars' (play-scoped variables), 'vars_files' (external variable files), 'gather_facts', and finally 'tasks' or 'roles'. The order of these keys does not affect execution, but 'tasks' entries within a play always run sequentially.
Cricket analogy: The 'hosts' key is like naming the fielding team before the toss, while 'become' is like the captain temporarily handing the gloves to a specialist wicketkeeper for a tricky spell.
---
- name: Configure web servers
hosts: webservers
become: true
gather_facts: true
vars:
http_port: 8080
app_env: production
vars_files:
- vars/webservers_secrets.yml
tasks:
- name: Ensure nginx is installed
ansible.builtin.apt:
name: nginx
state: present
update_cache: true
- name: Deploy nginx site configuration
ansible.builtin.template:
src: templates/site.conf.j2
dest: /etc/nginx/sites-available/app.conf
mode: '0644'
notify: Restart nginx
handlers:
- name: Restart nginx
ansible.builtin.service:
name: nginx
state: restarted
Multiple Plays and Roles
A single playbook file can contain multiple plays, each targeting a different host group with its own tasks — for example, one play to configure database servers and a second to configure web servers, both in the same file. As playbooks grow, tasks are usually factored out into 'roles', which are self-contained directories following a fixed structure (tasks/, handlers/, templates/, vars/, defaults/) that a play references via the top-level 'roles' key instead of inline 'tasks'.
Cricket analogy: Multiple plays in one file are like a tour itinerary covering both a Test match strategy for Day 1-5 and a separate T20 strategy for the following week, each with its own game plan but bundled in the same tour dossier.
Use 'ansible-playbook --syntax-check site.yml' before running any playbook against real infrastructure — it validates YAML structure and catches indentation or key errors without touching a single host.
- A playbook is a YAML file containing one or more plays.
- Each play maps a 'hosts' pattern to a list of 'tasks' executed top to bottom.
- Common play-level keys: name, hosts, become, vars, vars_files, gather_facts, tasks, handlers, roles.
- Key order within a play doesn't matter, but task order within 'tasks' always does.
- A single file can hold multiple plays targeting different host groups.
- Roles let you package reusable tasks, handlers, templates, and defaults into a standard directory layout.
- Always run --syntax-check before executing a playbook against real infrastructure.
Practice what you learned
1. What is the correct term for a single YAML file passed to ansible-playbook?
2. Which key determines which inventory hosts a play targets?
3. What is the primary benefit of extracting tasks into a role instead of leaving them inline?
4. Can a single playbook file contain more than one play?
5. Which command flag validates playbook YAML structure without touching any hosts?
Was this page helpful?
You May Also Like
Tasks and Modules
Understand how Ansible tasks invoke modules to perform idempotent actions, and how to choose the right module for the job.
Handlers and Notifications
Learn how Ansible handlers run only when notified by a change, and how to coordinate restarts and other follow-up actions efficiently.
Conditionals in Ansible
Use the 'when' clause and Jinja2 expressions to run tasks conditionally based on facts, variables, and previous task results.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics