Advanced

# library/hello.py
#!/usr/bin/python
# => Shebang for direct execution
# => Module files must be executable
from ansible.module_utils.basic import AnsibleModule
# => Core class for all custom modules
# => Provides argument parsing and result handling

def run_module():
 # => Main entry point for module execution
 module_args = dict(
 name=dict(type='str', required=True)
 # => Defines 'name' parameter
 # => Type validation: must be string
 # => Required: task fails if missing
 )

 module = AnsibleModule(
 # => Creates module instance
 # => Parses task args against spec
 argument_spec=module_args,
 # => Links to argument definitions above
 supports_check_mode=True
 # => Enables --check (dry-run) mode
 # => Module reports what would change without acting
 )

 result = dict(
 # => Result dictionary for Ansible
 changed=False,
 # => No state changes in hello module
 # => Set to True if module modifies system
 message=f"Hello, {module.params['name']}!"
 # => Access parsed params via module.params dict
 # => Returns greeting message
 )

 module.exit_json(**result)
 # => Returns result to Ansible core
 # => exit_json() for success (vs exit_fail_json() for errors)
 # => ** unpacks result dict as keyword args

if __name__ == '__main__':
 # => Python idiom: only run if script executed directly
 run_module()
 # => Executes module logic
# => Usage: ansible localhost -m hello -a "name=World"
# => Output: "Hello, World!"

# library/user_quota.py
#!/usr/bin/python
# => Custom module for managing user disk quotas
from ansible.module_utils.basic import AnsibleModule
# => Import core module utilities
import os
# => For filesystem operations

def main():
 # => Main module execution function
 module = AnsibleModule(
 # => Initialize module with argument spec
 argument_spec=dict(
 username=dict(required=True),
 # => Target username (required parameter)
 # => No type specified: defaults to 'str'
 quota_mb=dict(type='int', default=1000),
 # => Quota size in megabytes
 # => Type enforced: must be integer
 # => Default: 1000MB if not specified
 state=dict(choices=['present', 'absent'], default='present')
 # => Desired state of quota
 # => Choices: only 'present' or 'absent' allowed
 # => Default: 'present' (create/maintain quota)
 )
 )

 username = module.params['username']
 # => Extract username from parsed parameters
 quota = module.params['quota_mb']
 # => Extract quota value (integer)
 state = module.params['state']
 # => Extract desired state

 quota_file = f"/etc/quotas/{username}"
 # => Quota stored in file per user
 # => Path: /etc/quotas/alice for user 'alice'
 exists = os.path.exists(quota_file)
 # => Check if quota file currently exists
 # => True if present, False if absent

 changed = False
 # => Initialize changed flag to False
 # => Will set to True only if module modifies state

 if state == 'present' and not exists:
 # => Desired: present, Current: absent → CREATE
 with open(quota_file, 'w') as f:
 # => Create new quota file
 f.write(str(quota))
 # => Write quota value to file
 # => Convert int to string for storage
 changed = True
 # => State changed: resource created
 msg = f"Created quota {quota}MB for {username}"
 # => Descriptive message for playbook output
 elif state == 'absent' and exists:
 # => Desired: absent, Current: present → DELETE
 os.remove(quota_file)
 # => Delete quota file
 changed = True
 # => State changed: resource removed
 msg = f"Removed quota for {username}"
 # => Confirmation message
 else:
 # => State already matches desired
 # => present+exists OR absent+not_exists
 msg = f"Quota already in desired state"
 # => No action taken (idempotent)
 # => changed remains False

 module.exit_json(changed=changed, msg=msg)
 # => Return results to Ansible
 # => changed: triggers handlers if True
 # => msg: displayed in playbook output

if __name__ == '__main__':
 # => Execute only when run as script
 main()
 # => Call main function

# requirements.yml
---
collections:
 # => List of collections to install
 - name: community.general
 # => Collection name: namespace.collection
 # => Maintained by Ansible community
 version: ">=8.0.0"
 # => Minimum version constraint
 # => Allows 8.0.0, 8.1.0, 9.0.0, etc.
 # => Prevents breaking changes from older versions
 - name: ansible.posix
 # => Collection for POSIX system management
 # => Modules for mount, authorized_key, etc.
 version: "9.0.0"
 # => Exact version pinning
 # => Ensures reproducible environments
# => Install with: ansible-galaxy collection install -r requirements.yml
# => Collections installed to ~/.ansible/collections or ./collections/

# use_collection.yml
---
- name: Using Collection Modules
 # => Demonstrates FQCN module references
 hosts: localhost
 # => Run on control node
 tasks:
 - name: Archive files with community.general
 community.general.archive:
 # => FQCN format: namespace.collection.module
 # => Uses 'archive' module from community.general collection
 path: /tmp/mydir
 # => Source directory to archive
 dest: /tmp/archive.tar.gz
 # => Output archive file path
 format: gz
 # => Compression format: gzip
 # => Other options: bz2, xz, zip
 # => Creates compressed archive of directory
 # => Without FQCN: might conflict with other 'archive' modules

 - name: Mount filesystem with ansible.posix
 ansible.posix.mount:
 # => FQCN reference to mount module
 # => From ansible.posix collection
 path: /mnt/data
 # => Mount point directory
 src: /dev/sdb1
 # => Device to mount
 fstype: ext4
 # => Filesystem type
 state: mounted
 # => Ensure mounted and entry in /etc/fstab
 # => 'present': fstab entry only, 'mounted': also mount now
 # => FQCN prevents conflicts with custom 'mount' modules
 # => Makes playbook explicit about module source

