Interpreting an Ansible Playbook

What it is

An Ansible playbook is a YAML file that lists the tasks to run on a group of hosts.

Each task calls a module, which is a small unit of work such as installing a package or starting a service. Reading a playbook means finding the hosts, then going through the tasks in order.

Ansible is agentless. It connects over SSH, or an API for network devices, so nothing needs to be installed on the managed hosts.

How it works

A playbook holds one or more plays, and each play has hosts, tasks and options.

A sample playbook

---
- name: Set up a web server
  hosts: webservers
  become: true
  vars:
    web_package: nginx

  tasks:
    - name: Install the web server package
      ansible.builtin.apt:
        name: "{{ web_package }}"
        state: present
        update_cache: true

    - name: Create a service account
      ansible.builtin.user:
        name: webadmin
        shell: /bin/bash
        state: present

    - name: Copy the site configuration
      ansible.builtin.copy:
        src: site.conf
        dest: /etc/nginx/conf.d/site.conf
        mode: "0644"
      notify: Restart nginx

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

  handlers:
    - name: Restart nginx
      ansible.builtin.service:
        name: nginx
        state: restarted

Reading it top to bottom

• name is a label for humans. It does not change behaviour.
• hosts: webservers picks the group from the inventory that the play runs on.
• become: true runs the tasks with elevated privileges, as with sudo.
• vars defines variables, and {{ web_package }} inserts the value.
• Each task names a module and gives its arguments.

The play therefore installs the nginx package, creates a user named webadmin, copies a configuration file, and makes sure the service is running and set to start at boot. The handler restarts nginx, but only if the copy task changed something.

Common modules

The state argument

Most modules are described by the state they should reach, not by the action to take.

Because modules check the current state first, running a playbook again changes nothing if the host already matches. This property is called idempotence.

Handlers

A handler is a task that runs only when another task reports a change. It runs once at the end of the play. This is why a service restarts only when its configuration file really changed.

The inventory

The inventory lists the hosts and groups that playbooks can target.

[webservers]
web1.example
web2.example

[dbservers]
db1.example

Running a playbook

$ ansible-playbook -i inventory.ini site.yml
$ ansible-playbook -i inventory.ini site.yml --check

The --check option performs a dry run. The output ends with a recap, which counts tasks as ok, changed, failed or skipped.

Describing the workflow

When you interpret a playbook, answer in a sentence. For the sample above: it installs nginx on the web servers, creates a service account, deploys a configuration file, and ensures that nginx is started and enabled, with a restart if the file changes.

Stopping a service

A task with state: stopped and enabled: false stops a service and keeps it from starting at boot.

    - name: Stop and disable the service
      ansible.builtin.service:
        name: nginx
        state: stopped
        enabled: false