Intermediate

# ansible-galaxy init webserver
# Creates standard role structure

---
# Default variables (lowest precedence)
# => defaults/main.yml provides baseline values
# => Can be overridden by inventory, playbook, or extra-vars

http_port: 80 # => HTTP listening port
# => Default: 80 (standard HTTP)
# => Overridable for non-standard configurations

https_port: 443 # => HTTPS listening port
# => Default: 443 (standard HTTPS)

document_root: /var/www/html # => Web content directory
# => Path where HTML/static files served from
# => Must exist before nginx starts

server_name: localhost # => Virtual host server name
# => Matches HTTP Host header
# => Default: localhost (generic)

---
# Role variables (higher precedence than defaults)
# => vars/main.yml contains role internals
# => Should NOT be overridden (use defaults for that)

nginx_package: nginx # => Package name for installation
# => Fixed: nginx (role-specific constant)
# => Used by ansible.builtin.package module

nginx_service: nginx # => systemd service name
# => Fixed: nginx
# => Used for service state management

config_file: /etc/nginx/sites-available/default # => Config file path
# => Debian/Ubuntu path convention
# => Template deployment destination

---
# Main task file for webserver role
# => tasks/main.yml is the role entry point
# => Executes sequentially when role applied
# => Auto-loaded when role referenced in playbook

- name: Install web server # => Step 1: Package installation
 # => Task name visible in playbook execution output
 ansible.builtin.package: # => OS-agnostic package module
 # => Abstracts apt/yum/dnf/pacman differences
 name: "{{ nginx_package }}" # => Uses var from vars/main.yml
 # => Resolves to "nginx"
 # => Variable interpolation with Jinja2 {{ }}
 state: present # => Ensure package installed
 # => Idempotent: safe to run multiple times
 # => changed: [host] if package newly installed
 # => ok: [host] if package already present

- name: Create document root # => Step 2: Directory setup
 # => Ensures web content directory exists
 ansible.builtin.file: # => File/directory management module
 # => Handles files, directories, symlinks
 path: "{{ document_root }}" # => Uses var from defaults/main.yml
 # => Resolves to "/var/www/html"
 # => Overridable via play or inventory vars
 state: directory # => Ensure path is a directory
 # => Creates if missing, verifies if exists
 mode: "0755" # => rwxr-xr-x permissions
 # => Owner read/write/execute, others read/execute
 # => Octal notation requires quotes in YAML
 # => changed: [host] if directory created
 # => ok: [host] if directory exists with correct mode

- name: Deploy configuration # => Step 3: Config file from template
 # => Renders Jinja2 template with role variables
 ansible.builtin.template: # => Jinja2 template rendering
 # => Processes {{ variables }}, {% logic %}
 src: nginx.conf.j2 # => Template from templates/ directory
 # => Relative path: roles/webserver/templates/nginx.conf.j2
 # => Ansible searches role's templates/ folder
 dest: "{{ config_file }}" # => Destination path
 # => Resolves to "/etc/nginx/sites-available/default"
 # => Target location for rendered config
 mode: "0644" # => rw-r--r-- permissions
 # => Owner read/write, others read-only
 notify: restart nginx # => Trigger handler if config changes
 # => Handler queued for execution at play end
 # => Only executes if this task reports "changed"
 # => changed: [host] if template content differs from destination
 # => ok: [host] if template content matches destination

- name: Ensure service is running # => Step 4: Service state management
 # => Guarantees nginx active and boot-enabled
 ansible.builtin.service: # => systemd/init service module
 # => Abstracts systemd/SysV/upstart/OpenRC
 name: "{{ nginx_service }}" # => Service name
 # => Resolves to "nginx"
 # => systemd unit name
 state: started # => Ensure service running
 # => Starts if stopped, no-op if already running
 enabled: true # => Enable on boot (systemctl enable)
 # => Creates systemd symlink for auto-start
 # => changed: [host] if service stopped or disabled
 # => ok: [host] if service already running and enabled

---
# Handlers for service management
# => handlers/main.yml contains event-driven tasks
# => Execute at play end only if notified

- name: restart nginx # => Handler name (must match notify value)
 ansible.builtin.service: # => Service control module
 name: "{{ nginx_service }}" # => Service to restart
 # => Resolves to "nginx"
 state: restarted # => Stop then start service
 # => Executes only if notified by task changes
 # => Runs once per play even if notified multiple times
 # => Output: changed: [host] (nginx.service restarted)

# Nginx virtual host configuration template
# => Jinja2 template with variable substitution
# => Rendered by ansible.builtin.template module

server { # => Virtual host block
 listen {{ http_port }}; # => Listen port from defaults/main.yml
 # => Renders to: listen 80;
 # => Binds to all interfaces on port 80

 server_name {{ server_name }}; # => Host header matching
 # => Renders to: server_name localhost;
 # => Matches requests with Host: localhost

 root {{ document_root }}; # => Document root from defaults
 # => Renders to: root /var/www/html;
 # => Base path for static file serving

 index index.html; # => Default index file
 # => Serve index.html when directory requested
}

---
# webserver_playbook.yml
# => Playbook that applies webserver role to target hosts

- name: Deploy Web Server # => Play name
 hosts: webservers # => Target host group from inventory
 # => Executes on all hosts in webservers group
 become: true # => Escalate privileges (sudo/root)
 # => Required for package installation and service management

 roles: # => Roles to apply to hosts
 - webserver # => Apply webserver role
 # => Automatically includes:
 # => - roles/webserver/tasks/main.yml (tasks)
 # => - roles/webserver/handlers/main.yml (handlers)
 # => - roles/webserver/defaults/main.yml (default vars)
 # => - roles/webserver/vars/main.yml (role vars)
 # => - roles/webserver/templates/* (templates)
 # => Execution order:
 # => 1. Load variables (defaults, vars)
 # => 2. Execute tasks sequentially
 # => 3. Run notified handlers at play end

