ansible-playbook: running a playbook

ansible-playbook takes a playbook — a YAML file with plays — and an inventory, connects to the machines and runs the tasks in order. What an inventory, modules and one-off ansible commands are is in the ansible article. The lab machine has ansible-core 2.16 and the ansible 9.2 package with 103 collections (ansible-galaxy collection list); there is no network to the outside, so collections cannot be installed from Galaxy.

The playbook for the examples is site.yml:

- name: Demo site
  hosts: local
  become: true
  vars:
    site_title: Demo
  tasks:
    - name: Site directory
      ansible.builtin.file:
        path: /srv/demo
        state: directory
        mode: "0755"

    - name: Page from template
      ansible.builtin.template:
        src: index.html.j2
        dest: /srv/demo/index.html
        mode: "0644"
      notify: Reload nginx
      tags: page

    - name: Stamp
      ansible.builtin.shell: date > /srv/demo/stamp

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

The template templates/index.html.j2 sits next to the playbook — template looks for src in the templates/ directory:

<h1>{{ site_title }}</h1>
<p>{{ ansible_hostname }}</p>

The inventory inventory.ini is one machine, this one, without SSH:

[local]
localhost ansible_connection=local

Reading a run

The first run (the stars in the headers are shortened, the summary line is wrapped):

student@node1:~/demo$ ansible-playbook -i inventory.ini site.yml

PLAY [Demo site] ***

TASK [Gathering Facts] ***
ok: [localhost]

TASK [Site directory] ***
changed: [localhost]

TASK [Page from template] ***
changed: [localhost]

TASK [Stamp] ***
changed: [localhost]

RUNNING HANDLER [Reload nginx] ***
changed: [localhost]

PLAY RECAP ***
localhost  : ok=5    changed=4    unreachable=0    failed=0
             skipped=0    rescued=0    ignored=0

Gathering Facts collects facts about the machine (ansible_hostname in the template comes from here). The state of a task on each machine:

The summary: PLAY RECAP

PLAY RECAP is a line per machine: how many tasks ended in which state.

A good repeat run is changed=0 failed=0. The exit code: 0 — all went well, 2 — a task failed on some machine, 4 — a machine is unreachable or the playbook could not be parsed (a YAML error, an unknown module), 1 — another error, for example no machines left.

The second run

TASK [Site directory] ***
ok: [localhost]

TASK [Page from template] ***
ok: [localhost]

TASK [Stamp] ***
changed: [localhost]

PLAY RECAP ***
localhost  : ok=4    changed=1    unreachable=0    failed=0

The file and template modules first look at the machine and change only the difference — this is idempotency. shell does not know what its command does and always reports changed. A good playbook gives changed=0 on the second run: for the task — a module instead of shell, or creates: (do not run if the file exists), or changed_when: (your own rule for what counts as a change).

Handlers

A handler is a task that runs only if another task called it with notify and that task reported changed. In the first run the template changed — nginx reloaded its config; in the second the template was ok, and there is no RUNNING HANDLER in the output.

• Handlers run at the end of the play, after all tasks, and each one once, however many tasks called it.
• notify looks up a handler by its name (or by listen) exactly, case-sensitively; a typo is the error ansible-playbook.
• If a task fails, handlers called before it do not run; --force-handlers runs them anyway. To run them before the end, use a task ansible.builtin.meta: flush_handlers.

Templates and variables

The template module builds a file from a template .j2: each {{ name }} is replaced with a variable's value. It compares the result with what is on the machine and reports changed only if they differ — that is why a template and its handler give changed=0 on a repeat run.

Where the values come from:

• the play's vars: — site_title: Demo;
• the machine's facts from Gathering Facts — ansible_hostname (node1);
• variables from the inventory — the machine's line or [group:vars];
• -e site_title=Changed from the command line — above all the others.

A variable that does not exist fails the task — ansible-playbook. A default right in the template — {{ site_title | default('Demo') }}. --check --diff shows what the template would change.

Checking without changes

--check (-C) runs the playbook without changing anything; --diff (-D) prints what would change in files:

student@node1:~/demo$ ansible-playbook -i inventory.ini site.yml \
> --check --diff -e site_title=Changed
...
TASK [Page from template] ***
--- before: /srv/demo/index.html
+++ after: /home/student/.ansible/tmp/…/index.html.j2
@@ -1,2 +1,2 @@
-<h1>Demo</h1>
+<h1>Changed</h1>
 <p>node1</p>

changed: [localhost]

TASK [Stamp] ***
skipping: [localhost]

RUNNING HANDLER [Reload nginx] ***
changed: [localhost]

PLAY RECAP ***
localhost  : ok=4    changed=2    unreachable=0    failed=0
             skipped=1    rescued=0    ignored=0

changed here means "would change": the file stayed the same, and nobody touched nginx. shell and command are skipped in check mode — --check tells you nothing about them. A playbook for which --check --diff after a run shows no changed at all describes the machine as it is.

• ansible — inventory, modules, one-off commands.
• ssh-keys — the key for logging in to the inventory machines.
• ssh-client — check the connection by hand.
• sudo — what become: true does.
• systemctl — the services handlers restart.
• diff-patch — how to read the --diff output.