Ansible playbook structure: plays, tasks, handlers, and variables

Ansible beginners write flat playbooks where all tasks for every host are in one long file with hard-coded values. This becomes unmaintainable quickly and makes reuse across different inventories or environments impossible.

Structure playbooks with plays targeting host groups, tasks organized logically, handlers for service restarts, and variables in separate files. Use meaningful names for every task.

# site.yml — main playbook
---
- name: Configure web servers
  hosts: webservers
  become: true
  vars_files:
    - vars/web.yml

  pre_tasks:
    - name: Update apt cache
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600

  roles:
    - common
    - nginx

  tasks:
    - name: Deploy application config
      ansible.builtin.template:
        src: app.conf.j2
        dest: /etc/app/app.conf
        owner: www-data
        mode: '0644'
      notify: Restart nginx

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

Plays define scope (which hosts, which privilege level). Handlers run once at the end of a play regardless of how many tasks notified them, preventing redundant restarts. Variables files keep secrets and config separate from logic.

Writing Ansible playbooks for server configuration and application deployment