---
# Defaults (precedence: 2 - lowest for roles)
# => defaults/main.yml provides baseline configuration
# => Designed to be overridden by higher precedence sources

app_port: 8080 # => Default application port
# => Precedence: 2 (easily overridden)
# => Can be changed by inventory, play vars, role params, extra-vars

app_env: development # => Default environment
# => Precedence: 2
# => Common override: staging, production via inventory

debug_enabled: false # => Default debug mode
# => Precedence: 2
# => Disabled by default for performance

---
# Role vars (precedence: 18)
# => vars/main.yml contains role constants
# => High precedence - should NOT be overridden

app_name: MyApplication # => Fixed role variable
# => Precedence: 18 (only extra-vars can override)
# => Role-specific constant, not configurable

config_dir: /etc/myapp # => Application config directory
# => Precedence: 18
# => Fixed path for role's configuration files

---
# role_precedence.yml
# => Demonstrates variable precedence hierarchy

- name: Role Variable Precedence # => Play name
 hosts: localhost # => Execute on localhost
 gather_facts: false # => Skip fact gathering for speed

 # Play vars (precedence: 15)
 # => Variables defined at play level
 vars:
 app_port: 9090 # => Override default 8080
 # => Precedence: 15 (higher than defaults: 2)
 # => Overrides roles/app/defaults/main.yml
 # => Does NOT override roles/app/vars/main.yml (precedence 18)
 app_env: staging # => Override default development
 # => Precedence: 15

 roles:
 - role: app # => Apply app role
 # Role parameters (precedence: 17)
 # => Variables passed directly to role
 vars:
 debug_enabled: true # => Override default false
 # => Precedence: 17 (higher than play vars: 15)
 # => Overrides roles/app/defaults/main.yml
 # => Does NOT override roles/app/vars/main.yml (precedence 18)

 # => Variable resolution order for this play:
 # => 1. app_name: MyApplication (vars/main.yml - precedence 18)
 # => 2. config_dir: /etc/myapp (vars/main.yml - precedence 18)
 # => 3. debug_enabled: true (role params - precedence 17)
 # => 4. app_port: 9090 (play vars - precedence 15)
 # => 5. app_env: staging (play vars - precedence 15)

 tasks:
 - name: Display final configuration # => Show merged values
 ansible.builtin.debug: # => Print message module
 msg: | # => Multi-line message
 App: {{ app_name }}
 Port: {{ app_port }}
 Environment: {{ app_env }}
 Debug: {{ debug_enabled }}
 Config Dir: {{ config_dir }}
 # => Output:
 # => App: MyApplication (from vars - precedence 18)
 # => Port: 9090 (from play vars - precedence 15)
 # => Environment: staging (from play vars - precedence 15)
 # => Debug: true (from role params - precedence 17)
 # => Config Dir: /etc/myapp (from vars - precedence 18)

# Run playbook with extra-vars
ansible-playbook role_precedence.yml -e "app_port=3000"
# => -e flag passes extra-vars (precedence: 22 - highest)
# => Overrides all other variable sources including vars/main.yml

# Multiple extra-vars
ansible-playbook role_precedence.yml -e "app_port=3000 app_env=production"
# => Override multiple variables simultaneously
# => Useful for CI/CD parameter injection

---
# Database role dependencies
# => meta/main.yml defines role dependencies
# => Dependencies execute BEFORE current role

dependencies: # => List of required roles
 # => Dependencies execute before current role's tasks
 # => Ensures prerequisites satisfied before main role
 - role: common # => First dependency
 # => Always executes before firewall and database
 # => Execution order: 1st
 # => Provides baseline system configuration
 vars: # => Pass variables to dependency
 # => Override dependency's default values
 ntp_server: time.example.com # => Override default NTP server
 # => Custom NTP server for time synchronization
 # => dependency-specific variable override
 # => Scoped to common role only

 - role: firewall # => Second dependency
 # => Executes after common, before database
 # => Execution order: 2nd
 # => Configures network access rules
 vars: # => Configure firewall for database
 # => Database-specific firewall configuration
 allowed_ports: # => Ports to open
 # => YAML list of ports to allow through firewall
 - 5432 # => PostgreSQL default port
 # => TCP port for database connections
 # => Firewall configured before database installation
 # => Ensures connectivity ready when service starts
 # => Prevents connection failures after database starts

---
# Common role tasks
# => Provides baseline system configuration
# => Executed as dependency by other roles
# => Shared foundation for all dependent roles

- name: Update package cache # => Refresh package metadata
 # => Ensures latest package versions available
 ansible.builtin.apt: # => Debian/Ubuntu package manager
 # => APT module provides cache management
 # => Debian-specific (yum/dnf for RHEL)
 update_cache: true # => Run apt-get update
 # => Refreshes package index from repositories
 # => Downloads latest package metadata
 cache_valid_time: 3600 # => Skip if updated within 1 hour
 # => Prevents redundant updates (performance optimization)
 # => 3600 seconds = 1 hour cache validity
 when: ansible_os_family == "Debian" # => Only on Debian-based systems
 # => Conditional ensures APT only runs on Debian/Ubuntu
 # => ansible_os_family fact populated by setup module
 # => changed: [host] if cache refreshed
 # => ok: [host] if cache fresh (within 3600 seconds)

