Beginner

---
# hello.yml - Minimal working playbook demonstrating Ansible basics
- name:
 Hello World Playbook # => Human-readable play name (appears in console output)
 # => Required field for documentation and logging
 hosts:
 localhost # => Target host pattern (special name for local machine)
 # => Accepts hostname, group name, or pattern (e.g., web*)
 gather_facts:
 false # => Skip automatic fact collection (setup module)
 # => Improves execution speed when facts not needed
 # => Default is true (runs setup module before tasks)

 tasks: # => List of actions to execute on target hosts
 # => Tasks run sequentially from top to bottom
 - name:
 Print greeting # => Task description (appears in console output)
 # => Best practice: use descriptive names for debugging
 ansible.builtin.debug: # => Debug module prints messages to console
 # => No state changes (idempotent, safe for testing)
 # => FQCN format: namespace.collection.module
 msg:
 "Hello, Ansible!" # => Message to display during playbook execution
 # => Can be string or variable using Jinja2 syntax
 # => Output: ok: [localhost] => { "msg": "Hello, Ansible!" }
 # => Task status is "ok" (not "changed") because debug doesn't modify state

---
# verify.yml - Verification playbook for Ansible installation
- name:
 Verify Ansible Installation # => Play name describing verification purpose
 # => Appears in console output during execution
 hosts:
 localhost # => Execute tasks on local machine only
 # => Uses connection: local (no SSH required)
 gather_facts:
 true # => Enable automatic fact collection (setup module)
 # => Default behavior (explicitly shown for clarity)
 # => Runs ansible.builtin.setup before tasks
 # => Setup module collects 100+ facts about target system
 # => Facts include: OS, network, hardware, Python, filesystem info

 tasks: # => Task list begins after fact gathering completes
 # => All facts available as variables in tasks
 - name: Display Ansible version # => Task 1: Show installed Ansible version information
 # => Helps verify correct Ansible installation
 ansible.builtin.debug: # => Debug module prints variables to console
 # => Non-destructive (no state changes)
 # => FQCN format: ansible.builtin.debug
 msg:
 "Ansible version: {{ ansible_version.full }}" # => Access nested fact variable
 # => ansible_version is dict with 'full', 'major', 'minor' keys
 # => Jinja2 {{ }} syntax interpolates variables
 # => ansible_version.full contains complete version (e.g., "2.15.0")
 # => Output: ok: [localhost] => { "msg": "Ansible version: 2.15.0" }

 - name:
 Display Python version # => Task 2: Show Python interpreter version
 # => Confirms Python compatibility with Ansible
 ansible.builtin.debug: # => Debug module for console output
 msg:
 "Python version: {{ ansible_python_version }}" # => Access Python version fact
 # => Collected during fact gathering
 # => ansible_python_version contains version string (e.g., "3.11.6")
 # => Ansible requires Python 2.7+ or 3.5+ on target hosts
 # => Modern Ansible (2.12+) prefers Python 3.x
 # => Output: Python version: 3.11.6 (interpreter at ansible_python_interpreter path)

 - name:
 Display operating system # => Task 3: Show OS distribution and version
 # => Useful for environment-aware playbooks
 ansible.builtin.debug: # => Debug output module
 msg:
 "OS: {{ ansible_distribution }} {{ ansible_distribution_version }}" # => Combine two separate facts
 # => String concatenation with space
 # => ansible_distribution: OS family (Ubuntu, Debian, RedHat, CentOS, Fedora, etc.)
 # => ansible_distribution_version: Version number (22.04, 20.04, 9, 8, etc.)
 # => Detected from /etc/os-release or equivalent system files
 # => Output: OS: Ubuntu 22.04 (parsed from system identification files)
 # => Enables conditional logic: when: ansible_distribution == "Ubuntu"

---
# multi_task.yml - Sequential task execution demonstration
- name:
 Multi-Task Playbook Example # => Play showing task execution order
 # => Demonstrates sequential processing and dependencies
 hosts:
 localhost # => Execute on local machine only
 # => No remote SSH connection needed
 gather_facts:
 false # => Disable automatic fact collection
 # => Improves execution speed when facts not needed
 # => Default is true (setup module runs before tasks)

 tasks: # => Task list begins (executed top-to-bottom)
 # => Each task completes before next task starts
 # => Playbook stops if any task fails (unless ignore_errors: true)
 - name: Task 1 - Create directory # => First task in execution sequence
 # => Task names appear in console output
 ansible.builtin.file: # => File module for filesystem operations
 # => No content transfer (unlike copy module)
 # => Idempotent: safe to run multiple times
 path:
 /tmp/ansible_demo # => Directory path to create
 # => Absolute path recommended for reliability
 # => Parent directory /tmp must exist
 state:
 directory # => Ensure path is a directory (not file or symlink)
 # => Creates directory if missing
 # => Verifies existing directory attributes
 mode:
 "0755" # => POSIX permissions (octal notation, quotes required)
 # => 0755 = rwxr-xr-x (owner: rwx, group: rx, others: rx)
 # => Sets permissions atomically with creation
 # => changed: [localhost] (directory created or permissions modified)
 # => ok: [localhost] (directory exists with correct permissions already)
 # => Task fails if /tmp doesn't exist (parent must be present)
 # => Idempotent: running again produces same result

 - name:
 Task 2 - Create file in directory # => Second task (depends on task 1 completing)
 # => Uses directory created by previous task
 ansible.builtin.file: # => File module with different state parameter
 # => Same module, different operation
 path:
 /tmp/ansible_demo/test.txt # => Full file path (directory + filename)
 # => Parent directory created by task 1
 # => Must be inside existing directory
 state:
 touch # => Create empty file or update modification time
 # => Like Linux touch command
 # => Updates mtime and atime if file exists
 mode:
 "0644" # => File permissions (rw-r--r--)
 # => Owner: read/write, group: read, others: read
 # => Typical permission for text files
 # => changed: [localhost] (file created or timestamps updated)
 # => ok: [localhost] (if file exists with same attributes)
 # => Creates zero-byte file if missing
 # => Updates modification time if file already exists

 - name:
 Task 3 - Write content to file # => Third task modifies existing file
 # => Writes actual data to file created by task 2
 ansible.builtin.copy: # => Copy module with content parameter
 # => Can write inline content without source file
 # => Also supports file-to-file copying via src
 dest:
 /tmp/ansible_demo/test.txt # => Destination file path (overwrite target)
 # => File must exist or will be created
 content:
 "Hello from Ansible\n" # => String content to write
 # => \n adds newline at end
 # => Overwrites entire file content
 # => Can use 'src: /path/to/file' instead for file copying
 # => content parameter useful for small, inline data
 # => changed: [localhost] (content written to file)
 # => Replaces entire file content with this string
 # => Idempotent: compares content checksum before writing
 # => ok if file already contains exact same content

 - name:
 Task 4 - Display file content # => Fourth task reads file for verification
 # => Demonstrates command module and register
 ansible.builtin.command: # => Command module executes shell commands
 # => No shell interpreter (safer than shell module)
 # => Cannot use pipes, redirects, or variables
 cmd:
 cat /tmp/ansible_demo/test.txt # => Read file content command
 # => Standard Linux cat command
 # => Output goes to stdout
 register:
 file_content # => Save command results to variable
 # => Creates dict with stdout, stderr, rc, cmd keys
 # => Accessible in later tasks via {{ file_content }}
 # => changed: [localhost] (command module ALWAYS reports changed)
 # => Use changed_when: false to override this behavior
 # => Command module doesn't detect idempotency automatically
 # => file_content.stdout contains command output
 # => file_content.rc contains return code (0 = success)

 - name:
 Task 5 - Print file content # => Final task displays captured output
 # => Shows how to use registered variables
 ansible.builtin.debug: # => Debug module prints to console
 # => Non-destructive (no state changes)
 # => Useful for displaying variables and debugging
 msg:
 "File content: {{ file_content.stdout }}" # => Access stdout from registered variable
 # => Jinja2 syntax {{ }} interpolates variable
 # => file_content is dict with multiple keys
 # => file_content structure: {stdout: "..", stderr: "..", rc: 0, cmd: ".."}
 # => Output: File content: Hello from Ansible
 # => Debug tasks NEVER report changed status (always ok)
 # => Useful for verification and troubleshooting playbooks

