Your first playbook

Plays, tasks, and YAML structure.

Beginner12 min · lesson 4 of 12

A playbook is a YAML file that describes automation: one or more plays, each mapping a group of hosts to an ordered list of tasks. It is the repeatable, version-controlled form of what you would otherwise run ad-hoc — and because it is declarative and idempotent, it is the artifact you actually keep and evolve. You run it with ansible-playbook.

site.yml

- name: Configure web servers
  hosts: web
  become: true                 # run tasks with sudo
  tasks:
    - name: Install nginx
      ansible.builtin.apt:
        name: nginx
        state: present
    - name: Ensure nginx is running and enabled
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

Running and reading results

ansible-playbook runs each task in order across all matching hosts, printing ok (already correct), changed (it acted), or failed for each. The PLAY RECAP at the end summarizes per host. A key habit: run with --check first (check mode) to preview what would change without changing anything, then run for real once the plan looks right — Ansible’s equivalent of a dry run.

terminal

$ ansible-playbook -i inventory.ini site.yml --check   # dry run: predict changes
$ ansible-playbook -i inventory.ini site.yml           # apply
PLAY RECAP
web1 : ok=3  changed=1  unreachable=0  failed=0
web2 : ok=3  changed=1  unreachable=0  failed=0

Name every task and use fully-qualified modules

Give every task a human name — it is your log and your debugging map when a run fails midway. And prefer fully-qualified module names (ansible.builtin.apt, not just apt): collections can ship same-named modules, and the FQCN removes the ambiguity, which matters as soon as you use community or cloud collections beyond the built-ins.

Modules & idempotencyVariables, facts & precedence