Beginner8 min readLesson 3 of 5

Writing and running a playbook

A playbook is a YAML file of plays. Each play picks a group of hosts and lists tasks, and each task calls one module with its arguments. You run it with ansible-playbook, can preview it with --check and --diff, and read the result in the PLAY RECAP, which counts what was ok, changed or failed.

A first playbook

webserver.yml

- name: Configure the web servers
  hosts: web
  become: true
  vars:
    site_title: Payroll status

  tasks:
    - name: Install nginx
      ansible.builtin.package:
        name: nginx
        state: present

    - name: Publish the status page
      ansible.builtin.template:
        src: index.html.j2
        dest: /usr/share/nginx/html/index.html
        mode: "0644"
      notify: Reload nginx

    - name: Make sure nginx is running and starts at boot
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: true

  handlers:
    - name: Reload nginx
      ansible.builtin.service:
        name: nginx
        state: reloaded

The parts

Reading the playbookWhat it means

- name: / hosts: web

One play, aimed at the web group from the inventory. A playbook can hold several plays.

become: true

Run the tasks with elevated rights, usually through sudo.

vars:

Variables. Inside templates and tasks they are used as {{ site_title }} (Jinja2 syntax).

tasks:

Run in order, top to bottom, on every host in the play. Each has a name and one module.

notify: / handlers:

A handler runs once, at the end of the play, and only if a task that notifies it reported 'changed'.

Run it, preview first

A dry run, then the real run

$ ansible-playbook -i inventory.ini webserver.yml --check --diff
$ ansible-playbook -i inventory.ini webserver.yml

PLAY RECAP *********************************************************
web01.example.com : ok=4  changed=2  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0
web02.example.com : ok=4  changed=2  unreachable=0  failed=0  skipped=0  rescued=0  ignored=0

--check is a dry run: it reports what *would* change and changes nothing. Most modules support it.
--diff shows the line-by-line differences for files it would change.
--limit web01.example.com runs against one host only, a common way to try something on one machine first.

In the PLAY RECAP, ok counts tasks that ran successfully (including those that changed something), changed counts the ones that actually changed something, and failed and unreachable are the ones to investigate. By default, when a task fails on a host, Ansible stops working on that host and carries on with the others.

TRY IT YOURSELF

Which ansible-playbook option does a dry run that reports changes without making them?

Show a hint

Two dashes and a word meaning 'verify'.

Show the solution

--check (often used together with --diff).

Examples are for learning. Run commands and jobs only on a system you are authorised to use, such as a training or test system, and never on production without approval.

Common mistakes

Tabs in YAML

YAML does not allow tabs for indentation, so the playbook fails to load. Set your editor to insert spaces.

Skipping the dry run

--check --diff shows what would change before it changes. It costs seconds and saves incidents.

Expecting a handler to run straight away

Handlers run at the end of the play, and only if something notified them with a change.

What you will see at work

Pipelines typically run ansible-playbook in the deploy stage, with the inventory for the target environment.
Reviewers read the --check --diff output attached to a change before approving a production run.
Good task names matter: they are what appears in the output and in Automation Platform's job logs.

Key terms

Playbook (Ansible)Handler (Ansible)

Check your understanding.
Take this lesson's quiz and save your progress. Free.

Take the lesson quiz

← Inventory, modules and ad-hoc commands Run it twice: idempotence, roles and Vault →