- name: Install common packages # => Base utility installation
 # => Installs baseline tools for all systems
 ansible.builtin.package: # => OS-agnostic package module
 # => Cross-platform package installation
 # => Automatically selects apt/yum/dnf/pacman
 name: # => Package list (YAML array)
 # => Multiple packages installed in single transaction
 # => Efficient bulk installation
 - curl # => HTTP client utility
 # => Required for downloading files
 # => Used by many deployment scripts
 - vim # => Text editor
 # => Standard editor for configuration files
 # => Essential for server administration
 - git # => Version control system
 # => Essential for deployment workflows
 # => Clone repositories, manage configs
 state: present # => Ensure all packages installed
 # => Idempotent: installs only if missing
 # => changed: [host] if any package newly installed
 # => ok: [host] if all packages already present

---
# Firewall role tasks
# => Configures UFW (Uncomplicated Firewall)
# => Executed as dependency before application roles
# => Security layer for network access

- name: Install UFW # => Install firewall package
 ansible.builtin.package: # => Package module
 name: ufw # => Uncomplicated Firewall
 # => Frontend for iptables
 state: present # => Ensure installed
 when: ansible_os_family == "Debian" # => Debian/Ubuntu only
 # => UFW is Debian-specific tool
 # => changed: [host] if UFW newly installed
 # => ok: [host] if UFW already present

- name: Allow SSH # => Critical: Prevent lockout
 # => First rule to configure (safety measure)
 community.general.ufw: # => UFW management module
 # => From community.general collection
 rule: allow # => Allow connection
 # => Permits inbound traffic on specified port
 port: "22" # => SSH port
 # => String format required by UFW module
 # => Standard SSH port (default)
 proto: tcp # => TCP protocol
 # => SSH uses TCP (not UDP)
 # => MUST execute before enabling firewall
 # => Prevents SSH lockout on remote systems
 # => changed: [host] if rule added
 # => ok: [host] if rule exists

- name: Allow application ports # => Open ports from dependency vars
 community.general.ufw: # => UFW module
 rule: allow # => Allow incoming connections
 port: "{{ item }}" # => Port from loop iteration
 # => First iteration: 5432 (PostgreSQL)
 # => Variable substitution
 proto: tcp # => TCP protocol
 loop: "{{ allowed_ports }}" # => Variable from database role
 # => allowed_ports from database/meta/main.yml
 # => Iterates: [5432]
 # => changed: [host] if rule added
 # => ok: [host] if rule exists

- name: Enable UFW # => Activate firewall
 community.general.ufw: # => UFW module
 state: enabled # => Enable and start firewall
 # => Activates configured rules
 # => Activates all configured rules
 # => changed: [host] if UFW disabled
 # => ok: [host] if UFW already enabled

---
# Database role tasks (executes AFTER dependencies)
# => Runs 3rd: After common (1st) and firewall (2nd)
# => Dependencies guarantee system ready

- name: Install PostgreSQL # => Database package installation
 ansible.builtin.package: # => Package module
 name: postgresql # => PostgreSQL database
 # => Relational database system
 state: present # => Ensure installed
 # => Executes after common role installed base packages
 # => Executes after firewall role opened port 5432
 # => changed: [host] if PostgreSQL newly installed
 # => ok: [host] if PostgreSQL already present

- name: Ensure PostgreSQL is running # => Service management
 ansible.builtin.service: # => Service module
 name: postgresql # => PostgreSQL service name
 state: started # => Ensure service running
 # => Starts if stopped
 enabled: true # => Enable on boot
 # => Creates systemctl symlink
 # => Service starts with port 5432 open (firewall dependency)
 # => changed: [host] if service stopped or disabled
 # => ok: [host] if service already running and enabled

---
# database_playbook.yml
# => Deploy database with automatic dependency resolution

- name: Deploy Database Server # => Play name
 hosts: dbservers # => Target database servers from inventory
 become: true # => Escalate privileges (required for package/service)

 roles:
 - database # => Apply database role
 # => Automatic dependency resolution from database/meta/main.yml
 # => Execution order (automatic):
 # => 1. common role (dependency #1)
 # => 2. firewall role (dependency #2)
 # => 3. database role (primary role)
 # => No need to explicitly list common and firewall roles
 # => Dependencies resolved and executed automatically
 # => Dependencies execute first automatically

# Install specific role from Ansible Galaxy
ansible-galaxy install geerlingguy.nginx
# => Downloads latest version from galaxy.ansible.com
# => Installs to ~/.ansible/roles/geerlingguy.nginx

# Install with version constraint
ansible-galaxy install geerlingguy.nginx,2.8.0
# => Installs specific version 2.8.0 using comma-separated format
# => Ensures reproducible deployments

# Install multiple roles from requirements file
ansible-galaxy install -r requirements.yml
# => Batch install all roles with version pins from YAML file
# => Idempotent: Skips already-installed versions

---
# Galaxy roles
# => Roles from galaxy.ansible.com
# => Public role repository maintained by community

- name: geerlingguy.nginx # => Galaxy role (namespace.name format)
 # => Author: geerlingguy, Role: nginx
 version: 2.8.0 # => Pin to version 2.8.0
 # => Optional: Omit for latest version
 # => Best practice: Always pin versions for reproducibility
 # => Prevents unexpected updates breaking playbooks