---
# yaml_syntax.yml - Comprehensive YAML syntax demonstration
- name:
 YAML Syntax Demonstration # => Play showing YAML data structure capabilities
 # => Demonstrates strings, numbers, lists, dicts, multi-line
 hosts:
 localhost # => Execute on local machine only
 # => No remote SSH needed
 gather_facts:
 false # => Disable fact gathering
 # => Not needed for syntax demonstration
 # => Improves execution speed

 # Variables section (YAML dictionary at play level)
 vars: # => Play-level variable definitions
 # => All variables accessible in tasks via Jinja2 {{ var_name }}
 # => Variables persist throughout entire play
 simple_string:
 "Hello" # => String value (quotes optional for simple text)
 # => Without special chars, "Hello" same as Hello
 # => Quotes required for: colons, braces, brackets, etc.
 simple_number:
 42 # => Integer value (no quotes needed)
 # => YAML infers type from format
 # => Can be used in math: {{ simple_number + 8 }}
 simple_bool:
 true # => Boolean value (multiple valid formats)
 # => Accepts: true/false, yes/no, on/off
 # => Case-insensitive in YAML
 # => Rendered as True in Python, true in JSON

 # List syntax (ordered array data structure)
 simple_list: # => List declaration using dash (-) prefix syntax
 # => Lists are ordered sequences (maintain insertion order)
 # => Zero-indexed (first item is index 0)
 - item1 # => First list element (index 0)
 # => Access via {{ simple_list[0] }} returns "item1"
 - item2 # => Second list element (index 1)
 # => Access via {{ simple_list[1] }} returns "item2"
 - item3 # => Third list element (index 2)
 # => Access via {{ simple_list[2] }} returns "item3"
 # => Can iterate with loops: {% for item in simple_list %}
 # => List length: {{ simple_list | length }} returns 3

 # Dictionary syntax (key-value map data structure)
 simple_dict: # => Dictionary declaration using key: value format
 # => Dictionaries are unordered collections (pre-Python 3.7)
 # => Keys must be strings, values can be any type
 key1:
 value1 # => First key-value pair
 # => Access via dot notation: {{ simple_dict.key1 }}
 # => Or bracket notation: {{ simple_dict['key1'] }}
 key2:
 value2 # => Second key-value pair
 # => Keys must be unique (duplicates overwrite)
 # => Both syntaxes access same value
 # => Can check key existence: {% if 'key1' in simple_dict %}
 # => Dictionary keys: {{ simple_dict.keys() }}

 # Multi-line string - Folded scalar (joins with spaces)
 folded_string: > # => Folded block scalar (> symbol indicates folding)
 This is a long string
 that will be folded into
 a single line with spaces.
 # => Folding process: joins lines with single space between
 # => Result: "This is a long string that will be folded into a single line with spaces."
 # => Trailing newline added automatically
 # => Useful for long descriptions, documentation, help text
 # => Preserves single line for word wrapping

 # Multi-line string - Literal scalar (preserves formatting)
 literal_string: | # => Literal block scalar (| symbol preserves newlines)
 Line 1
 Line 2
 Line 3
 # => Each newline preserved exactly as written
 # => Result: "Line 1\nLine 2\nLine 3\n" (explicit \n characters)
 # => Trailing newline added automatically
 # => Useful for: config files, scripts, SQL queries, formatted output
 # => Indentation within block is significant

 tasks: # => Task list begins
 # => Only one task in this demonstration
 - name:
 Display variables # => Task outputs all defined variable values
 # => Shows how Jinja2 interpolates each type
 ansible.builtin.debug: # => Debug module for console output
 # => Non-destructive (no state changes)
 # => Useful for displaying and verifying variables
 msg: | # => Multi-line literal message (uses | scalar)
 String: {{ simple_string }}
 Number: {{ simple_number }}
 Bool: {{ simple_bool }}
 List: {{ simple_list }}
 Dict: {{ simple_dict }}
 Folded: {{ folded_string }}
 Literal: {{ literal_string }}
 # => Each line shows: Label: <value>
 # => Jinja2 {{ }} interpolates variables into string
 # => List shows as JSON array: ['item1', 'item2', 'item3']
 # => Dict shows as JSON object: {'key1': 'value1', 'key2': 'value2'}
 # => Output displays actual values with proper formatting
 # => Debug module converts Python objects to readable strings
 # => Useful for troubleshooting variable content

---
# multi_play.yml - Multiple plays in single playbook file
# Demonstrates sequential play execution and independent play settings

# Play 1: Setup phase (initialization)
- name:
 Play 1 - Setup Phase # => First play in playbook execution sequence
 # => Plays execute sequentially (Play 1 → Play 2 → Play 3)
 hosts:
 localhost # => Execute on local machine only
 # => No remote SSH connection
 gather_facts:
 false # => Disable fact gathering for this play
 # => Improves execution speed when facts not needed
 # => Each play has independent gather_facts setting
 # => Play-level settings: hosts, gather_facts, become, vars, etc.
 # => Settings apply only to this play's tasks

 tasks: # => Task list scoped to Play 1 only
 # => Tasks in other plays don't see these task names
 - name:
 Initialize setup # => Setup initialization task
 # => Task name appears in console output
 ansible.builtin.debug: # => Debug module for informational output
 # => Safe (no state changes, no side effects)
 msg:
 "Starting multi-play playbook" # => Informational message string
 # => Visible in playbook execution output
 # => Output: ok: [localhost] => { "msg": "Starting multi-play playbook" }
 # => Debug tasks execute immediately without external effects
 # => Useful for logging playbook progress

# Play 2: Configuration phase (main operations)
- name:
 Play 2 - Configuration Phase # => Second play begins after Play 1 completes
 # => Play 1 must finish successfully before Play 2 starts
 hosts:
 localhost # => Same target host as Play 1
 # => Each play has independent host targeting
 # => Could target different hosts (e.g., webservers vs databases)
 gather_facts:
 true # => Enable fact gathering for this play
 # => Independent setting (different from Play 1's false)
 # => Setup module runs before tasks execute
 # => Facts collected in this play are available to:
 # => 1. All tasks in Play 2
 # => 2. All tasks in Play 3 (facts persist across plays)
 # => Fact gathering happens once per playbook run per host

 tasks: # => Task list scoped to Play 2
 # => New task namespace (independent from Play 1 tasks)
 - name:
 Display hostname # => Task uses fact collected during gather_facts
 # => Demonstrates fact usage in tasks
 ansible.builtin.debug: # => Debug module for output
 msg:
 "Configuring {{ ansible_hostname }}" # => Jinja2 variable interpolation
 # => ansible_hostname from gathered facts
 # => Facts automatically available as variables
 # => ansible_hostname populated by setup module's fact collection
 # => Output: ok: [localhost] => { "msg": "Configuring localhost" }
 # => hostname value comes from system identification
 # => Facts persist in memory for subsequent plays

