Playbook Structure

Overview

Learn how to structure Ansible playbooks effectively for maintainability and reusability.

Basic Structure

---
# site.yml
- name: Web Server Configuration
  hosts: webservers
  become: true
  vars:
    http_port: 80
    max_clients: 200

  pre_tasks:
    - name: Update apt cache
      apt:
        update_cache: yes
        cache_valid_time: 3600

  tasks:
    - name: Install required packages
      package:
        name: "{{ item }}"
        state: present
      loop:
        - nginx
        - php-fpm

  post_tasks:
    - name: Ensure services are running
      service:
        name: "{{ item }}"
        state: started
        enabled: yes
      loop:
        - nginx
        - php-fpm

  handlers:
    - name: Restart nginx
      service:
        name: nginx
        state: restarted

Directory Layout

ansible-project/
├── site.yml                  # Main playbook
├── requirements.yml          # Role dependencies
├── ansible.cfg              # Ansible configuration
├── group_vars/
│   ├── all.yml             # Variables for all groups
│   └── webservers.yml      # Variables for webserver group
├── host_vars/
│   ├── web1.example.com.yml
│   └── web2.example.com.yml
├── inventory/
│   ├── production/
│   │   ├── hosts
│   │   └── group_vars/
│   └── staging/
│       ├── hosts
│       └── group_vars/
└── roles/
    ├── common/
    │   ├── tasks/
    │   ├── handlers/
    │   ├── templates/
    │   ├── files/
    │   ├── vars/
    │   ├── defaults/
    │   └── meta/
    └── webserver/
        └── [role folders]

Advanced Structures

Multi-Environment Setup

# environments/production/group_vars/all.yml
---
environment: production
domain: example.com
backup_retention: 30

# environments/staging/group_vars/all.yml
---
environment: staging
domain: staging.example.com
backup_retention: 7

Play Organization

# site.yml
---
- import_playbook: webservers.yml
- import_playbook: dbservers.yml
- import_playbook: monitoring.yml

# webservers.yml
---
- name: Configure web servers
  hosts: webservers
  roles:
    - common
    - nginx
    - php
    - deployment

Best Practices

Variables Organization

# group_vars/all/main.yml
---
# Basic settings
app_name: myapp
app_version: 1.0.0

# Database settings
db_host: localhost
db_port: 5432

# Feature flags
enable_monitoring: true
enable_backups: true

# Overrides file
# group_vars/all/overrides.yml
---
# Override specific settings per environment

Tags Usage

# Tagging tasks for selective execution
tasks:
  - name: Install packages
    package:
      name: "{{ item }}"
      state: present
    loop: "{{ required_packages }}"
    tags: 
      - packages
      - setup

  - name: Configure application
    template:
      src: app.conf.j2
      dest: /etc/app/config.conf
    tags:
      - configuration
      - app

Include vs Import

# Using includes (dynamic)
tasks:
  - name: Include database tasks
    include_tasks: db_tasks.yml
    when: db_setup_required

# Using imports (static)
tasks:
  - name: Import web tasks
    import_tasks: web_tasks.yml

Modular Design

Task Files

# tasks/main.yml
---
- import_tasks: install.yml
- import_tasks: configure.yml
- import_tasks: security.yml
- import_tasks: monitoring.yml

Conditional Includes

# Conditional role inclusion
roles:
  - role: nginx
    when: deploy_nginx | default(true)
  - role: php
    when: deploy_php | default(true)
  - role: monitoring
    when: enable_monitoring | default(false)

Error Handling

Block Usage

tasks:
  - name: Handle complex deployments
    block:
      - name: Deploy application
        deploy_application:
          path: "{{ app_path }}"
          version: "{{ app_version }}"
    rescue:
      - name: Revert deployment
        deploy_application:
          path: "{{ app_path }}"
          version: "{{ previous_version }}"
    always:
      - name: Cleanup temp files
        file:
          path: "{{ temp_path }}"
          state: absent

Documentation

Playbook Documentation

---
# Title: Web Application Deployment
# Description: Deploys and configures web application stack
# Author: DevOps Team
# Last Updated: 2024-03-15

- name: Deploy Web Application
  hosts: webservers
  vars_files:
    - vars/main.yml
  # Rest of playbook...

Variable Documentation

# vars/main.yml
---
# Application Settings
app_name: myapp                  # Name of the application
app_version: 1.0.0              # Current version to deploy
app_path: /var/www/myapp        # Installation path

# Database Settings
db_host: localhost              # Database host
db_port: 5432                   # Database port
db_name: myapp_db              # Database name