- name: geerlingguy.postgresql # => PostgreSQL database role
 # => Popular role for PostgreSQL installation
 version: 3.4.1 # => Pin to version 3.4.1
 # => Prevents breaking changes from auto-updates
 # => Specific version ensures consistency across teams

# Git repository roles
# => Roles from custom Git repositories
# => Use for internal/private roles not on Galaxy
- src: https://github.com/example/ansible-role-custom.git # => Git URL
 # => HTTPS URL for Git repository
 name: custom_role # => Local role name (how to reference in playbook)
 # => Name required for Git sources (no namespace inference)
 # => Used in playbook: roles: [custom_role]
 version: main # => Git branch or tag
 # => Default: main/master branch
 # => Can use tags: v1.0.0 or commit SHA
 # => Commit SHA provides immutable reference

# Local roles path override
# => Roles from local filesystem (development/testing)
- src: ./local-roles/internal-role # => Relative or absolute path
 name: internal_role # => Local role name
 # => Useful for internal/proprietary roles
 # => No version control (uses current filesystem state)

---
# galaxy_roles.yml
# => Playbook demonstrating Galaxy role integration
- name: Use Galaxy Roles # => Play name
 # => Describes playbook purpose
 hosts: webservers # => Target host group
 # => Executes on all hosts in webservers inventory group
 become: true # => Escalate privileges
 # => Required for package installation and service management
 # => Uses sudo/su based on target system

 roles: # => Roles to apply
 # => Executes role tasks in order
 - role: geerlingguy.nginx # => Galaxy role reference
 # => Format: namespace.rolename
 # => geerlingguy = Galaxy namespace (author)
 # => nginx = role name (web server)
 # => Must be installed via ansible-galaxy first
 vars: # => Pass configuration to role
 # => Override role default variables
 # => Role-specific configuration
 nginx_vhosts: # => Virtual hosts configuration
 # => Variable name expected by geerlingguy.nginx role
 # => Check role documentation for required/optional vars
 # => List of virtual host definitions
 - listen: "80" # => HTTP port
 # => Virtual host listens on port 80
 # => Standard HTTP port (unencrypted)
 server_name: "example.com" # => Domain name
 # => Matches HTTP Host header
 # => Used for name-based virtual hosting
 root: "/var/www/html" # => Document root
 # => Path to serve static files from
 # => Base directory for web content
 # => Role executes its tasks with these variables
 # => Configures nginx with virtual host
 # => Installs package, writes config, starts service

 tasks: # => Additional tasks after role execution
 # => Runs after all roles complete
 - name: Verify nginx is running # => Post-role validation
 # => Confirms role successfully configured service
 ansible.builtin.service: # => Service module
 # => Query/manage system services
 name: nginx # => Service name
 # => systemd unit name
 state: started # => Ensure running
 # => Verify service is active
 # => Validates role successfully started service
 # => ok: [host] if nginx running (expected)
 # => changed: [host] if nginx stopped (unexpected)
 # => Failure indicates role configuration error

# List all installed roles
ansible-galaxy list
# => Shows all roles in ~/.ansible/roles/
# => Output: namespace.rolename, version
# => Example: geerlingguy.nginx, 2.8.0

# Show role information
ansible-galaxy info geerlingguy.nginx
# => Displays role metadata: description, platforms, versions, dependencies
# => Useful before installing to check compatibility

# Remove installed role
ansible-galaxy remove geerlingguy.nginx
# => Deletes role from ~/.ansible/roles/
# => Use when upgrading or cleaning up unused roles

# Create role skeleton with standard structure
ansible-galaxy init --init-path roles/ myapp
# => Creates standardized role structure in roles/myapp/
# => Includes: tasks, handlers, templates, files, vars, defaults, meta, tests

---
# Role metadata for Ansible Galaxy
# => meta/main.yml describes role for Galaxy publication

galaxy_info: # => Galaxy-specific metadata
 author: Your Name # => Role author/maintainer
 # => Displayed on Galaxy role page

 description: Deploys and configures MyApp # => Short description
 # => Appears in Galaxy search results
 # => Keep concise (1-2 sentences)

 license: MIT # => Role license
 # => Common: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause

 min_ansible_version: 2.14 # => Minimum Ansible version
 # => Prevents role execution on incompatible versions
 # => Galaxy validates this during import

 platforms: # => Supported OS platforms
 # => Tested and supported distributions
 - name: Ubuntu # => Distribution name
 versions: # => Supported versions
 - focal # => Ubuntu 20.04 LTS
 - jammy # => Ubuntu 22.04 LTS
 - name: Debian # => Distribution name
 versions: # => Supported versions
 - bullseye # => Debian 11
 - bookworm # => Debian 12

 galaxy_tags: # => Galaxy search/filter tags
 # => Help users discover role (max 20 tags)
 - web # => Tag for web-related roles
 - application # => General application deployment
 - deployment # => Deployment automation

dependencies: [] # => Role dependencies
# => Empty list: no dependencies
# => Non-empty: roles that must execute first
# => Format: [{role: namespace.rolename, version: "1.0.0"}]

# Ansible Role: myapp

Deploys and configures MyApp web application.

## Requirements

- Ansible 2.14+
- Ubuntu 20.04+ or Debian 11+
- Python 3.8+

## Role Variables

Available variables with defaults (defaults/main.yml):

```yaml
myapp_version: "1.0.0" # Application version
myapp_port: 8080 # HTTP port
myapp_user: myapp # System user
myapp_install_dir: /opt/myapp # Installation directory
```

- hosts: appservers
 roles:
 - role: myapp
 vars:
 myapp_version: "2.0.0"
 myapp_port: 9090