# Play 3: Reporting phase (final summary)
- name:
 Play 3 - Reporting Phase # => Third play executes after Play 2 completes
 # => All previous plays must succeed before this runs
 hosts:
 localhost # => Same target host
 # => Consistent targeting across all plays
 gather_facts:
 false # => Skip fact gathering for this play
 # => Performance optimization (facts already collected)
 # => Facts from Play 2 still accessible
 # => Reuses facts collected in Play 2 (facts persist in memory)
 # => Fact persistence eliminates redundant setup module execution
 # => Common pattern: gather facts once, use in multiple plays

 tasks: # => Final task list scoped to Play 3
 # => Last set of operations before playbook exit
 - name:
 Generate report # => Final reporting task
 # => Summarizes playbook completion
 ansible.builtin.debug: # => Debug module for summary output
 msg:
 "Playbook execution complete" # => Completion message
 # => Confirms successful execution
 # => Output: ok: [localhost] => { "msg": "Playbook execution complete" }
 # => Playbook exits with success status after this task
 # => All three plays completed sequentially

---
# variables.yml - Variable precedence demonstration
- name:
 Variable Precedence Example # => Play demonstrating Ansible's precedence hierarchy
 # => Shows how variables override each other
 hosts:
 localhost # => Execute on local machine only
 # => No remote SSH needed
 gather_facts:
 false # => Disable fact gathering
 # => Not needed for variable demonstration
 # => Improves execution speed

 # Play-level variables (precedence level: 15 out of 22)
 vars: # => Variable declarations at play scope
 # => Ansible has 22 precedence levels total
 # => Play vars sit in middle (level 15)
 # => Lower levels: defaults, inventory
 # => Higher levels: task vars, extra vars
 environment:
 "development" # => String variable with default value
 # => Defined in playbook (precedence 15)
 # => Can be overridden by CLI extra-vars (precedence 22)
 # => Useful for environment-specific configuration
 app_name:
 "MyApp" # => Application name variable
 # => String value accessible in all play tasks
 # => Accessed via {{ app_name }} in tasks
 # => Play-level scope (not accessible in other plays)
 app_port:
 8080 # => Port number variable (integer type)
 # => YAML infers type from format (no quotes = number)
 # => Can be used in calculations: {{ app_port + 1 }}
 # => Playbook vars can be overridden by inventory or extra-vars

 tasks: # => Task list begins
 # => All play-level vars accessible in tasks
 - name: Display variables # => Task 1: Show current variable values
 # => Demonstrates variable access via Jinja2
 ansible.builtin.debug: # => Debug module for console output
 # => Non-destructive output operation
 msg: | # => Multi-line literal scalar (preserves newlines)
 Environment: {{ environment }}
 App: {{ app_name }}
 Port: {{ app_port }}
 # => Jinja2 {{ }} syntax interpolates variables into strings
 # => Each line shows: Label: <value>
 # => environment, app_name, app_port from play vars above
 # => Output shows actual values after precedence resolution:
 # => Environment: development
 # => App: MyApp
 # => Port: 8080
 # => Values can change if overridden by CLI -e flag

 # Task-level variable demonstration (precedence level: 21)
 - name:
 Override with task vars # => Task 2: Task-scoped variable example
 # => Demonstrates highest precedence (except extra-vars)
 ansible.builtin.debug: # => Debug output module
 msg:
 "Task-level environment: {{ task_env }}" # => References task-scoped variable
 # => task_env defined below in this task only
 vars: # => Task-scoped variables (precedence: 21)
 # => Highest precedence except extra-vars (22)
 # => Only accessible within THIS task
 task_env:
 "production" # => Task-level variable definition
 # => Precedence 21 beats play vars (15)
 # => Overrides any lower-precedence task_env
 # => Scope limited to this task only
 # => Higher precedence than play vars (15 < 21)
 # => Cannot be accessed from other tasks
 # => Output: Task-level environment: production
 # => task_env variable exists only during this task execution
 # => Attempting {{ task_env }} in other tasks would fail

# inventory.ini - Static inventory in INI format
# Ungrouped hosts (not in any group, still accessible via 'all')
standalone.example.com # => Host without group membership
 # => Reachable via: ansible standalone.example.com -m ping

# Group: webservers (logical grouping of web tier hosts)
[webservers] # => Group header (INI section format)
 # => Create logical grouping for fleet operations
web1.example.com ansible_host=192.168.1.10 # => Inventory hostname with IP override
 # => DNS name: web1.example.com
 # => Actual IP: 192.168.1.10 (ansible_host connection variable)
web2.example.com ansible_host=192.168.1.11 # => Second webserver with IP override
 # => Connects to 192.168.1.11 via SSH
web3.example.com ansible_port=2222 # => Third webserver with custom SSH port
 # => Default port 22 overridden to 2222
 # => Useful for security hardening (non-standard SSH ports)

# Group: databases (database tier hosts)
[databases] # => Database group header
 # => Separate from webservers for targeted operations
db1.example.com # => Database primary server
 # => Uses default connection settings (SSH port 22, current user)
db2.example.com ansible_user=dbadmin # => Database replica with custom SSH user
 # => Connects as 'dbadmin' instead of current user
 # => Requires SSH key or password for dbadmin

# Group of groups (parent group containing other groups)
[production:children] # => Parent group syntax: [groupname:children]
 # => Contains other groups, not individual hosts
webservers # => Include all hosts from webservers group
 # => Expands to: web1, web2, web3
databases # => Include all hosts from databases group
 # => Expands to: db1, db2
# => Result: 'production' contains 5 hosts (web1, web2, web3, db1, db2)
# => Enables targeting entire production environment: ansible production -m ping

# Group variables (apply to all hosts in group)
[webservers:vars] # => Variables for webservers group
 # => Applied to web1, web2, web3 automatically
ansible_python_interpreter=/usr/bin/python3 # => Override Python interpreter path
 # => Required when default Python is 2.x
 # => Ansible requires Python on target hosts
http_port=80 # => Custom variable (not Ansible built-in)
 # => Accessible in playbooks as {{ http_port }}
 # => Used for application configuration

[databases:vars] # => Variables for databases group
 # => Applied to db1, db2
db_port=5432 # => PostgreSQL default port
 # => Custom variable for database configuration
 # => Accessible as {{ db_port }} in playbooks

---
# inventory_demo.yml
- name: Use Inventory Groups # => Demonstrate inventory-based targeting
 hosts: webservers # => Target all hosts in webservers group
 # => Expands to: web1, web2, web3 from inventory file
 # => Ansible connects to each host via SSH sequentially or parallel (forks)
 gather_facts: false # => Skip fact gathering for speed

 tasks: # => Tasks execute on ALL hosts in webservers group
 - name: Display host information # => Show per-host information
 ansible.builtin.debug: # => Debug module runs on each target host
 msg: "Host {{ inventory_hostname }} on port {{ http_port }}" # => inventory_hostname is built-in variable
 # => inventory_hostname contains current host's name from inventory
 # => http_port comes from [webservers:vars] section (value: 80)
 # => Runs on web1, web2, web3 (all webservers group members)
 # => Output: Host web1.example.com on port 80
 # => Output: Host web2.example.com on port 80
 # => Output: Host web3.example.com on port 80