# molecule/default/molecule.yml
---
driver:
 # => Infrastructure driver for test instances
 name: docker
 # => Use Docker containers as test targets
 # => Fast startup, isolated, disposable
 # => Alternatives: vagrant, ec2, azure
platforms:
 # => List of test instances to create
 - name: ubuntu-test
 # => Instance name (container name)
 image: ubuntu:22.04
 # => Docker image to use
 # => Official Ubuntu 22.04 LTS image
 pre_build_image: true
 # => Use image as-is, don't rebuild
 # => Faster than building custom Dockerfile
provisioner:
 # => Tool for applying configuration
 name: ansible
 # => Use Ansible as provisioner (default)
 playbooks:
 # => Playbook mappings for lifecycle phases
 converge: converge.yml
 # => Playbook that applies the role
 # => "Converge" = bring to desired state
# => Run with: molecule test
# => Full lifecycle: create → converge → verify → destroy

# molecule/default/converge.yml
---
- name: Converge
 # => Apply role to test instance
 # => "Converge" = configure instance to desired state
 hosts: all
 # => Target all instances defined in molecule.yml
 # => In this case: ubuntu-test
 roles:
 # => List of roles to test
 - role: my_role
 # => Role being tested (in roles/my_role/)
 vars:
 # => Variables for role execution
 app_port: 8080
 # => Example variable: application port
 # => Tests role with specific configuration
# => Molecule executes this playbook during 'converge' phase
# => Role applied to fresh container each test run

# molecule/default/verify.yml
---
- name: Verify
 # => Test that role worked correctly
 # => Runs after converge completes
 hosts: all
 # => Test all instances
 tasks:
 - name: Check service is running
 # => Verification task
 service:
 # => Query service state
 name: myapp
 # => Service installed by role
 state: started
 # => Expected state: running
 check_mode: yes
 # => Don't change anything, only check
 register: result
 # => Capture module output
 failed_when: result.changed
 # => Fail if service NOT running
 # => Logic: if check_mode reports 'would change',
 # => it means service is currently stopped
 # => Therefore test fails (service should be running)

# .ansible-lint
---
profile: production
# => Use production rule profile
# => Stricter than 'basic', less than 'safety'
# => Enforces idempotency, proper naming, no shell when module exists

skip_list:
  # => Rules to skip (disable)
  - yaml[line-length]
  # => Allow long lines in YAML
  # => Default: 160 chars, but URLs/JMESPath can exceed
  - name[casing]
  # => Allow any task name casing
  # => Default enforces: Title Case or Sentence case

warn_list:
  # => Rules that warn but don't fail
  - experimental
  # => Warn on experimental Ansible features
  # => Allows usage but flags for review

exclude_paths:
  # => Directories to skip during linting
  - .cache/
  # => Ansible cache directory
  - test/fixtures/
  # => Test data files (not real playbooks)
  - molecule/
  # => Molecule scenarios (separate test context)
# => Run with: ansible-lint site.yml
# => Returns exit code 0 (pass) or 2 (violations found)