---
# Main tasks
- name: Include OS-specific variables
 ansible.builtin.include_vars: "{{ ansible_os_family }}.yml"
 # => Loads vars/Debian.yml or vars/RedHat.yml based on OS

- name: Create application user
 ansible.builtin.user:
 name: "{{ myapp_user }}"
 group: "{{ myapp_group }}"
 system: true
 create_home: false
 # => Creates system user for application

- name: Create installation directory
 ansible.builtin.file:
 path: "{{ myapp_install_dir }}"
 state: directory
 owner: "{{ myapp_user }}"
 group: "{{ myapp_group }}"
 mode: "0755"
 # => Creates app installation directory

- name: Deploy application
 ansible.builtin.get_url:
 url: "https://releases.example.com/myapp-{{ myapp_version }}.tar.gz"
 dest: "/tmp/myapp-{{ myapp_version }}.tar.gz"
 # => Downloads application release

- name: Extract application
 ansible.builtin.unarchive:
 src: "/tmp/myapp-{{ myapp_version }}.tar.gz"
 dest: "{{ myapp_install_dir }}"
 remote_src: true
 owner: "{{ myapp_user }}"
 group: "{{ myapp_group }}"
 # => Extracts to installation directory

- name: Deploy configuration
 ansible.builtin.template:
 src: config.yml.j2
 dest: "{{ myapp_config_file }}"
 owner: "{{ myapp_user }}"
 group: "{{ myapp_group }}"
 mode: "0640"
 notify: restart myapp
 # => Renders configuration template

---
# tests/test.yml
- hosts: localhost
 become: true
 roles:
 - myapp

---
# dynamic_roles.yml
# => Demonstrates dynamic vs static role inclusion

- name: Dynamic Role Inclusion # => Play name
 hosts: localhost # => Execute on localhost
 gather_facts: true # => Gather facts (needed for group_names)

 vars: # => Variables for dynamic role selection
 server_type: webserver # => Dynamic role selector
 # => Value determines which role to include
 # => Could be: webserver, appserver, database
 enable_monitoring: true # => Conditional flag
 # => Controls whether monitoring role included

 tasks:
 # Static import (parse-time)
 # => import_role processes at playbook parse time

 - name: Import role statically # => Static role import
 ansible.builtin.import_role: # => Parse-time inclusion
 name: common # => Role name (fixed, not variable)
 # => Always imported during playbook parsing
 # => Tasks added to play even if skipped by conditionals
 # => Supports --tags and --skip-tags
 # => Best for: Roles that should always be parsed

 # Dynamic include (runtime)
 # => include_role processes during playbook execution
 - name: Include role dynamically # => Runtime role inclusion
 ansible.builtin.include_role: # => Runtime inclusion
 name: "{{ server_type }}" # => Role name from variable
 # => Resolves to "webserver" at runtime
 # => Variable interpolation possible
 # => Role loaded only when task executes
 # => Allows conditional role selection
 # => Does NOT support --tags on role tasks

 # Conditional role inclusion
 # => Include role only if condition met
 - name: Include monitoring role if enabled # => Conditional inclusion
 ansible.builtin.include_role: # => Runtime inclusion
 name: monitoring # => Monitoring role
 when: enable_monitoring # => Condition: only if true
 # => Evaluates: enable_monitoring is true
 # => Role included: monitoring tasks execute
 # => If false: entire role skipped
 # => Efficient: Role not loaded if skipped

 # Include specific tasks from role
 # => Load subset of role tasks
 - name: Include specific role tasks # => Partial role inclusion
 ansible.builtin.include_role: # => Runtime inclusion
 name: webserver # => Role name
 tasks_from: install # => Specific task file
 # => tasks_from: Load tasks/install.yml instead of tasks/main.yml
 # => Executes: roles/webserver/tasks/install.yml only
 # => Useful for: Large roles with logical task separation
 # => Example: Install vs configure vs upgrade tasks

 # Apply role to subset of hosts
 # => Host-specific role application
 - name: Include role for specific hosts # => Host-filtered inclusion
 ansible.builtin.include_role: # => Runtime inclusion
 name: database # => Database role
 when: "'dbservers' in group_names" # => Condition: host in group
 # => group_names: List of groups this host belongs to
 # => Evaluates true only on hosts in dbservers group
 # => Role applies selectively based on host membership
 # => Efficient: No role processing on non-db hosts

 # Include role with custom variables
 # => Override role defaults per inclusion
 - name: Include role with vars # => Parameterized role inclusion
 ansible.builtin.include_role: # => Runtime inclusion
 name: application # => Application role
 vars: # => Variables scoped to this inclusion
 app_version: "2.0.0" # => Override default version
 # => Overrides defaults/main.yml value
 app_port: 9090 # => Override default port
 # => Variables scoped to this role execution only
 # => Different inclusions can have different values
 # => Useful for: Multi-instance deployments

 # Loop over roles
 # => Apply multiple roles iteratively
 - name: Include multiple roles dynamically # => Loop-based inclusion
 ansible.builtin.include_role: # => Runtime inclusion
 name: "{{ item }}" # => Role name from loop iteration
 # => First iteration: logging
 # => Second iteration: metrics
 # => Third iteration: tracing
 loop: # => List of role names
 - logging # => Observability role 1
 - metrics # => Observability role 2
 - tracing # => Observability role 3
 # => Executes each role sequentially
 # => Equivalent to three separate include_role tasks
 # => Useful for: Applying related role suites

---
# handlers_basic.yml
# => Demonstrates handler event-driven execution