---
# inventory.yml - Static inventory in YAML format
all: # => Root group containing all hosts in inventory
 # => Special group automatically created by Ansible
 # => Contains both standalone hosts and grouped hosts
 hosts: # => Host definitions at root level
 # => Hosts here belong to 'all' group only (ungrouped)
 standalone.example.com: # => Ungrouped host entry
 # => Empty dict means no host-specific variables
 # => Reachable via: ansible standalone.example.com -m ping

 children: # => Nested groups under 'all' parent group
 # => Groups organize hosts logically (web tier, db tier, etc.)
 webservers: # => Webservers group definition
 # => Equivalent to [webservers] in INI format
 hosts: # => Host list for webservers group
 # => Each entry can have host-specific variables
 web1.example.com: # => First webserver entry
 # => Indented dict contains host variables
 ansible_host:
 192.168.1.10 # => Connection IP override
 # => Ansible connects to 192.168.1.10 instead of DNS lookup
 web2.example.com: # => Second webserver
 ansible_host:
 192.168.1.11 # => IP override for web2
 # => Enables static IP targeting
 web3.example.com: # => Third webserver with custom SSH port
 ansible_port:
 2222 # => Override default SSH port (22 → 2222)
 # => Security hardening via non-standard port
 vars: # => Group-level variables for all webservers
 # => Applied to web1, web2, web3 automatically
 ansible_python_interpreter:
 /usr/bin/python3 # => Python 3 interpreter path
 # => Required when Python 2.x is system default
 # => Ansible modules require Python on targets
 http_port:
 80 # => Custom application variable
 # => Accessible in playbooks as {{ http_port }}
 # => Not an Ansible built-in (user-defined)

 databases: # => Database group definition
 # => Separate tier from webservers
 hosts: # => Database host list
 db1.example.com: # => Primary database server
 # => Empty dict (no host-specific variables)
 # => Uses group vars and defaults
 db2.example.com: # => Replica database server
 ansible_user:
 dbadmin # => SSH username override
 # => Connects as 'dbadmin' user instead of current user
 # => Requires SSH key or password for dbadmin account
 vars: # => Database group variables
 # => Applied to db1, db2
 db_port:
 5432 # => PostgreSQL default port
 # => Custom variable for database configuration
 # => Accessible as {{ db_port }} in playbooks

 production: # => Parent group containing other groups
 # => Enables hierarchy: production → webservers/databases → hosts
 children: # => List of child groups (not hosts)
 # => Only groups allowed here (no individual hosts)
 webservers: # => Include webservers group (web1, web2, web3)
 # => All hosts from webservers become production members
 databases: # => Include databases group (db1, db2)
 # => All hosts from databases become production members
 vars: # => Variables applied to ALL production hosts
 # => Inherited by both webservers and databases groups
 environment:
 production # => Environment identifier
 # => Accessible as {{ environment }}
 # => Used for environment-specific logic in playbooks
 # => production group contains 5 total hosts

---
# patterns.yml
# Pattern examples (use with existing inventory)
# => Demonstrates host targeting patterns without inventory modification

# Target single host (most specific pattern)
- name: Single Host # => Most specific targeting pattern
 # => No wildcards, no groups, exact match only
 hosts:
 web1.example.com # => Exact hostname match from inventory
 # => Targets only this specific host
 # => No pattern matching or expansion
 # => Use case: one-off operations on individual servers
 # => Debugging, emergency fixes, specific maintenance
 tasks:
 - ansible.builtin.debug:
 msg="Single host" # => Executes only on web1
 # => Single execution output
 # => Output: ok: [web1.example.com] => { "msg": "Single host" }
 # => Other hosts in inventory remain untouched

# Target all hosts in group
- name: All Webservers # => Group-based targeting
 hosts: webservers # => All members of webservers group
 # => Expands to all hosts defined in [webservers] section
 # => web1.example.com, web2.example.com, web3.example.com
 tasks:
 - ansible.builtin.debug: msg="All webservers" # => Executes on each webserver
 # => Output appears 3 times (once per host)

# Wildcard pattern (all hosts starting with 'web')
- name: Wildcard Pattern # => Glob-style pattern matching
 hosts: web* # => Matches any hostname starting with 'web'
 # => Asterisk (*) wildcard matches zero or more characters
 # => Matches: web1, web2, web3, webserver, web-prod, etc.
 # => Does NOT match groups, only individual hostnames
 tasks:
 - ansible.builtin.debug: msg="Wildcard match" # => Runs on all web* hosts
 # => Pattern matching happens at inventory parsing time

# Union of groups (hosts in EITHER group)
- name: Union Pattern # => Combine multiple groups
 hosts: webservers:databases # => Colon (:) operator creates union
 # => Targets hosts in webservers OR databases (logical OR)
 # => Includes: web1, web2, web3, db1, db2 (5 hosts total)
 # => Duplicates removed automatically if host in both groups
 tasks:
 - ansible.builtin.debug: msg="Web or DB servers" # => Runs on union set
 # => 5 separate task executions

# Intersection of groups (hosts in BOTH groups)
- name: Intersection Pattern # => Hosts in multiple groups
 hosts: webservers:&production # => Colon-ampersand (:&) creates intersection
 # => Targets hosts in webservers AND production (logical AND)
 # => Only includes hosts that are members of BOTH groups
 # => Useful for filtering by environment (dev/staging/prod)
 tasks:
 - ansible.builtin.debug: msg="Webservers in production" # => Runs on intersection
 # => Fewer hosts than webservers alone

# Exclusion pattern (hosts in first group but NOT second)
- name: Exclusion Pattern # => Subtract hosts from targeting
 hosts: webservers:!web3.example.com # => Colon-exclamation (:!) excludes hosts
 # => Targets webservers EXCEPT web3.example.com (logical subtraction)
 # => Includes: web1, web2 (excludes web3)
 # => Exclusion can be hostname or group name
 tasks:
 - ansible.builtin.debug: msg="Webservers except web3" # => Runs on web1, web2 only
 # => web3 skipped entirely, not even shown in output

# Complex pattern combining operations
- name: Complex Pattern # => Multi-operation pattern
 hosts: webservers:&production:!web3.example.com # => Combines intersection and exclusion
 # => Read left-to-right: (webservers ∩ production) - web3
 # => Step 1: Hosts in webservers AND production
 # => Step 2: Remove web3.example.com from result
 # => Useful for maintenance windows, canary deployments
 tasks:
 - ansible.builtin.debug: msg="Production webservers except web3" # => Surgical targeting
 # => Targets production webservers with one host excluded

#!/usr/bin/env python3
# inventory.py (executable: chmod +x inventory.py)
# => Dynamic inventory script that outputs JSON to Ansible
# => Must be executable: chmod +x inventory.py before use
# => Ansible invokes this script to discover hosts dynamically
import json # => JSON library for formatting output
 # => Required for converting Python dict to JSON string
import sys # => System library for command-line argument parsing
 # => Used to check --list vs --host invocation mode

