Ansible Playbooks

Ansible Playbooks

Ansible playbooks are YAML files that define the desired state of your infrastructure. Unlike ad-hoc commands, playbooks are idempotent: running the same playbook ten times produces the same result as running it once. Ansible checks the current state before making changes — if nginx is already installed, the "install nginx" task reports "ok" instead of reinstalling it. This makes playbooks safe to run repeatedly, making them ideal for both initial configuration and ongoing drift correction.

Playbook structure

nano webserver-setup.yml

webserver-setup.yml — full playbook example

---
- name: Configure web servers
  hosts: webservers          # Targets from inventory
  become: true               # Run all tasks with sudo
  vars:
    nginx_port: 80
    site_name: "example.com"
    document_root: "/var/www/{{ site_name }}"

  tasks:
    - name: Install nginx
      apt:
        name: nginx
        state: present
        update_cache: yes

    - name: Create document root
      file:
        path: "{{ document_root }}"
        state: directory
        owner: www-data
        group: www-data
        mode: '0755'

    - name: Deploy nginx site config
      template:
        src: templates/nginx-site.conf.j2
        dest: "/etc/nginx/sites-available/{{ site_name }}"
      notify: Reload nginx    # Trigger handler if this task changes anything

    - name: Enable site
      file:
        src: "/etc/nginx/sites-available/{{ site_name }}"
        dest: "/etc/nginx/sites-enabled/{{ site_name }}"
        state: link

  handlers:
    - name: Reload nginx
      service:
        name: nginx
        state: reloaded

# Run the playbook:
ansible-playbook webserver-setup.yml

# Dry run (check mode — shows what would change without making changes):
ansible-playbook webserver-setup.yml --check

# Run with verbose output:
ansible-playbook webserver-setup.yml -v    # or -vv for more detail

# Limit to specific hosts:
ansible-playbook webserver-setup.yml --limit web-01

Tasks and handlers

Playbook run output

PLAY [Configure web servers] *********************************************
TASK [Install nginx] *****************************************************
ok: [web-01]    ← Already installed, no change
changed: [web-02]   ← Was not installed, installed now

TASK [Deploy nginx site config] ******************************************
changed: [web-01]   ← Config file changed
ok: [web-02]        ← Already up to date

RUNNING HANDLER [Reload nginx] *******************************************
changed: [web-01]   ← Reloaded because config changed (NOT run on web-02)

PLAY RECAP ***************************************************************
web-01: ok=4 changed=2 unreachable=0 failed=0
web-02: ok=4 changed=1 unreachable=0 failed=0

Variables and templates

nano templates/nginx-site.conf.j2

templates/nginx-site.conf.j2 — Jinja2 template

server {
    listen {{ nginx_port }};
    server_name {{ site_name }};
    root {{ document_root }};
    index index.html index.php;

    access_log /var/log/nginx/{{ site_name }}.access.log;
    error_log  /var/log/nginx/{{ site_name }}.error.log;
}

# Override variables for specific hosts or groups (host_vars/group_vars):
mkdir -p group_vars host_vars

# group_vars/webservers.yml:
echo "nginx_port: 8080" > group_vars/webservers.yml

# host_vars/web-01.yml (overrides group vars for this host):
echo "nginx_port: 80" > host_vars/web-01.yml

Ansible roles

# Roles organize playbooks into reusable, shareable units:
ansible-galaxy init nginx-role    # Create role skeleton

# Role directory structure:
# nginx-role/
#   tasks/main.yml     → task list
#   handlers/main.yml  → handler definitions
#   templates/         → Jinja2 templates
#   files/             → static files to copy
#   vars/main.yml      → role variables
#   defaults/main.yml  → default variable values

# Use a role in a playbook:
# - name: Configure servers
#   hosts: webservers
#   roles:
#     - nginx-role
#     - certbot-role

Conclusion

The power of Ansible is idempotency: you can run playbooks in CI/CD pipelines, run them as cron jobs to prevent configuration drift, and run them on new servers to bring them to the desired state. Handlers are essential for service restarts — they only fire when a task actually makes a change, preventing unnecessary restarts of services that are already in the correct state. Use --check mode before any playbook run in production to preview changes without applying them.