- name: Handler Basics # => Play name
 hosts: localhost # => Execute on localhost
 become: true # => Escalate privileges (required for nginx)
 gather_facts: false # => Skip fact gathering for speed

 handlers: # => Handler definitions section
 # Handlers execute at play end, only if notified

 - name: restart nginx # => Handler name (must match notify value)
 # => Event-driven task triggered by notify
 ansible.builtin.service: # => Service management module
 name: nginx # => Service to restart
 state: restarted # => Stop then start service
 # => Executes ONLY if notified by task change
 # => Executes ONLY ONCE per play (deduplicated)
 # => Runs after ALL tasks complete

 tasks: # => Task definitions section
 # Task 1: Notify handler on change

 - name: Update nginx configuration # => Config file update
 ansible.builtin.copy: # => File copy module
 dest: /etc/nginx/nginx.conf # => Destination path
 content: | # => File content (multi-line)
 events {}
 http {
 server {
 listen 8080;
 }
 }
 # => Content: Minimal nginx config
 notify: restart nginx # => Notify handler if content changes
 # => Triggers "restart nginx" handler
 # => changed: [localhost] → handler queued
 # => ok: [localhost] → handler not queued

 # Task 2: Notify same handler (deduplication test)
 - name: Update site configuration # => Site-specific config
 ansible.builtin.copy: # => File copy module
 dest: /etc/nginx/sites-available/default # => Site config file
 content: | # => File content
 server {
 listen 80;
 root /var/www/html;
 }
 # => Content: Virtual host configuration
 notify: restart nginx # => Notify same handler
 # => Even if BOTH tasks change, handler runs ONCE
 # => Prevents redundant restarts (efficiency)

 # Task 3: No notification (baseline task)
 - name: Create web root # => Directory creation
 ansible.builtin.file: # => File module
 path: /var/www/html # => Directory path
 state: directory # => Ensure directory exists
 mode: "0755" # => rwxr-xr-x permissions
 # => No notify: handler not affected by this task
 # => changed: [localhost] if directory created
 # => ok: [localhost] if directory exists

 # Execution Order:
 # => 1. All tasks execute sequentially
 # => 2. Handler notifications queued during task execution
 # => 3. After last task: handlers execute (deduplicated)
 # => 4. "restart nginx" runs once if notified by any task

---
# handler_patterns.yml
# => Demonstrates multiple handler notification patterns

- name: Handler Notification Patterns # => Play name
 hosts: localhost # => Execute on localhost
 become: true # => Escalate privileges (for service management)
 gather_facts: false # => Skip fact gathering

 handlers: # => Handler definitions
 # Handlers execute in THIS order (definition order)
 # NOT in notification order

 - name: restart nginx # => Handler 1 (definition order)
 ansible.builtin.service: # => Service module
 name: nginx # => Service name
 state: restarted # => Full restart (stop + start)
 # => Execution order: 1st (if queued)
 # => Downtime: ~1-2 seconds during restart

 - name: reload nginx # => Handler 2 (definition order)
 ansible.builtin.service: # => Service module
 name: nginx # => Service name
 state: reloaded # => Graceful reload (no downtime)
 # => Execution order: 2nd (if queued)
 # => Reloads config without dropping connections

 - name: restart php-fpm # => Handler 3 (definition order)
 ansible.builtin.service: # => Service module
 name: php-fpm # => PHP FastCGI Process Manager
 state: restarted # => Full restart
 # => Execution order: 3rd (if queued)
 # => Required when PHP config changes

 - name: clear cache # => Handler 4 (definition order)
 ansible.builtin.file: # => File module
 path: /var/cache/app # => Cache directory
 state: absent # => Remove directory
 # => Execution order: 4th (if queued)
 # => Clears application cache

 tasks:
 # Single notification pattern
 # => Task notifies one handler

 - name: Update nginx config # => Config file update
 ansible.builtin.copy: # => File copy module
 dest: /etc/nginx/nginx.conf # => Destination path
 content: "events {}\nhttp {}\n" # => Minimal config
 notify: restart nginx # => Single handler notification
 # => Syntax: notify: handler_name
 # => Queues "restart nginx" if task reports changed
 # => No queue if task reports ok (unchanged)

 # Multiple notifications pattern
 # => Task notifies multiple handlers
 - name: Update PHP config # => PHP configuration change
 ansible.builtin.copy: # => File copy module
 dest: /etc/php/php.ini # => PHP config file
 content: | # => Multi-line content
 [PHP]
 memory_limit = 256M
 notify: # => List of handlers to notify
 - restart php-fpm # => Handler 1 notification
 # => Queues restart php-fpm
 - clear cache # => Handler 2 notification
 # => Queues clear cache
 # => Both handlers queued if task changes
 # => Execution: restart php-fpm (3rd), then clear cache (4th)
 # => Order determined by handler definition, not notify order

 # Notification with list syntax (alternative)
 # => Another example of multi-handler notification
 - name: Update application code # => Application file update
 ansible.builtin.copy: # => File copy module
 dest: /var/www/app/index.php # => PHP application file
 content: "<?php phpinfo(); ?>" # => PHP code
 notify: # => Handler list
 - reload nginx # => Graceful reload (no downtime)
 # => Reload instead of restart (better for production)
 - clear cache # => Clear cache after code update
 # => Queues reload nginx and clear cache
 # => Execution: reload nginx (2nd), then clear cache (4th)

 # Handler execution order (after all tasks complete):
 # => Handlers execute in DEFINITION order, NOT notification order
 # => Order:
 # => 1. restart nginx (if queued by task 1)
 # => 2. reload nginx (if queued by task 3)
 # => 3. restart php-fpm (if queued by task 2)
 # => 4. clear cache (if queued by task 2 or 3)