def get_inventory():
 """Return inventory in Ansible's expected JSON format"""
 # => Function constructs inventory structure as Python dictionary
 # => Ansible expects specific JSON structure with groups and hosts
 # => Must include _meta, groups, and 'all' group
 inventory = { # => Main inventory dictionary
 # => Top-level keys: _meta, group names, all
 "_meta": { # => Meta section for host variables
 # => Performance optimization to avoid multiple --host calls
 # => Including hostvars here prevents Ansible from calling --host for each host
 # => Without _meta, Ansible calls --host N times (slow for large inventories)
 # => With _meta: Ansible calls --list once, gets everything
 "hostvars": { # => Host-specific variables dictionary
 # => Key: hostname, Value: dict of variables
 "web1.local": { # => First host's variable dictionary
 # => Hostname must match exactly in hosts list
 "ansible_host": "192.168.1.10", # => SSH connection IP address
 # => Overrides DNS resolution for this host
 "http_port": 8080 # => Custom application variable
 # => Accessible in playbooks as {{ http_port }}
 # => User-defined (not Ansible built-in)
 },
 "web2.local": { # => Second host's variable dictionary
 # => Separate from web1 variables
 "ansible_host": "192.168.1.11", # => Different SSH IP for web2
 # => Each host has unique IP
 "http_port": 8080 # => Same http_port as web1
 # => Common configuration across group
 }
 }
 },
 "webservers": { # => Group definition (logical grouping)
 # => Group name used in playbook hosts: webservers
 # => Groups enable fleet operations across multiple hosts
 "hosts": ["web1.local", "web2.local"], # => List of group member hostnames
 # => Hostnames must match keys in hostvars
 # => Python list format
 "vars": { # => Group-level variables dictionary
 # => Apply to ALL hosts in this group
 "environment": "production" # => Environment identifier variable
 # => Accessible as {{ environment }}
 # => All hosts in webservers group inherit this variable
 # => Overrides host-level vars if conflict exists
 }
 },
 "all": { # => Special 'all' group (implicit in all inventories)
 # => Automatically includes ALL hosts across ALL groups
 # => Variables here apply to EVERY host (global scope)
 "vars": { # => Global variables for all hosts
 # => Lowest precedence (overridden by group/host vars)
 "ansible_python_interpreter": "/usr/bin/python3" # => Python interpreter path
 # => Ensures Python 3 usage on all targets
 # => Ensures Python 3 usage on all target systems
 # => Prevents Python 2 compatibility issues
 }
 }
 }
 return inventory # => Return complete inventory dictionary
 # => Will be converted to JSON by caller

if __name__ == "__main__":
 # => Script entry point (executed when run directly)
 # => Ansible invokes script with two possible command-line modes:
 # => 1. --list: get all inventory (called once)
 # => 2. --host <hostname>: get single host vars (called per host if no _meta)
 if len(sys.argv) == 2 and sys.argv[1] == "--list":
 # => --list mode: Return complete inventory (groups, hosts, vars)
 # => Ansible calls this ONCE per playbook run for full inventory
 # => sys.argv = ["inventory.py", "--list"]
 inventory = get_inventory() # => Generate inventory data structure
 # => Calls function defined above
 print(json.dumps(inventory, indent=2)) # => Output JSON to stdout
 # => indent=2 makes JSON human-readable
 # => Ansible parses stdout as inventory data
 # => No other output allowed (corrupts JSON)
 elif len(sys.argv) == 3 and sys.argv[1] == "--host":
 # => --host mode: Return variables for specific host
 # => Ansible calls --host <hostname> for each host if _meta missing
 # => sys.argv = ["inventory.py", "--host", "web1.local"]
 # => hostname = sys.argv[2] (e.g., "web1.local")
 print(json.dumps({})) # => Return empty dict (hostvars already in --list)
 # => Performance optimization: empty because _meta provides vars
 # => Performance: hostvars in _meta section eliminates N --host calls
 # => For 100 hosts: 1 --list call instead of 1 --list + 100 --host calls
 else:
 # => Invalid usage: neither --list nor --host provided
 # => Or wrong number of arguments
 print("Usage: inventory.py --list or --host <hostname>") # => Error message to stderr
 # => Shows correct invocation
 sys.exit(1) # => Non-zero exit code (1) signals error to Ansible
 # => Ansible aborts playbook execution on error

---
# command_vs_shell.yml - Demonstrates security and functionality differences
- name: Command vs Shell Comparison # => Compare safe (command) vs powerful (shell) modules
 hosts: localhost # => Execute on local machine
 gather_facts: false # => Skip fact collection (not needed)

 tasks: # => Task list demonstrating module differences
 # command module - Safe but limited (no shell interpreter)
 - name: Using command module (safe) # => Task 1: Safe command execution
 ansible.builtin.command: # => Command module bypasses shell
 # => No shell injection risk (safe for user input)
 # => Cannot use pipes, redirects, wildcards, variables
 cmd:
 echo "Hello World" # => Command with arguments
 # => Executes directly via exec() system call
 # => No /bin/bash or /bin/sh involved
 register:
 cmd_result # => Save task output to variable
 # => Stores stdout, stderr, rc (return code)
 # => changed: [localhost] (command module ALWAYS reports changed)
 # => Use changed_when: false to override this behavior
 # => stdout: "Hello World" (command output)

 - name: Display command result # => Task 2: Show command module output
 ansible.builtin.debug: # => Debug module for console output
 msg:
 "Command output: {{ cmd_result.stdout }}" # => Access stdout from registered variable
 # => cmd_result is dict with stdout/stderr/rc keys
 # => Output: Command output: Hello World
 # => Debug tasks never report changed status

 # command module - FAILS with shell features
 - name: Command module with pipe (FAILS) # => Task 3: Demonstrate command limitations
 ansible.builtin.command: # => Command module doesn't support pipes
 cmd:
 echo "test" | grep test # => Pipe character | not interpreted
 # => Passed literally to echo command
 # => ERROR: echo tries to output string "test | grep test"
 ignore_errors:
 true # => Continue playbook execution despite failure
 # => Prevents playbook abort on failed task
 # => failed: [localhost] (command module rejects shell metacharacters)
 # => Error message explains pipes/redirects require shell module

 # shell module - Full shell access (powerful but risky)
 - name: Using shell module (powerful but risky) # => Task 4: Full shell capabilities
 ansible.builtin.shell: # => Shell module invokes /bin/sh (or SHELL env var)
 # => Enables pipes, redirects, wildcards, variable expansion
 # => SECURITY RISK: vulnerable to shell injection attacks
 cmd:
 echo "Hello" | tr 'a-z' 'A-Z' # => Pipe works because shell interprets it
 # => echo outputs "Hello" → piped to tr
 # => tr translates lowercase to uppercase
 register:
 shell_result # => Save output to variable
 # => Same dict structure as command (stdout/stderr/rc)
 # => changed: [localhost] (shell module always reports changed)
 # => stdout: "HELLO" (pipe executed in bash subprocess)
 # => Both echo and tr executed in same shell process

 - name: Display shell result # => Task 5: Show shell module output
 ansible.builtin.debug: # => Debug output
 msg: "Shell output: {{ shell_result.stdout }}" # => Access stdout from shell task
 # => Output: Shell output: HELLO
 # => Demonstrates successful pipe execution

 # shell module - Environment variable expansion
 - name: Shell module with variables # => Task 6: Environment variable support
 ansible.builtin.shell: # => Shell module enables $VAR expansion
 cmd:
 echo "Current user is $USER" # => $USER expanded by shell to username
 # => Command module would output literal "$USER"
 # => Shell interprets environment variables
 register: user_result # => Capture output with username
 # => stdout: "Current user is <username>" (e.g., "Current user is admin")
 # => $USER environment variable replaced with actual username

 - name: Display user # => Task 7: Show expanded username
 ansible.builtin.debug: # => Debug module for output
 msg: "{{ user_result.stdout }}" # => Display stdout (contains expanded username)
 # => Output: Current user is <actual_username>
 # => Confirms shell variable expansion worked

