Ansible playbooks

From ad-hoc to playbooks

Ad-hoc commands are one-off. A playbook is a file you keep in Git and run again and again. It is written in YAML. A playbook contains plays; a play says which hosts to target and lists tasks; a task calls one module with arguments and has a name that shows up in the output.

---
- name: Set up web servers for the college website
  hosts: web
  become: true
  vars:
    site_name: college.edu
    packages:
      - nginx
      - ufw
  tasks:
    - name: Install packages
      ansible.builtin.apt:
        name: "{{ packages }}"
        state: present
        update_cache: true

    - name: Deploy the nginx site config
      ansible.builtin.template:
        src: templates/site.conf.j2
        dest: /etc/nginx/sites-available/{{ site_name }}
        mode: "0644"
      notify: Reload nginx

    - name: Enable the site
      ansible.builtin.file:
        src: /etc/nginx/sites-available/{{ site_name }}
        dest: /etc/nginx/sites-enabled/{{ site_name }}
        state: link
      notify: Reload nginx

    - name: Copy the home page
      ansible.builtin.copy:
        src: files/index.html
        dest: /var/www/html/index.html
        owner: www-data
        mode: "0644"

    - 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

Useful modules

Variables

A variable is a named value used as {{ name }} (Jinja2 syntax). You can set variables in a play under vars, in files group_vars/web.yml (for every host in the web group), group_vars/all.yml (for every host), and host_vars/web1.college.edu.yml (for one host). Ansible has a long precedence order; the short version is: more specific wins (host over group, group over all), and extra vars on the command line (-e) win over everything. Role defaults have the lowest priority.

Facts

At the start of each play, Ansible gathers facts: information about every host, such as the OS family, distribution, IP addresses, memory and CPUs. They are available as ansible_facts, for example ansible_facts['os_family'] is "Debian" on Ubuntu. Run ansible web1.college.edu -m ansible.builtin.setup to see them all. Set gather_facts: false to skip this step when you do not need facts and want speed.

Handlers and notify

You want to reload nginx only when its config actually changed, not on every run. A handler is a task that runs only when notified. A task notifies a handler with notify, and the notification counts only if the task reported changed. Handlers run once, at the end of the play (after all tasks), even if several tasks notified them, and they run in the order they are listed in the handlers section.

Conditionals and loops

- name: Install nginx on Debian-family hosts
  ansible.builtin.apt:
    name: nginx
    state: present
  when: ansible_facts['os_family'] == "Debian"

- name: Create staff accounts
  ansible.builtin.user:
    name: "{{ item }}"
    groups: www-data
    append: true
  loop:
    - asha
    - ravi
    - meena

Check mode and diff

ansible-playbook -i inventory.ini site.yml --check --diff   # dry run: what would change, and how
ansible-playbook -i inventory.ini site.yml --limit web1.college.edu   # run on one host only
ansible-playbook -i inventory.ini site.yml --syntax-check

Common mistakes

• Restarting a service in a normal task on every run. Use a handler with notify so it happens only after a change.
• Writing when: "{{ x }} == 1". when is already an expression: write when: x == 1.
• Forgetting become: true when tasks need root.
• Wrong indentation under a module: its arguments must be indented one level below the module name.
• Unquoted file modes such as mode: 0644. Quote them as "0644" so they are not read as a different number.