---
# flush_handlers.yml
# => Demonstrates flush_handlers and listen patterns

- name: Flush Handlers and Listen # => Play name
 hosts: localhost # => Execute on localhost
 become: true # => Escalate privileges
 gather_facts: false # => Skip fact gathering

 handlers: # => Handler definitions with listen topics
 # listen keyword enables topic-based handler grouping
 # Multiple handlers can listen to same topic

 - name: restart nginx service # => Handler 1
 ansible.builtin.service: # => Service module
 name: nginx # => Nginx service
 state: restarted # => Full restart
 listen: restart web services # => Topic this handler listens to
 # => Triggered when notify: restart web services
 # => Multiple handlers can share same topic
 # => Decouples tasks from handler implementation

 - name: restart apache service # => Handler 2
 ansible.builtin.service: # => Service module
 name: apache2 # => Apache service
 state: restarted # => Full restart
 listen: restart web services # => Same topic as handler 1
 # => BOTH nginx and apache restart when topic notified
 # => Topic pattern: One notification triggers multiple handlers
 # => Execution: Both handlers run (definition order)

 - name: reload configuration # => Handler 3
 ansible.builtin.command: # => Command module
 cmd: /usr/local/bin/reload-config.sh # => Custom reload script
 listen: restart web services # => Same topic again
 # => Three handlers listening to one topic
 # => All three execute when "restart web services" notified
 # => Useful for: Cascading service operations

 tasks:
 # Task 1: Notify topic (not specific handler)
 # => Demonstrates topic-based notification

 - name: Update shared configuration # => Config update
 ansible.builtin.copy: # => File copy module
 dest: /etc/shared/config.conf # => Shared config file
 content: "setting=value\n" # => Config content
 notify: restart web services # => Notify TOPIC, not handler name
 # => Queues ALL handlers listening to this topic
 # => Queued: restart nginx, restart apache, reload configuration
 # => Handlers won't execute yet (wait for play end)

 # Task 2: Force immediate handler execution
 # => Demonstrates meta: flush_handlers
 - name: Flush handlers immediately # => Force handler execution
 ansible.builtin.meta: flush_handlers # => Meta module
 # => Executes ALL queued handlers IMMEDIATELY
 # => Execution order (from handlers section):
 # => 1. restart nginx service
 # => 2. restart apache service
 # => 3. reload configuration
 # => Handlers run NOW, not at play end
 # => Clears handler queue

 # Task 3: Run after handlers
 # => Demonstrates dependency on flushed handlers
 - name: Verify services are running # => Post-handler verification
 ansible.builtin.service: # => Service module
 name: nginx # => Check nginx status
 state: started # => Ensure running
 # => Runs AFTER handlers flushed
 # => nginx already restarted by handler 1
 # => Verification task depends on handler completion
 # => Without flush: would run BEFORE handlers

 # Task 4: Notify again after flush
 # => Demonstrates handlers can execute multiple times
 - name: Update another config # => Second config update
 ansible.builtin.copy: # => File copy module
 dest: /etc/shared/other.conf # => Different config file
 content: "other=value\n" # => Different content
 notify: restart web services # => Notify same topic again
 # => Queues handlers AGAIN (after first flush)
 # => Handlers can execute multiple times per play
 # => Second queue: restart nginx, restart apache, reload config

 # Execution timeline:
 # => 1. Task 1: Update config → queue handlers
 # => 2. Task 2: flush_handlers → execute handlers (1st time)
 # => 3. Task 3: Verify services → nginx already restarted
 # => 4. Task 4: Update another config → queue handlers again
 # => 5. Play end → execute handlers (2nd time)

 # Final handlers execute here at play end
 # => restart web services handlers run SECOND time
 # => Only if task 4 changed (notified after flush)

---
# handler_conditionals.yml
# => Demonstrates handler conditionals and error handling