---
# copy_module.yml - File transfer and inline content creation
- name: Copy Module Examples # => Demonstrate copy module capabilities
 hosts: localhost # => Execute on local machine
 gather_facts: false # => Skip fact gathering (not needed)

 tasks: # => Task list showing different copy patterns
 # Copy with inline content (no source file needed)
 - name: Create file with inline content # => Task 1: Write inline content to file
 ansible.builtin.copy: # => Copy module handles file creation/transfer
 # => Idempotent: checks content checksum before writing
 dest:
 /tmp/demo_inline.txt # => Destination path on target host
 # => Creates parent directory if missing
 content: | # => Inline multi-line content (literal YAML block)
 Line 1: Hello
 Line 2: World
 # => Literal block preserves newlines and formatting
 # => Content written exactly as shown (including trailing newline)
 mode:
 "0644" # => POSIX permissions (octal notation, quotes required)
 # => 0644 = rw-r--r-- (owner: rw, group: r, others: r)
 owner:
 "{{ ansible_user_id }}" # => File owner username
 # => ansible_user_id is fact (current SSH user)
 # => changed: [localhost] (creates file if missing or content/mode differs)
 # => ok: [localhost] (if file exists with identical content/permissions)
 # => Idempotency: compares SHA256 checksum of existing vs new content

 # Copy from file (first create source file)
 - name: Create source file # => Task 2: Prepare source file for copying
 ansible.builtin.copy: # => Copy module also creates source files
 dest: /tmp/source.txt # => Source file location
 content: "Source file content\n" # => Single-line content with newline
 # => Creates file at /tmp/source.txt for next task

 - name: Copy file from control node to target # => Task 3: File transfer operation
 ansible.builtin.copy: # => Copy mode: src→dest transfer
 # => Transfers files from control node to managed hosts
 src:
 /tmp/source.txt # => Source file path on control node
 # => Must exist before task runs
 dest:
 /tmp/destination.txt # => Destination path on target host
 # => Creates new file or overwrites existing
 mode: "0644" # => Override destination permissions
 backup:
 true # => Create timestamped backup before overwriting
 # => Backup format: <dest>.<pid>.<timestamp>~
 # => Only created if destination already exists
 register:
 copy_result # => Capture task results in variable
 # => Contains: changed, backup_file, checksum, dest
 # => changed: [localhost] (if content, mode, or owner differs)
 # => ok: [localhost] (if destination matches source exactly)
 # => backup_file key only present if backup created
 # => Example backup: /tmp/destination.txt.12345.2024-01-15@12:30:00~

 - name: Display backup location # => Task 4: Show backup path if created
 ansible.builtin.debug: # => Debug output module
 msg:
 "Backup created: {{ copy_result.backup_file | default('No backup needed') }}"
 # => Access backup_file from registered variable
 # => Jinja2 filter: default() provides fallback if key missing
 # => Output: "Backup created: /path.." (if backup created)
 # => Output: "Backup created: No backup needed" (if new file)

 # Copy with validation (critical for config files)
 - name: Copy configuration with validation # => Task 5: Safe config deployment
 ansible.builtin.copy: # => Copy with pre-deployment validation
 # => Prevents broken configs from reaching production
 dest: /tmp/config.conf # => Destination config file path
 content: | # => Configuration file content
 setting1=value1
 setting2=value2
 # => INI-style configuration format
 validate:
 'grep -q "setting1" %s' # => Validation command template
 # => %s replaced with temp file path
 # => Exit code 0 = valid, non-zero = invalid
 # => Process: writes to temp file → validates temp → replaces dest
 # => Runs validation: grep -q "setting1" /tmp/ansible.tmpXXXX
 # => Only replaces /tmp/config.conf if grep succeeds
 # => Task fails if validation fails (protects against bad configs)

---
# file_module.yml - Filesystem management without content transfer
- name: File Module Examples # => Demonstrate file module capabilities
 hosts: localhost # => Execute on local machine
 gather_facts: false # => Skip fact gathering (not needed)

 tasks: # => Task list for filesystem operations
 # Create directory (idempotent directory creation)
 - name: Create directory with specific permissions # => Task 1: Directory creation
 ansible.builtin.file: # => File module manages filesystem objects
 # => No content transfer (unlike copy module)
 # => Idempotent: safe to run multiple times
 path:
 /tmp/demo_dir # => Directory path to create
 # => Absolute path recommended for reliability
 # => Creates directory if missing
 state:
 directory # => Ensure path is a directory (not file/link)
 # => Creates directory if absent
 # => Verifies existing directory has correct attributes
 mode:
 "0755" # => POSIX permissions in octal notation (quotes required)
 # => 0755 = rwxr-xr-x (owner: rwx, group: rx, others: rx)
 # => Owner can read/write/execute, others can read/execute
 owner:
 "{{ ansible_user_id }}" # => Set directory owner to current user
 # => ansible_user_id is fact (current SSH user)
 # => Requires appropriate permissions to chown
 # => changed: [localhost] (directory created or attributes modified)
 # => ok: [localhost] (directory exists with correct mode/owner)
 # => Idempotent: running twice produces same result

 # Create nested directories (recursive directory creation)
 - name: Create nested directory structure # => Task 2: Nested directory creation
 ansible.builtin.file: # => File module with recursive option
 path:
 /tmp/demo_dir/sub1/sub2 # => Three-level nested path
 # => Target: /tmp/demo_dir/sub1/sub2
 state: directory # => Ensure path is directory
 mode: "0755" # => Permissions applied to all created directories
 recurse:
 true # => Create parent directories if missing
 # => Without recurse, task fails if parents don't exist
 # => Like mkdir -p command
 # => changed: [localhost] (creates demo_dir, sub1, sub2 as needed)
 # => Creates all missing parent directories in one operation
 # => Idempotent: ok if directory structure already exists

 # Touch file (create empty file or update timestamp)
 - name: Create empty file or update timestamp # => Task 3: Touch file operation
 ansible.builtin.file: # => File module with touch state
 path:
 /tmp/demo_dir/timestamp.txt # => File path inside created directory
 # => Must be absolute or relative path
 state:
 touch # => Create empty file or update modification time
 # => Like Linux touch command
 # => Updates mtime (modification time) and atime (access time)
 mode:
 "0644" # => Permissions for new file (rw-r--r--)
 # => Owner: rw, group: r, others: r
 # => changed: [localhost] (file created or timestamps updated)
 # => Creates zero-byte file if missing
 # => Updates timestamps if file exists

 # Create symlink (symbolic link creation)
 - name: Create symbolic link # => Task 4: Symlink creation
 ansible.builtin.file: # => File module with link state
 src:
 /tmp/demo_dir # => Link target (what symlink points to)
 # => Can be absolute or relative path
 # => Target doesn't need to exist (dangling symlink allowed)
 dest:
 /tmp/demo_link # => Link path (the symlink itself)
 # => This is the symlink file created
 # => Must not already exist as regular file
 state:
 link # => Create symbolic link (soft link, not hard link)
 # => Creates symlink pointing from dest to src
 # => Like ln -s command
 # => changed: [localhost] (symlink created)
 # => Creates: /tmp/demo_link -> /tmp/demo_dir
 # => ls -la output: lrwxr-xr-x .. /tmp/demo_link -> /tmp/demo_dir
 # => Following symlink reaches /tmp/demo_dir directory

 # Modify permissions and ownership (attribute modification)
 - name: Change file permissions # => Task 5: Permission modification
 ansible.builtin.file: # => File module modifying existing file
 path:
 /tmp/demo_dir/timestamp.txt # => Target file to modify
 # => File must already exist
 mode:
 "0600" # => New permissions (rw-------)
 # => Owner: rw, group: none, others: none
 # => Restricts access to owner only (security hardening)
 # => changed: [localhost] (if current permissions differ from 0600)
 # => ok: [localhost] (if permissions already 0600)
 # => Idempotent: only changes if different

 # Remove file (file deletion)
 - name: Remove file # => Task 6: File deletion
 ansible.builtin.file: # => File module with absent state
 path:
 /tmp/demo_dir/timestamp.txt # => File to delete
 # => Absolute path for safety
 state:
 absent # => Ensure file does not exist
 # => Deletes file if present
 # => Succeeds if already absent (idempotent)
 # => changed: [localhost] (file deleted if it existed)
 # => ok: [localhost] (file already absent, no action needed)
 # => Idempotent: safe to run multiple times

 # Remove directory recursively (directory deletion)
 - name: Remove directory and contents # => Task 7: Recursive directory deletion
 ansible.builtin.file: # => File module deleting directory
 path:
 /tmp/demo_dir # => Directory to remove
 # => Removes directory and ALL contents
 state:
 absent # => Ensure directory does not exist
 # => Recursive deletion (like rm -rf)
 # => Deletes files, subdirectories, symlinks inside
 # => changed: [localhost] (directory and contents deleted)
 # => Dangerous operation: no confirmation, no trash/recycle
 # => Use with caution in production (irreversible)