# CI pipeline integration
ansible-lint playbooks/*.yml --force-color --format pep8 > lint-results.txt
# => Lint all playbooks with CI-compatible output format
# => Returns non-zero exit code on failures, failing build

# ansible.cfg
[defaults]
gathering = smart
# => Fact gathering mode
# => 'smart': gather only if facts missing/expired
# => 'implicit': always gather (default, slow)
# => 'explicit': never gather unless gather_facts: yes
fact_caching = jsonfile
# => Cache backend type (jsonfile, redis, memcached)
# => jsonfile: simple disk-based cache, no external dependencies
fact_caching_connection = /tmp/ansible_facts
# => Backend connection: directory for jsonfile, URL for redis/memcached
# => Example redis: redis://localhost:6379/0
fact_caching_timeout = 86400
# => Cache expiration: 86400 seconds = 24 hours
# => Facts re-gathered after timeout expires

# playbook.yml
---
- name: Use Cached Facts
 # => Demonstrates fact caching behavior
 hosts: all
 # => Target all hosts in inventory
 gather_facts: yes
 # => Enable fact gathering
 # => With gathering=smart: uses cache if available
 tasks:
 - name: Print cached IP
 # => Display host IP address from facts
 debug:
 msg: "IP: {{ ansible_default_ipv4.address }}"
 # => ansible_default_ipv4: fact gathered from host
 # => .address: specific fact attribute (IP string)
 # => First run: gathers facts from all hosts (slow)
 # => Example: 1000 hosts × 3 seconds = 50 minutes
 # => Subsequent runs within 24h: loads from cache (fast)
 # => Example: 1000 hosts × 0.01 seconds = 10 seconds
 # => 98% time reduction for large inventories

# ansible.cfg
[defaults]
pipelining = True
# => Enable SSH pipelining globally
# => Reduces SSH roundtrips per module execution
# => Requires: sudo without requiretty

[ssh_connection]
pipelining = True
# => Redundant with [defaults] setting but explicit
# => Some Ansible versions check this section first
ssh_args = -o ControlMaster=auto -o ControlPersist=60s
# => SSH multiplexing configuration
# => ControlMaster=auto: create/reuse SSH connection socket
# => ControlPersist=60s: keep connection alive 60s after last use
# => Reduces SSH handshake overhead (TLS negotiation, authentication)
# => Example: 100 tasks × 5 SSH connections (without) → 1 connection (with)

# playbook.yml
---
- name: Fast Execution with Pipelining
 # => Demonstrates pipelining performance benefits
 # => ansible.cfg pipelining=True required for optimization
 hosts: webservers
 # => Target webserver group
 # => Executes on all hosts in parallel
 tasks:
 - name: Install 10 packages
 # => Package installation task
 # => Single task installs multiple packages atomically
 apt:
 # => Debian/Ubuntu package module
 # => Uses APT package manager
 name:
 # => List of packages to install
 # => YAML array format for bulk operations
 - pkg1
 - pkg2
 - pkg3
 - pkg4
 - pkg5
 - pkg6
 - pkg7
 - pkg8
 - pkg9
 - pkg10
 # => 10 packages in single task
 # => More efficient than 10 separate tasks
 state: present
 # => Ensure packages installed
 # => Idempotent: skips already-installed packages
 # => Without pipelining per host:
 # => SSH connect → create /tmp/ansible-modulefile → execute → delete
 # => With pipelining: SSH connect → pipe module → execute (no temp file)
 # => ~2 seconds overhead per module execution
 # => With pipelining:
 # => SSH connect → stream module code → execute
 # => ~0.5 seconds overhead per module
 # => 30-40% faster execution on large playbooks

# .github/workflows/ansible-ci.yml
name: Ansible CI
# => Workflow name displayed in GitHub Actions UI
on: [push, pull_request]
# => Trigger on code push or PR creation
# => Validates changes before merge

jobs:
 # => Define workflow jobs
 test:
 # => Job name: 'test'
 runs-on: ubuntu-latest
 # => Run on GitHub-hosted Ubuntu runner
 # => Latest Ubuntu LTS version
 steps:
 # => Sequential steps in job
 - uses: actions/checkout@v3
 # => Check out repository code
 # => Clones repo to runner workspace

 - name: Setup Python
 # => Install Python interpreter
 uses: actions/setup-python@v4
 # => GitHub action for Python setup
 with:
 # => Action parameters
 python-version: "3.11"
 # => Ansible requires Python 3.8+
 # => 3.11: stable, good performance

 - name: Install Ansible
 run: pip install ansible ansible-lint
 # => Install Ansible and linter via pip
 # => Latest stable versions from PyPI
 # => Creates isolated environment per workflow run

 - name: Syntax check
 run: ansible-playbook site.yml --syntax-check
 # => Validate YAML syntax and basic structure
 # => Catches: invalid YAML, undefined variables in jinja2
 # => Fast check: doesn't connect to hosts
 # => Fails workflow if syntax errors found

 - name: Lint playbooks
 run: ansible-lint site.yml
 # => Check best practices and anti-patterns
 # => Enforces style guide and idempotency
 # => Uses .ansible-lint config if present
 # => Fails on violations (exit code 2)

 - name: Run playbook
 run: ansible-playbook site.yml -i inventory/ci
 # => Execute playbook against CI inventory
 # => CI inventory: localhost or Docker containers
 # => Tests playbook logic without affecting production
 # => Validates tasks execute successfully

 - name: Test idempotency
 run: |
 # => Multi-line shell script
 ansible-playbook site.yml -i inventory/ci | tee first-run.txt
 # => First run: captures output to file
 # => tee: display output AND save to file
 ansible-playbook site.yml -i inventory/ci | tee second-run.txt
 # => Second run: should make zero changes
 grep -q 'changed=0' second-run.txt
 # => Search for 'changed=0' in output
 # => grep -q: quiet mode (exit code only)
 # => Fails if any task reported changes
 # => Validates playbook is truly idempotent

# rolling_update.yml
---
- name: Rolling Update Web Servers
 # => Zero-downtime deployment pattern
 hosts: webservers
 # => Target all webservers
 # => Example: 10 hosts total
 serial: 2
 # => Process 2 hosts at a time
 # => Batch size controls deployment speed vs risk
 # => Smaller batches: safer but slower
 max_fail_percentage: 25
 # => Abort deployment if >25% of batch fails
 # => Example: 2 host batch, abort if 1 fails
 # => Prevents bad deployments from affecting entire fleet

 pre_tasks:
 # => Execute before main tasks on each batch
 - name: Remove from load balancer
 # => Drain traffic before updating host
 uri:
 # => HTTP module for API calls
 url: "http://lb.example.com/api/hosts/{{ inventory_hostname }}/disable"
 # => Load balancer API endpoint
 # => {{ inventory_hostname }}: current host (e.g., web1.example.com)
 method: POST
 # => POST request to disable host
 delegate_to: localhost
 # => Execute API call from control node
 # => Not from target host
 # => Prevents 'calling API from server being updated'

 tasks:
 - name: Deploy new version
 # => Copy application artifact
 copy:
 src: "app-{{ app_version }}.jar"
 # => Source: local file on control node
 # => {{ app_version }}: variable (e.g., v2.5.0)
 dest: /opt/myapp/app.jar
 # => Destination: application directory
 notify: Restart application
 # => Trigger handler to restart service
 # => Handler runs at end of play

 - name: Wait for application health
 # => Verify app started successfully
 uri:
 url: "http://{{ inventory_hostname }}:8080/health"
 # => Health check endpoint
 # => Query updated host directly
 status_code: 200
 # => Expected HTTP status: 200 OK
 retries: 10
 # => Retry up to 10 times
 delay: 3
 # => Wait 3 seconds between retries
 # => Total max wait: 30 seconds
 # => Fails if health check doesn't pass

 post_tasks:
 # => Execute after main tasks complete successfully
 - name: Add back to load balancer
 # => Restore traffic to updated host
 uri:
 url: "http://lb.example.com/api/hosts/{{ inventory_hostname }}/enable"
 # => Re-enable host in LB
 method: POST
 delegate_to: localhost
 # => Execute from control node

 handlers:
 # => Triggered by 'notify' directive
 - name: Restart application
 # => Restart app service
 service:
 name: myapp
 # => Service name from systemd/init
 state: restarted
 # => Stop then start service
 # => Loads new app.jar file

# canary_deploy.yml
---
- name: Canary Deployment
 # => Risk-reduction deployment pattern
 hosts: webservers
 # => All webservers (canary + production)
 tasks:
 - name: Deploy to canary hosts
 # => Stage 1: Deploy to canary subset
 copy:
 src: "app-{{ new_version }}.jar"
 # => New version artifact
 dest: /opt/myapp/app.jar
 when: "'canary' in group_names"
 # => Conditional: only run if host in 'canary' group
 # => group_names: list of groups host belongs to
 # => Example: ['webservers', 'canary'] → True
 # => Example: ['webservers', 'production'] → False
 notify: Restart application
 # => Trigger app restart handler

 - name: Wait for canary validation
 # => Manual validation checkpoint
 pause:
 # => Pause playbook execution
 prompt: "Check metrics. Press enter to continue or Ctrl-C to abort"
 # => Display message and wait for user input
 # => User validates: error rates, latency, logs, metrics
 # => Enter: proceed to production rollout
 # => Ctrl-C: abort playbook (no production deploy)
 when: "'canary' in group_names"
 # => Only pause when deploying to canary
 # => Skipped for production group

 - name: Deploy to production
 # => Stage 2: Deploy to all production servers
 copy:
 src: "app-{{ new_version }}.jar"
 dest: /opt/myapp/app.jar
 when: "'production' in group_names"
 # => Only run on production group hosts
 # => Executes AFTER canary validation passes
 notify: Restart application

# inventory.ini
[canary]
# => Canary group: single host for testing
web1.example.com
# => 1% of fleet (1 of 100 servers)
# => Receives new deployments first

[production]
# => Production group: remaining servers
web2.example.com
web3.example.com
web4.example.com
# .. 96 more servers
# => 99% of fleet
# => Only updated after canary succeeds

[webservers:children]
# => Parent group containing all webservers
# => Combines canary + production
canary
production
# => Allows targeting all with 'hosts: webservers'
# => Or specific subsets with conditionals

# blue_green.yml
---
- name: Blue-Green Deployment
 # => Zero-downtime deployment with instant rollback
 hosts: localhost
 # => Run orchestration from control node
 # => No direct host targeting (uses includes)
 vars:
 active_color: "{{ lookup('file', '/etc/active_color.txt') }}"
 # => Read current active environment
 # => lookup('file'..): reads file content into variable
 # => File contains: 'blue' or 'green'
 # => Example: active_color = 'blue'
 inactive_color: "{{ 'green' if active_color == 'blue' else 'blue' }}"
 # => Calculate inactive environment (opposite of active)
 # => Ternary conditional: condition ? true_value : false_value
 # => If active='blue': inactive='green'
 # => If active='green': inactive='blue'

 tasks:
 - name: Deploy to inactive environment
 # => Update inactive env without affecting traffic
 include_tasks: deploy.yml
 # => Separate deploy playbook (reusable)
 vars:
 target_hosts: "{{ inactive_color }}_webservers"
 # => Dynamic host group selection
 # => If inactive='green': target 'green_webservers' group
 # => Example: green_webservers = [green1, green2, green3]

 - name: Run smoke tests
 # => Verify inactive environment before cutover
 uri:
 url: "http://{{ inactive_color }}-lb.example.com/health"
 # => Internal load balancer for inactive env
 # => Example: http://green-lb.example.com/health
 status_code: 200
 # => Expect HTTP 200 OK
 # => Fails deployment if unhealthy
 # => Prevents switching to broken environment

 - name: Switch load balancer
 # => Cutover: redirect traffic to newly deployed env
 uri:
 url: "http://lb.example.com/api/switch"
 # => Production LB API endpoint
 method: POST
 body_format: json
 # => Send JSON payload
 body:
 # => Request body
 active: "{{ inactive_color }}"
 # => Tell LB to make inactive active
 # => Example: switch traffic from blue to green
 # => Atomic operation: instant traffic cutover
 # => Users immediately served by new version

 - name: Update active color file
 # => Persist new active environment state
 copy:
 content: "{{ inactive_color }}"
 # => Write new active color to file
 # => Example: 'green' (was 'blue')
 dest: /etc/active_color.txt
 # => State file for next deployment
 # => Next run: green becomes active, blue becomes inactive

# immutable_deploy.yml
---
- name: Build Golden AMI
 # => Create new machine image with updated code
 hosts: packer_builder
 # => Dedicated host for image building
 # => Isolated from production
 tasks:
 - name: Launch Packer build
 # => Use Packer to build AMI
 command: packer build -var 'version={{ app_version }}' ami-template.json
 # => packer: image building tool
 # => -var: pass variable to template
 # => ami-template.json: defines image configuration
 # => Output: new AMI ID
 register: packer_result
 # => Capture command output
 # => Contains AMI ID in stdout

 - name: Extract AMI ID
 # => Parse AMI ID from Packer output
 set_fact:
 # => Create new fact variable
 new_ami: "{{ packer_result.stdout | regex_search('ami-[a-z0-9]+') }}"
 # => regex_search: extract text matching pattern
 # => Pattern: 'ami-' followed by alphanumeric chars
 # => Example: stdout contains "AMI: ami-0abc123def456"
 # => new_ami = 'ami-0abc123def456'

- name: Deploy New Auto Scaling Group
 # => Replace instances with new AMI
 hosts: localhost
 # => Execute AWS API calls from control node
 tasks:
 - name: Create launch configuration
 # => Define instance launch parameters
 ec2_lc:
 # => EC2 Launch Configuration module
 name: "myapp-{{ app_version }}"
 # => Unique name per version
 # => Example: myapp-v2.5.0
 image_id: "{{ new_ami }}"
 # => Use newly built AMI
 # => Contains updated application code
 instance_type: t3.medium
 # => EC2 instance size
 security_groups: ["sg-123456"]
 # => Firewall rules for instances
 # => Creates immutable launch config
 # => Cannot modify, only create new and switch

 - name: Update Auto Scaling Group
 # => Switch ASG to new launch configuration
 ec2_asg:
 # => EC2 Auto Scaling Group module
 name: myapp-asg
 # => Target ASG name
 launch_config_name: "myapp-{{ app_version }}"
 # => Reference new launch config
 # => ASG will launch instances using new AMI
 min_size: 3
 # => Minimum instances running
 max_size: 6
 # => Maximum instances for scaling
 desired_capacity: 3
 # => Current target instance count
 # => Triggers instance replacement
 # => ASG terminates old instances, launches new ones
 # => Gradual replacement based on ASG health checks

 - name: Wait for new instances healthy
 # => Verify new instances operational
 ec2_instance_facts:
 # => Query EC2 instance information
 filters:
 # => Filter criteria for instances
 "tag:Version": "{{ app_version }}"
 # => Only instances tagged with new version
 "instance-state-name": running
 # => Only running instances
 register: instances
 # => Store query results
 until: instances.instances | length == 3
 # => Retry until 3 instances found
 # => Matches desired_capacity
 retries: 20
 # => Retry up to 20 times
 delay: 30
 # => Wait 30 seconds between retries
 # => Total max wait: 10 minutes
 # => Ensures replacement completed successfully

# zero_downtime.yml
---
- name: Zero-Downtime Deployment
 # => Production-grade deployment pattern
 hosts: webservers
 # => All web servers
 serial: 1
 # => One host at a time (safest)
 # => Ensures N-1 hosts always serving traffic
 max_fail_percentage: 0
 # => Abort on any failure
 # => Zero tolerance for deployment errors

 tasks:
 - name: Pre-deployment health check
 # => Verify host healthy before starting update
 uri:
 url: "http://{{ inventory_hostname }}:8080/health"
 # => Application health endpoint
 # => Direct host query (bypass LB)
 status_code: 200
 # => Expect healthy response
 # => Catches pre-existing issues
 # => Don't attempt update on unhealthy host

 - name: Disable host in load balancer
 # => Remove host from active pool
 haproxy:
 # => HAProxy load balancer module
 backend: web_backend
 # => Backend pool name in HAProxy config
 host: "{{ inventory_hostname }}"
 # => Target host to disable
 state: disabled
 # => Mark as maintenance mode
 # => LB stops routing new requests
 socket: /run/haproxy/admin.sock
 # => Unix socket for HAProxy admin commands
 delegate_to: lb.example.com
 # => Execute on load balancer server
 # => Not on web server being updated

 - name: Wait for connections to drain
 # => Allow active requests to complete
 wait_for:
 # => Wait module (time-based)
 timeout: 30
 # => Wait 30 seconds
 # => Typical max request duration: 10-20s
 # => Buffer for long-running requests
 # => Prevents killing active user sessions
 # => Graceful connection draining

 - name: Deploy application
 # => Update application artifact
 copy:
 src: "myapp-{{ version }}.jar"
 # => New version from control node
 dest: /opt/myapp/app.jar
 # => Overwrite existing version
 notify: Restart application
 # => Trigger service restart handler

 - name: Flush handlers now
 # => Execute handlers immediately
 meta: flush_handlers
 # => Normally handlers run at play end
 # => flush_handlers: run now
 # => Ensures restart completes before health check
 # => Required for proper health verification

 - name: Wait for application startup
 # => Wait for app to bind network port
 wait_for:
 # => Wait for port availability
 port: 8080
 # => Application listen port
 delay: 5
 # => Wait 5 seconds before first check
 # => Allows JVM startup
 timeout: 120
 # => Max wait: 2 minutes
 # => Fail if app doesn't start
 # => Ensures app process running and listening

 - name: Application health check
 # => Verify application functional
 uri:
 url: "http://{{ inventory_hostname }}:8080/health"
 # => Direct health endpoint query
 status_code: 200
 # => Expect healthy response
 retries: 12
 # => Retry up to 12 times
 delay: 5
 # => Wait 5 seconds between retries
 # => Total max wait: 60 seconds
 # => Allows app warmup (DB connections, cache)

 - name: Enable host in load balancer
 # => Return host to active pool
 haproxy:
 backend: web_backend
 host: "{{ inventory_hostname }}"
 state: enabled
 # => Mark as active
 # => LB starts routing requests
 socket: /run/haproxy/admin.sock
 delegate_to: lb.example.com
 # => Execute on LB server

 - name: Wait for host to receive traffic
 # => Allow LB health checks to pass
 pause:
 seconds: 10
 # => Wait 10 seconds
 # => LB health check interval: typically 5s
 # => Ensures LB marks host healthy
 # => Prevents race condition:
 # => host enabled but LB hasn't verified health

 handlers:
 # => Executed when notified by tasks
 - name: Restart application
 # => Restart application service
 service:
 name: myapp
 # => Systemd service name
 state: restarted
 # => Stop then start service
 # => Loads new application code

# monitored_deploy.yml
---
- name: Deployment with Monitoring
 # => Observable deployment with external integrations
 # => Integrates Slack and DataDog for deployment visibility
 hosts: webservers
 # => Target servers for deployment
 tasks:
 - name: Send deployment start notification
 # => Notify team in real-time via Slack
 # => Alerts on-call engineers of deployment start
 uri:
 # => HTTP module for API calls
 url: "{{ slack_webhook_url }}"
 # => Slack incoming webhook URL
 # => Configured in Slack workspace settings
 # => Variable should come from vault or vars
 method: POST
 # => POST request to webhook
 # => Webhook expects POST, not GET
 body_format: json
 # => Send JSON payload
 # => Required format for Slack webhooks
 body:
 # => Slack message payload
 # => JSON structure per Slack API spec
 text: "Starting deployment of {{ app_version }} to {{ inventory_hostname }}"
 # => Message text for Slack channel
 # => Example: "Starting deployment of v2.5.0 to web1"
 # => Variables interpolated at runtime
 delegate_to: localhost
 # => Execute webhook call from control node
 # => Not from target server (control node has internet access)
 # => Reduces network dependency on target hosts

 - name: Create deployment marker in DataDog
 # => Create event annotation in monitoring dashboard
 # => Visible as vertical line on DataDog graphs
 uri:
 # => HTTP module for DataDog API
 url: "https://api.datadoghq.com/api/v1/events"
 # => DataDog Events API endpoint
 # => Public API endpoint (authentication via header)
 method: POST
 # => POST creates new event
 headers:
 # => API authentication headers
 # => Required for DataDog API access
 DD-API-KEY: "{{ datadog_api_key }}"
 # => DataDog API key from vault/vars
 # => Secret credential (use Ansible Vault)
 body_format: json
 # => JSON request body
 body:
 # => Event data payload
 # => Structured data for DataDog event
 title: "Deployment Started"
 # => Event title in DataDog
 # => Appears in event stream
 text: "{{ app_version }} deploying to {{ inventory_hostname }}"
 # => Event description
 # => Provides deployment context
 tags:
 # => Event tags for filtering
 # => Enable filtering in DataDog dashboards
 - "environment:production"
 # => Tag: environment name
 # => Filter: environment:production
 - "version:{{ app_version }}"
 # => Tag: deployed version
 # => Filter deployments by version
 delegate_to: localhost
 # => Creates vertical line on graphs at deployment time
 # => Correlate deployment with metric changes
 # => Correlates metric changes with deployments

 - name: Deploy application
 # => Actual deployment task
 copy:
 src: "app-{{ app_version }}.jar"
 dest: /opt/myapp/app.jar
 notify: Restart application

 - name: Check error rate post-deployment
 # => Validate deployment didn't increase errors
 uri:
 url: "{{ metrics_api }}/error_rate?host={{ inventory_hostname }}"
 # => Query metrics API for error rate
 # => Host-specific query
 return_content: yes
 # => Return response body
 register: error_rate
 # => Store API response
 # => Example: { "value": 2.3, "unit": "percent" }
 delegate_to: localhost

 - name: Trigger alert if error rate high
 # => Automated incident creation on anomaly
 uri:
 url: "{{ pagerduty_events_url }}"
 # => PagerDuty Events API v2
 method: POST
 body_format: json
 body:
 # => PagerDuty incident payload
 routing_key: "{{ pagerduty_key }}"
 # => Integration key from PagerDuty service
 event_action: trigger
 # => Action: create new incident
 # => Alternatives: acknowledge, resolve
 payload:
 # => Incident details
 summary: "High error rate after deployment"
 # => Incident title
 severity: critical
 # => Urgency level
 # => Routes to on-call engineer
 when: error_rate.json.value > 5.0
 # => Conditional: only if error rate exceeds threshold
 # => 5.0 = 5% error rate
 # => Triggers immediate response
 delegate_to: localhost

# disaster_recovery.yml
---
- name: Disaster Recovery Procedure
 # => Automated DR orchestration
 hosts: localhost
 # => Run from control node (primary site may be down)
 vars:
 backup_date: "{{ lookup('pipe', 'date +%Y-%m-%d') }}"
 # => Get current date for backup selection
 # => lookup('pipe'..): execute shell command, return output
 # => Example: backup_date = '2025-12-29'

 tasks:
 - name: Provision new infrastructure
 # => Recreate servers in DR location
 include_role:
 # => Execute provisioning role
 name: provision_infrastructure
 # => Role that creates VMs/cloud resources
 vars:
 environment: dr_recovery
 # => Variable for role: target DR environment
 # => Uses DR region, networks, configurations

 - name: Restore database from backup
 # => Restore DB from S3-stored backup
 postgresql_db:
 # => PostgreSQL database module
 name: myapp
 # => Database name to restore
 state: restore
 # => Restore mode (vs dump/present/absent)
 target: "s3://backups/db-{{ backup_date }}.dump"
 # => S3 URL of backup file
 # => Example: s3://backups/db-2025-12-29.dump
 # => Uses AWS credentials from environment
 # => Restores full database schema and data

 - name: Restore application files
 # => Download application backup from S3
 aws_s3:
 # => AWS S3 module
 bucket: backups
 # => S3 bucket name
 object: "app-{{ backup_date }}.tar.gz"
 # => S3 object key (file path)
 dest: /tmp/app-restore.tar.gz
 # => Local destination path
 mode: get
 # => Download mode (vs put/delobj)
 # => Downloads compressed app backup

 - name: Extract application
 # => Uncompress application files
 unarchive:
 # => Archive extraction module
 src: /tmp/app-restore.tar.gz
 # => Source archive path
 dest: /opt/myapp
 # => Extraction destination
 remote_src: yes
 # => Source file on remote host (vs control node)
 # => Extracts all application files to deployment directory

 - name: Verify data integrity
 # => Validate restored data not corrupted
 command: /opt/myapp/bin/verify-data.sh
 # => Custom verification script
 # => Checks: DB row counts, checksums, referential integrity
 register: integrity_check
 # => Capture script output
 failed_when: "'PASS' not in integrity_check.stdout"
 # => Fail task if verification fails
 # => Script must output 'PASS' for success
 # => Prevents activating corrupted DR site

 - name: Update DNS to DR site
 # => Cutover: redirect traffic to DR environment
 route53:
 # => AWS Route53 DNS module
 state: present
 # => Create/update DNS record
 zone: example.com
 # => DNS zone (domain)
 record: app.example.com
 # => DNS record name (subdomain)
 type: A
 # => Record type: A (IPv4 address)
 value: "{{ dr_lb_ip }}"
 # => New IP: DR load balancer
 # => Changes: prod_lb_ip → dr_lb_ip
 ttl: 60
 # => Time to live: 60 seconds
 # => Short TTL for faster failback
 # => DNS propagation: 1-5 minutes
 # => Traffic redirects to DR site

 - name: Send recovery notification
 # => Notify team DR completed
 uri:
 url: "{{ slack_webhook_url }}"
 method: POST
 body:
 text: "DR completed. Services running at DR site."
 # => Slack notification message
 # => Alerts team to monitor DR site

# drift_detection.yml
---
- name: Detect Configuration Drift
 # => Continuous compliance monitoring
 # => Runs periodically (cron/scheduler) to detect unauthorized changes
 hosts: production
 # => All production servers
 # => Scans entire production fleet for drift
 check_mode: yes
 # => Don't make changes, only check
 # => Simulates changes, reports what would happen
 # => Safe for production runs (no state modification)
 diff: yes
 # => Show differences between desired and actual
 # => Displays file content changes in output
 # => Useful for debugging configuration mismatches
 tasks:
 - name: Check nginx configuration
 # => Verify nginx config matches template
 # => Detects manual edits or unauthorized changes
 template:
 # => Template module (normally writes file)
 # => In check mode: compares without writing
 src: nginx.conf.j2
 # => Jinja2 template: desired configuration
 # => Source of truth for nginx config
 dest: /etc/nginx/nginx.conf
 # => Target file path on production server
 register: nginx_drift
 # => Capture result into variable
 # => In check mode: .changed=True if file differs
 # => Actual file NOT modified (check mode active)

 - name: Check service state
 # => Verify service running and enabled
 # => Ensures service hasn't been stopped or disabled
 service:
 name: nginx
 # => Service name (systemd unit)
 state: started
 # => Expected: running
 # => Drift if service stopped
 enabled: yes
 # => Expected: start on boot
 # => Drift if disabled
 register: service_drift
 # => .changed=True if service stopped or disabled
 # => Alert ops team if drift detected

 - name: Check package versions
 # => Verify specific package versions installed
 # => Detects version drift or unauthorized upgrades
 package:
 name:
 # => List of packages with version constraints
 # => Version pins prevent unexpected upgrades
 - nginx=1.18*
 # => Nginx version 1.18.x
 # => * = any patch version (1.18.0, 1.18.1, etc.)
 # => Drift if 1.19+ installed
 - postgresql=14*
 # => PostgreSQL version 14.x
 state: present
 # => Must be installed
 register: package_drift
 # => .changed=True if wrong version or missing

 - name: Collect drift report
 # => Aggregate drift findings
 set_fact:
 # => Create summary variable
 drift_detected: >-
 {{
 nginx_drift.changed or
 service_drift.changed or
 package_drift.changed
 }}
 # => Boolean: True if ANY check reported changes
 # => Multi-line YAML: >- (fold, strip trailing newlines)

 - name: Alert on drift
 # => Send webhook notification if drift found
 uri:
 url: "{{ alerting_webhook }}"
 # => Alerting system webhook URL
 method: POST
 body:
 # => Alert payload
 host: "{{ inventory_hostname }}"
 # => Hostname with drift
 drift: "{{ drift_detected }}"
 # => Boolean: drift present
 details:
 # => Breakdown by check
 nginx: "{{ nginx_drift.changed }}"
 # => Config file drift
 service: "{{ service_drift.changed }}"
 # => Service state drift
 packages: "{{ package_drift.changed }}"
 # => Package version drift
 when: drift_detected
 # => Only send alert if drift detected
 # => No alert spam when compliant
 delegate_to: localhost
 # => Execute webhook from control node

# pipeline_deploy.yml
---
- name: Deploy to Development
 # => Stage 1: Development environment
 # => First deployment stage (lowest risk)
 hosts: dev_webservers
 # => Dev servers (isolated environment)
 # => No production traffic
 vars_files:
 # => Load environment-specific variables
 # => Different config per environment
 - vars/dev.yml
 # => Development config: dev DB, debug enabled, etc.
 # => Overrides role defaults with dev-specific values
 tasks:
 - include_tasks: deploy_tasks.yml
 # => Reusable deployment tasks
 # => Same tasks for all environments
 # => Variables differ per environment
 # => DRY principle: single task definition

- name: Run Integration Tests
 # => Validate deployment on dev
 # => Quality gate before promoting to staging
 hosts: dev_webservers
 # => Run tests on newly deployed dev environment
 tasks:
 - name: Execute test suite
 # => Run automated tests
 # => Validates application functionality
 command: /opt/tests/run-integration-tests.sh
 # => Test script: API tests, DB queries, etc.
 # => Exit code 0 = success, non-zero = failure
 register: tests
 # => Capture test results
 # => Result stored in 'tests' variable
 failed_when: tests.rc != 0
 # => Fail pipeline if tests fail
 # => rc: return code (0=success, non-zero=failure)
 # => Blocks progression to staging
 # => Pipeline stops here if tests fail

- name: Deploy to Staging
 # => Stage 2: Staging environment (only if dev tests pass)
 # => Production-like environment for final validation
 hosts: staging_webservers
 # => Staging servers (production-like)
 # => Same OS, packages, config as production
 vars_files:
 - vars/staging.yml
 # => Staging config: staging DB, prod-like settings
 # => Mirrors production configuration
 tasks:
 - include_tasks: deploy_tasks.yml
 # => Same deployment tasks, different vars
 # => Reuses deploy_tasks.yml with staging variables

- name: Staging Smoke Tests
 # => Quick validation on staging
 # => Lightweight tests for rapid feedback
 hosts: staging_webservers
 # => Test newly deployed staging environment
 tasks:
 - name: Check critical endpoints
 # => Test key application functions
 # => Ensure core features responsive
 uri:
 url: "http://{{ inventory_hostname }}/{{ item }}"
 # => HTTP health check per endpoint
 # => Test URL per host
 status_code: 200
 # => Expect successful response
 loop:
 # => Test multiple endpoints
 - health
 # => Health check endpoint
 - api/users
 # => User API
 - api/orders
 # => Orders API
 # => Verifies core functionality works
 # => Faster than full integration tests

- name: Production Approval Gate
 # => Manual checkpoint before production
 hosts: localhost
 # => Run on control node
 tasks:
 - name: Wait for approval
 # => Pause for human decision
 pause:
 prompt: "Approve production deployment? (Enter to continue)"
 # => Manual approval required
 # => Reviewer checks: staging metrics, logs, test results
 # => Enter: proceed to production
 # => Ctrl-C: abort deployment

- name: Deploy to Production
 # => Stage 3: Production (only after approval)
 hosts: prod_webservers
 # => Production servers
 serial: 3
 # => Rolling update: 3 hosts at a time
 # => Gradual rollout for safety
 vars_files:
 - vars/production.yml
 # => Production config: prod DB, optimizations
 tasks:
 - include_tasks: deploy_tasks.yml
 # => Same deployment tasks, production vars

# vault_integration.yml
---
- name: Dynamic Secrets from Vault
 # => Runtime secret fetching (no stored credentials)
 hosts: webservers
 vars:
 vault_addr: "https://vault.example.com:8200"
 # => HashiCorp Vault server URL
 # => HTTPS required for production
 tasks:
 - name: Get database credentials from Vault
 # => Request dynamic DB credentials
 uri:
 # => HTTP API call to Vault
 url: "{{ vault_addr }}/v1/database/creds/myapp"
 # => Vault API endpoint
 # => /v1/database/creds/{role}: database secrets engine
 # => {role}: 'myapp' (defines DB permissions)
 method: GET
 # => GET request to read credentials
 headers:
 X-Vault-Token: "{{ lookup('env', 'VAULT_TOKEN') }}"
 # => Authentication token
 # => lookup('env'..): read environment variable
 # => VAULT_TOKEN: set in CI/CD environment
 return_content: yes
 # => Return response body
 register: db_creds
 # => Store credentials in variable
 # => Contains: username, password, lease_id, lease_duration
 delegate_to: localhost
 # => Execute API call from control node
 no_log: true
 # => Don't log credentials in output
 # => Security: prevents credential exposure in logs

 - name: Configure application with Vault credentials
 # => Write config file with dynamic credentials
 template:
 src: app-config.j2
 # => Template with credential placeholders
 dest: /opt/myapp/config.yml
 # => Application config file
 mode: "0600"
 # => Restrictive permissions: owner read/write only
 # => Prevents other users reading credentials
 vars:
 # => Variables for template
 db_username: "{{ db_creds.json.data.username }}"
 # => Extract username from Vault response
 # => Example: v-token-myapp-AbC123
 db_password: "{{ db_creds.json.data.password }}"
 # => Extract password from Vault response
 # => Example: randomly generated 32-char string
 no_log: true
 # => Don't log task with credentials

 - name: Revoke credentials on failure
 # => Cleanup credentials if deployment fails
 uri:
 url: "{{ vault_addr }}/v1/sys/leases/revoke"
 # => Vault lease revocation endpoint
 method: PUT
 # => PUT request to revoke
 headers:
 X-Vault-Token: "{{ lookup('env', 'VAULT_TOKEN') }}"
 body:
 # => Revocation request payload
 lease_id: "{{ db_creds.json.lease_id }}"
 # => Lease ID from credential response
 # => Identifies credential to revoke
 delegate_to: localhost
 when: ansible_failed_task is defined
 # => Only run if previous task failed
 # => ansible_failed_task: set when failure occurs
 # => Prevents orphaned credentials