- name: Handler Conditionals and Error Handling # => Play name
 hosts: localhost # => Execute on localhost
 become: true # => Escalate privileges
 gather_facts: true # => Gather facts (needed for OS detection)

 vars: # => Play-level variables
 production_mode: true # => Environment flag
 # => Controls production-specific handlers
 enable_service_restart: true # => Service restart toggle
 # => Allows disabling restarts in maintenance mode

 handlers: # => Handler definitions with conditionals
 # Pattern 1: Simple conditional handler
 # => Handler executes only if condition true

 - name: restart nginx # => Conditional service restart
 ansible.builtin.service: # => Service module
 name: nginx # => Service name
 state: restarted # => Restart action
 when: enable_service_restart # => Condition: variable must be true
 # => Handler runs only if enable_service_restart is true
 # => If false: handler queued but skipped
 # => Useful for: Maintenance windows (disable restarts)

 # Pattern 2: OS-specific conditional handler
 # => Handler adapts to operating system
 - name: restart web server # => OS-adaptive restart
 ansible.builtin.service: # => Service module
 name: "{{ 'apache2' if ansible_os_family == 'Debian' else 'httpd' }}" # => Dynamic service name
 # => Debian/Ubuntu: apache2
 # => RedHat/CentOS: httpd
 state: restarted # => Restart action
 when: ansible_os_family in ['Debian', 'RedHat'] # => OS family filter
 # => Executes only on Debian or RedHat systems
 # => Skipped on: FreeBSD, Windows, etc.
 # => Pattern: Cross-platform playbooks

 # Pattern 3: Error-tolerant handler
 # => Handler that never fails playbook
 - name: reload application # => Graceful application reload
 ansible.builtin.command: # => Command module
 cmd: /usr/local/bin/app reload # => Custom reload command
 register: reload_result # => Capture result for inspection
 # => Stores: rc (return code), stdout, stderr
 failed_when: false # => Never mark as failed
 # => Always reports: ok (even if command returns non-zero)
 # => Prevents handler failure from stopping playbook
 # => Useful for: Optional operations

 # Pattern 4: Chained conditional handler
 # => Handler depends on previous handler result
 - name: report reload failure # => Conditional failure reporting
 ansible.builtin.debug: # => Debug message module
 msg: "WARNING: Application reload failed" # => Warning message
 when: reload_result is defined and reload_result.rc != 0 # => Multi-condition
 # => Condition 1: reload_result exists (previous handler ran)
 # => Condition 2: Return code != 0 (command failed)
 # => Executes only if previous handler registered failure
 # => Pattern: Error reporting without failing playbook

 # Pattern 5: Environment-specific handler
 # => Handler runs only in specific environments
 - name: send notification # => Production notification
 ansible.builtin.uri: # => HTTP request module
 url: https://hooks.slack.com/services/YOUR/WEBHOOK/URL # => Slack webhook
 method: POST # => HTTP POST
 body_format: json # => JSON payload
 body: # => Request body
 text: "Configuration updated on {{ inventory_hostname }}" # => Message
 # => inventory_hostname: Current host name
 when: production_mode # => Condition: production only
 # => Executes only if production_mode is true
 # => Skipped in: development, staging environments
 # => Prevents notification spam in non-prod

 tasks:
 # Task 1: Notify all handlers
 # => Demonstrates multiple handler notifications

 - name: Update configuration # => Config file update
 ansible.builtin.copy: # => File copy module
 dest: /etc/app/config.yml # => Application config
 content: | # => YAML content
 port: 8080
 debug: false
 notify: # => Notify multiple handlers
 - restart nginx # => Handler 1: Conditional restart
 - reload application # => Handler 2: Error-tolerant reload
 - report reload failure # => Handler 3: Chained conditional
 - send notification # => Handler 4: Production-only
 # => All handlers queued if task changes
 # => Handler conditions evaluated at execution time
 # => Execution order: Definition order (handlers section)

 # Task 2: Demonstrate conditional skip
 # => Task-level variable overrides play variable
 - name: Update non-critical config # => Non-critical update
 ansible.builtin.copy: # => File copy module
 dest: /tmp/test.conf # => Temporary file
 content: "test=value\n" # => Test content
 notify: restart nginx # => Notify restart handler
 vars: # => Task-level variables
 enable_service_restart: false # => Override play variable
 # => Task-level: false (overrides play-level: true)
 # => Handler queued but skipped when executed
 # => when: enable_service_restart evaluates to false
 # => Pattern: Selective handler disabling per task

---
# template_basics.yml
# => Demonstrates basic Jinja2 template usage

- name: Jinja2 Template Basics # => Play name
 hosts: localhost # => Execute on localhost
 gather_facts: true # => Required for ansible_date_time variable

 vars: # => Variables for template substitution
 app_name: MyApplication # => Application name
 # => Used in template: {{ app_name }}
 app_version: "2.1.0" # => Version string
 # => Quoted to preserve as string (not float)
 app_environment: production # => Environment identifier
 server_host: 0.0.0.0 # => Listen on all interfaces
 server_port: 8080 # => HTTP port
 worker_count: 4 # => Worker processes
 db_host: db.example.com # => Database hostname
 db_port: 5432 # => PostgreSQL default port
 db_name: appdb # => Database name
 db_user: appuser # => Database username
 log_level: info # => Logging level (lowercase)
 # => Template will uppercase: INFO
 # log_file not defined
 # => Template will use default: /var/log/app.log

 tasks:
 - name: Render application configuration # => Template rendering
 ansible.builtin.template: # => Template module
 src: app_config.yml.j2 # => Template source file
 # => Path relative to playbook or templates/ directory
 # => Searches: playbook dir, playbook/templates/
 dest: /tmp/app_config.yml # => Destination on managed host
 # => Fully rendered file copied here
 mode: "0644" # => rw-r--r-- permissions
 # => Owner read/write, group/others read
 # => Process:
 # => 1. Load template from control node
 # => 2. Render with Jinja2 engine (variable substitution)
 # => 3. Copy rendered content to managed host
 # => changed: [localhost] if destination content differs
 # => ok: [localhost] if destination content identical

 - name: Display rendered configuration # => Read rendered file
 ansible.builtin.command: # => Command module
 cmd: cat /tmp/app_config.yml # => Display file contents
 register: config_content # => Store output
 # => config_content.stdout: File contents
 # => config_content.rc: Return code (0 = success)

 - name: Show configuration # => Display captured output
 ansible.builtin.debug: # => Debug module
 msg: "{{ config_content.stdout }}" # => Message from registered var
 # => Shows fully rendered configuration file
 # => Output: Multi-line YAML configuration

# Application Configuration
# Generated by Ansible on 2024-01-15T10:30:00Z

application:
  name: MyApplication
  version: 2.1.0
  environment: production

server:
  host: 0.0.0.0
  port: 8080
  workers: 4

database:
  host: db.example.com
  port: 5432
  name: appdb
  user: appuser

logging:
  level: INFO
  file: /var/log/app.log