---
# template_module.yml - Jinja2 template rendering demonstration
- name: Template Module Example # => Play demonstrating template rendering
 hosts: localhost # => Execute on local machine
 gather_facts: false # => Skip fact gathering (not needed)

 vars: # => Variables section (all vars available to template)
 # => Template accesses these via {{ variable_name }}
 http_port:
 8080 # => Port number for nginx listen directive
 # => Integer value (no quotes)
 # => Rendered in template as: listen 8080;
 server_name:
 example.com # => Virtual host server name
 # => String value for DNS matching
 # => Rendered as: server_name example.com;
 document_root:
 /var/www/html # => Root directory for served files
 # => Absolute path to document root
 # => Rendered as: root /var/www/html;
 enable_ssl:
 true # => Boolean flag for conditional SSL block
 # => Controls {% if enable_ssl %} in template
 # => true includes SSL config, false excludes it
 ssl_cert_path:
 /etc/ssl/cert.pem # => SSL certificate file path
 # => Used only if enable_ssl is true
 ssl_key_path:
 /etc/ssl/key.pem # => SSL private key file path
 # => Used only if enable_ssl is true
 custom_locations: # => List variable for Jinja2 {% for %} loop
 # => Each item is dict with path/backend keys
 - path: /api # => First location: API endpoint path
 backend:
 http://localhost:3000 # => Backend server for /api requests
 # => Proxy target for API calls
 - path: /admin # => Second location: Admin interface path
 backend:
 http://localhost:4000 # => Backend server for /admin requests
 # => Separate backend for admin panel

 tasks: # => Task list begins
 - name: Render template to file # => Task 1: Template rendering and deployment
 ansible.builtin.template: # => Template module renders Jinja2 to plain text
 # => Processing happens on control node
 # => Rendered output copied to target host
 src:
 nginx.conf.j2 # => Source template file path
 # => Path relative to playbook directory
 # => Must have .j2 extension (convention)
 # => Template uses Jinja2 syntax ({{}} and {%%})
 dest:
 /tmp/nginx.conf # => Destination path for rendered output
 # => Plain nginx config (no Jinja2 syntax)
 # => All variables replaced with actual values
 mode:
 "0644" # => File permissions for rendered output
 # => Readable by all, writable by owner only
 backup:
 true # => Create timestamped backup before overwriting
 # => Backup format: <dest>.<pid>.<timestamp>~
 # => Only created if dest file already exists
 # => changed: [localhost] (template rendered and written to dest)
 # => Template rendering: reads src, processes Jinja2, writes dest
 # => Variables substituted: {{ http_port }} → 8080, {{ server_name }} → example.com
 # => Conditionals evaluated: {% if enable_ssl %} → includes SSL block
 # => Loops expanded: {% for location in custom_locations %} → 2 location blocks

 - name: Display rendered configuration # => Task 2: Read rendered output
 ansible.builtin.command: # => Execute shell command to read file
 cmd:
 cat /tmp/nginx.conf # => Read rendered nginx config
 # => Shows final output with all substitutions
 register:
 rendered_config # => Save command output to variable
 # => Contains stdout with file contents

 - name: Show configuration # => Task 3: Display rendered template
 ansible.builtin.debug: # => Debug module for console output
 msg:
 "{{ rendered_config.stdout }}" # => Access stdout from registered variable
 # => Shows complete rendered nginx config
 # => Output shows final config with:
 # => - Variables replaced (http_port=8080, server_name=example.com)
 # => - Conditional SSL block included (enable_ssl=true)
 # => - Two location blocks from loop (custom_locations list)
 # => Template rendering complete: Jinja2 → plain nginx config

---
# package_management.yml - Cross-platform package management
# => Demonstrates generic and distribution-specific package modules
- name: Package Management Examples # => Playbook for software installation patterns
 # => Shows package, apt, yum module usage
 hosts: localhost # => Execute on control node
 # => localhost avoids SSH connection overhead
 become: true # => Require sudo/root privileges for package operations
 # => Package installation requires elevated permissions
 # => Without become, tasks fail with permission denied
 gather_facts: true # => Collect system facts for OS detection
 # => Facts needed for ansible_os_family conditional logic
 # => Enables distribution-specific task execution

 tasks: # => Task list demonstrating package management patterns
 # Generic package module (cross-platform abstraction)
 - name: Install package using generic module # => Task 1: Cross-platform installation
 ansible.builtin.package: # => Generic package module
 # => Automatically detects package manager (apt/yum/dnf/zypper)
 # => Ansible chooses implementation based on ansible_pkg_mgr fact
 name: curl # => Package name (consistent across distributions)
 # => Same name works on Debian and RedHat families
 state: present # => Ensure package is installed
 # => Idempotent: no action if already installed
 # => changed: [localhost] (installs curl if missing)
 # => ok: [localhost] (if curl already installed)
 # => Works on Debian, RedHat, SUSE families automatically
 # => Internally calls apt/yum/zypper based on detected OS

 # Debian/Ubuntu specific (apt module with advanced features)
 - name: Install package using apt # => Task 2: Debian-specific installation
 ansible.builtin.apt: # => APT package manager (Debian/Ubuntu)
 # => Provides Debian-specific features beyond generic module
 # => Enables cache management, repository control
 name: nginx # => Package name from Debian repositories
 # => Installs latest available version from enabled repos
 state: present # => Ensure nginx installed
 update_cache: true # => Run apt-get update before installation
 # => Refreshes package index from remote repositories
 # => Ensures latest package metadata available
 cache_valid_time: 3600 # => Cache valid for 1 hour (3600 seconds)
 # => Skip update if cache refreshed within 1 hour
 # => Performance optimization: reduces repository queries
 when: ansible_os_family == "Debian" # => Conditional execution for Debian-based systems
 # => Only runs on Ubuntu, Debian, Linux Mint, etc.
 # => Skipped on RedHat/CentOS/Fedora systems
 # => changed: [localhost] (updates cache and installs nginx)
 # => ok: [localhost] (if nginx already installed and cache fresh)

 # Install multiple packages (batch installation)
 - name: Install multiple packages # => Task 3: Bulk package installation
 ansible.builtin.package: # => Generic module handles multiple packages
 # => Single transaction for all packages (faster than separate tasks)
 name: # => List of package names
 # => YAML list format enables multiple packages
 - git # => Version control system
 # => First package in list
 - vim # => Text editor
 # => Second package in list
 - htop # => Interactive process viewer
 # => Third package in list
 state: present # => Install all packages if missing
 # => Atomic operation: all succeed or all fail
 # => changed: [localhost] (installs missing packages)
 # => ok: [localhost] (if all packages already installed)
 # => Installs all packages in single transaction (faster than 3 separate tasks)
 # => Reduced overhead: one package manager invocation instead of three

 # Install specific version (version pinning)
 - name: Install specific package version # => Task 4: Version-specific installation
 ansible.builtin.apt: # => APT module supports version pinning
 # => Generic package module doesn't support version specification
 name: nginx=1.18.0-0ubuntu1 # => Exact version specification format
 # => Package name + equals + version string
 # => Format: name=version (Debian convention)
 state: present # => Install specified version
 # => Downgrades if newer version installed
 # => Upgrades if older version installed
 when: ansible_os_family == "Debian" # => Debian-only task
 # => Version format varies by distribution
 # => changed: [localhost] (installs or changes to specified version)
 # => Used for compliance, security patches, compatibility requirements

 # Remove package (uninstallation)
 - name: Remove package # => Task 5: Package removal
 ansible.builtin.package: # => Generic module supports removal
 # => Works across all package managers
 name: htop # => Package to remove
 # => Must match installed package name exactly
 state: absent # => Ensure package is NOT installed
 # => Idempotent: no action if already absent
 # => Opposite of state: present
 # => changed: [localhost] (removes htop if installed)
 # => ok: [localhost] (if htop already absent)
 # => Leaves configuration files (not purge)
 # => Use apt module with purge: yes to remove configs

 # Update all packages (system-wide upgrade)
 - name: Update all packages # => Task 6: Distribution upgrade
 ansible.builtin.apt: # => APT module for Debian upgrade operations
 # => Generic module doesn't support full system upgrades
 upgrade: dist # => Distribution upgrade type
 # => dist = apt-get dist-upgrade (installs/removes packages as needed)
 # => safe = apt-get upgrade (no package removal)
 # => full = apt-get full-upgrade (same as dist)
 update_cache: true # => Refresh package lists before upgrade
 # => Ensures latest package versions discovered
 when: ansible_os_family == "Debian" # => Debian-only operation
 # => Equivalent: yum update for RedHat systems
 # => changed: [localhost] (upgrades packages with new dependencies)
 # => WARNING: Can upgrade hundreds of packages, long execution time

---
# service_management.yml - System service lifecycle management
# => Demonstrates service module for init system control
- name: Service Management Examples # => Playbook for service operations
 # => Shows systemd, SysV, upstart compatibility
 hosts: localhost # => Execute on control node
 # => Service management typically runs on all servers
 become: true # => Service management requires root privileges
 # => Non-root users cannot start/stop/enable system services
 # => Without become, tasks fail with permission errors
 gather_facts: false # => Skip fact collection (not needed)
 # => Service module works without facts

 tasks: # => Task list demonstrating service states and boot configuration
 # Ensure service is running (start if stopped)
 - name: Start service # => Task 1: Ensure service running
 ansible.builtin.service: # => Service module (cross-init-system abstraction)
 # => Works with systemd, SysV init, upstart automatically
 # => Ansible detects init system and uses appropriate commands
 name: nginx # => Service name (systemd unit or init script name)
 # => Matches service file name: /lib/systemd/system/nginx.service
 # => Or init script: /etc/init.d/nginx
 state: started # => Ensure service is currently running
 # => Idempotent: only starts if not already running
 # => Does NOT restart if already running
 # => changed: [localhost] (if service was stopped, starts it)
 # => Internally runs: systemctl start nginx (on systemd systems)
 # => ok: [localhost] (if service already running, no action)
 # => Check with: systemctl status nginx or service nginx status

 # Ensure service is stopped (stop if running)
 - name: Stop service # => Task 2: Ensure service not running
 ansible.builtin.service: # => Service module for stopping
 name: nginx # => Same service name as start task
 state: stopped # => Ensure service is NOT running
 # => Idempotent: only stops if currently running
 # => changed: [localhost] (if service was running, stops it gracefully)
 # => Sends SIGTERM signal for graceful shutdown
 # => ok: [localhost] (if service already stopped)
 # => Internally runs: systemctl stop nginx

 # Restart service (unconditional restart)
 - name: Restart service # => Task 3: Force service restart
 ansible.builtin.service: # => Service module for restart
 name: nginx # => Service to restart
 state: restarted # => Always restart (NOT idempotent)
 # => Stops then starts service regardless of current state
 # => ALWAYS reports changed (even if already running)
 # => changed: [localhost] (stops then starts service)
 # => Causes brief service interruption (downtime)
 # => Internally runs: systemctl restart nginx
 # => Use after config changes that require full restart

 # Reload configuration without full restart (zero-downtime)
 - name: Reload service configuration # => Task 4: Configuration reload
 ansible.builtin.service: # => Service module for reload operation
 name: nginx # => Service supporting reload
 # => Not all services support reload (service must handle SIGHUP)
 state: reloaded # => Send reload signal to service
 # => Sends SIGHUP signal (hangup signal)
 # => Service re-reads configuration without stopping
 # => changed: [localhost] (nginx reloads config without dropping connections)
 # => Zero downtime: active connections continue serving
 # => Internally runs: systemctl reload nginx or nginx -s reload
 # => Preferred over restart for web servers (no connection drops)

 # Enable service at boot (persistence configuration)
 - name: Enable service to start at boot # => Task 5: Boot persistence
 ansible.builtin.service: # => Service module for boot configuration
 name: nginx # => Service to enable at boot
 enabled: true # => Enable service in init system
 # => Creates systemd symlink or init script links
 # => Does NOT start service immediately (only affects boot)
 # => changed: [localhost] (creates systemd symlink or init script link)
 # => Internally runs: systemctl enable nginx
 # => Creates symlink: /etc/systemd/system/multi-user.target.wants/nginx.service
 # => Service starts automatically after reboot

 # Disable service at boot (prevent auto-start)
 - name: Disable service at boot # => Task 6: Disable boot persistence
 ansible.builtin.service: # => Service module for boot configuration
 name: nginx # => Service to disable from boot
 enabled: false # => Disable service from starting at boot
 # => Removes systemd symlinks or init script links
 # => Does NOT stop currently running service
 # => changed: [localhost] (removes systemd symlink)
 # => Internally runs: systemctl disable nginx
 # => Service will NOT start after reboot
 # => Use for services that should only run manually

 # Combined: Start and enable (most common pattern)
 - name: Ensure service is running and enabled # => Task 7: Complete service setup
 ansible.builtin.service: # => Service module with dual configuration
 # => Both runtime state AND boot configuration
 name: nginx # => Service name
 state: started # => Ensure currently running (runtime state)
 # => Starts service if stopped
 enabled: true # => Ensure starts at boot (boot configuration)
 # => Creates boot persistence
 # => changed: [localhost] (if either state or enabled changes)
 # => Reports changed if service started OR enabled modified
 # => ok: [localhost] (if already running and enabled)
 # => This is the MOST COMMON pattern for production services
 # => Ensures service running NOW and persists across reboots