ansible-project/
├── ansible.cfg              # Ansible configuration
├── inventory/               # Inventory files
│   ├── production/
│   │   ├── hosts           # Production inventory
│   │   └── group_vars/
│   │       └── all.yml
│   └── staging/
│       ├── hosts           # Staging inventory
│       └── group_vars/
│           └── all.yml
├── group_vars/             # Group-specific variables
│   ├── all.yml
│   ├── webservers.yml
│   └── databases.yml
├── host_vars/              # Host-specific variables
│   └── server1.yml
├── roles/                  # Reusable roles
│   ├── common/
│   ├── webserver/
│   └── database/
├── playbooks/              # Playbooks
│   ├── site.yml           # Master playbook
│   ├── webservers.yml
│   └── databases.yml
├── files/                  # Static files
├── templates/              # Jinja2 templates
├── vars/                   # Additional variables
│   └── external_vars.yml
└── requirements.yml        # Collection dependencies

roles/webserver/
├── README.md              # Role documentation
├── defaults/
│   └── main.yml          # Default variables (lowest precedence)
├── vars/
│   └── main.yml          # Role variables (higher precedence)
├── tasks/
│   ├── main.yml          # Main task list
│   ├── install.yml       # Installation tasks
│   └── configure.yml     # Configuration tasks
├── handlers/
│   └── main.yml          # Handlers
├── templates/
│   └── nginx.conf.j2     # Template files
├── files/
│   └── index.html        # Static files
├── meta/
│   └── main.yml          # Role metadata and dependencies
└── molecule/             # Molecule test scenarios
    └── default/
        ├── molecule.yml
        ├── converge.yml
        └── verify.yml

# Descriptive, action-oriented names
- name: Install nginx web server
  apt:
    name: nginx
    state: present

- name: Configure nginx virtual host for example.com
  template:
    src: vhost.conf.j2
    dest: /etc/nginx/sites-available/example.com

- name: Enable and start nginx service
  systemd:
    name: nginx
    state: started
    enabled: yes

- name: Create application user with limited privileges
  user:
    name: appuser
    system: yes
    shell: /bin/false
    home: /var/lib/app

# Vague, uninformative names
- name: Install package
  apt:
    name: nginx

- name: Configure
  template:
    src: vhost.conf.j2
    dest: /etc/nginx/sites-available/example.com

- name: Service
  systemd:
    name: nginx
    state: started

# No name at all
- apt:
    name: nginx

# ✅ Good - Descriptive, namespaced
nginx_version: "1.18.0"
nginx_worker_processes: 4
nginx_worker_connections: 1024
app_database_host: "db.example.com"
app_database_port: 5432

# ❌ Bad - Generic, collision-prone
version: "1.18.0"  # Too generic
workers: 4         # Unclear
db: "db.example.com"  # Vague

# defaults/main.yml - Intended to be overridden
---
nginx_port: 80
nginx_user: www-data
nginx_worker_processes: "auto"

# vars/main.yml - Should not be overridden
---
nginx_config_dir: /etc/nginx
nginx_log_dir: /var/log/nginx
nginx_pid_file: /run/nginx.pid

# Use default filter for optional variables
- name: Set API endpoint
  set_fact:
    api_endpoint: "{{ custom_api_endpoint | default('https://api.example.com') }}"

# Use required filter for mandatory variables
- name: Configure database
  template:
    src: db.conf.j2
    dest: /etc/app/database.conf
  vars:
    db_password: "{{ database_password | required('database_password must be defined') }}"

# File module - inherently idempotent
- name: Ensure configuration directory exists
  file:
    path: /etc/myapp
    state: directory
    mode: '0755'

# Template module - only changes if content differs
- name: Configure application
  template:
    src: app.conf.j2
    dest: /etc/myapp/app.conf
    mode: '0644'

# Package module - idempotent
- name: Install required packages
  apt:
    name:
      - nginx
      - python3
      - git
    state: present

# Service module - idempotent
- name: Ensure service is running
  systemd:
    name: myapp
    state: started
    enabled: yes

# Command/shell without creates/removes
- name: Download file
  command: curl -o /tmp/file.tar.gz https://example.com/file.tar.gz
  # This runs every time!

# Fix with creates
- name: Download file
  command: curl -o /tmp/file.tar.gz https://example.com/file.tar.gz
  args:
    creates: /tmp/file.tar.gz

# Or better - use get_url module
- name: Download file
  get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    checksum: sha256:abc123...

# Command that always reports changed
- name: Check service status
  command: systemctl status myapp
  register: service_status
  # Always shows as changed!

# Fix with changed_when
- name: Check service status
  command: systemctl status myapp
  register: service_status
  changed_when: false
  failed_when: service_status.rc not in [0, 3]

# ❌ Bad - Using shell/command
- name: Create directory
  shell: mkdir -p /opt/myapp

- name: Install package
  command: apt-get install -y nginx

- name: Add line to file
  shell: echo "export PATH=$PATH:/opt/bin" >> ~/.bashrc

# ✅ Good - Using appropriate modules
- name: Create directory
  file:
    path: /opt/myapp
    state: directory
    mode: '0755'

- name: Install package
  apt:
    name: nginx
    state: present

- name: Add line to file
  lineinfile:
    path: ~/.bashrc
    line: 'export PATH=$PATH:/opt/bin'
    create: yes

- name: Handle errors gracefully
  block:
    - name: Attempt risky operation
      command: /usr/local/bin/risky-operation.sh
      register: result

    - name: Process successful result
      debug:
        msg: "Operation succeeded: {{ result.stdout }}"

  rescue:
    - name: Handle failure
      debug:
        msg: "Operation failed, applying fallback"

    - name: Apply fallback configuration
      copy:
        src: fallback.conf
        dest: /etc/app/config.conf

  always:
    - name: Cleanup temporary files
      file:
        path: /tmp/operation.lock
        state: absent

# Custom failure conditions
- name: Check disk space
  shell: df -h / | tail -1 | awk '{print $5}' | sed 's/%//'
  register: disk_usage
  failed_when: disk_usage.stdout | int > 90

# Custom changed conditions
- name: Verify configuration
  command: /usr/local/bin/check-config.sh
  register: config_check
  changed_when: false
  failed_when: config_check.rc != 0

# Multiple conditions
- name: Run healthcheck
  uri:
    url: http://localhost:8080/health
    method: GET
  register: health
  failed_when:
    - health.status != 200
    - "'healthy' not in health.json.status"

# Only when failure is acceptable
- name: Try to stop service (may not exist)
  systemd:
    name: old-service
    state: stopped
  ignore_errors: yes

# Better approach - check first
- name: Check if service exists
  systemd:
    name: old-service
  register: service_status
  failed_when: false

- name: Stop service if it exists
  systemd:
    name: old-service
    state: stopped
  when: service_status.status.ActiveState is defined

# Simple condition
- name: Install Apache (Debian)
  apt:
    name: apache2
    state: present
  when: ansible_os_family == "Debian"

# Multiple conditions (AND)
- name: Install package on Ubuntu 20.04
  apt:
    name: package
    state: present
  when:
    - ansible_distribution == "Ubuntu"
    - ansible_distribution_version == "20.04"

# OR conditions
- name: Install on RHEL or CentOS
  yum:
    name: package
    state: present
  when: ansible_distribution == "RedHat" or ansible_distribution == "CentOS"

# Complex conditions
- name: Configure firewall
  ufw:
    rule: allow
    port: '443'
  when:
    - ansible_os_family == "Debian"
    - firewall_enabled | default(true) | bool
    - ansible_virtualization_type != "docker"

# Simple loop
- name: Install packages
  apt:
    name: "{{ item }}"
    state: present
  loop:
    - nginx
    - python3
    - git

# Loop with hash
- name: Create users
  user:
    name: "{{ item.name }}"
    groups: "{{ item.groups }}"
    state: present
  loop:
    - { name: 'alice', groups: 'developers' }
    - { name: 'bob', groups: 'operators' }

# Loop with dict
- name: Create directories
  file:
    path: "{{ item.path }}"
    state: directory
    mode: "{{ item.mode }}"
  loop:
    - { path: '/opt/app', mode: '0755' }
    - { path: '/var/log/app', mode: '0755' }
    - { path: '/etc/app', mode: '0750' }

# Loop with conditional
- name: Install debug tools (dev only)
  apt:
    name: "{{ item }}"
    state: present
  loop:
    - strace
    - tcpdump
    - gdb
  when: environment == "development"

{# templates/nginx.conf.j2 #}

{# Use comments to explain complex logic #}
user {{ nginx_user }};
worker_processes {{ nginx_worker_processes }};
pid {{ nginx_pid_file }};

{# Conditionals in templates #}
{% if nginx_enable_ssl %}
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers HIGH:!aNULL:!MD5;
{% endif %}

{# Loops in templates #}
{% for vhost in nginx_vhosts %}
server {
    listen {{ vhost.port }};
    server_name {{ vhost.server_name }};
    root {{ vhost.document_root }};

    {% if vhost.ssl_enabled | default(false) %}
    ssl_certificate {{ vhost.ssl_cert }};
    ssl_certificate_key {{ vhost.ssl_key }};
    {% endif %}
}
{% endfor %}

{# Filters #}
upstream_servers = {{ backend_servers | join(',') }}
max_connections = {{ max_connections | default(1024) }}

# String manipulation
- debug:
    msg: "{{ 'hello' | upper }}"  # HELLO
    msg: "{{ 'HELLO' | lower }}"  # hello
    msg: "{{ '  hello  ' | trim }}"  # hello

# List operations
- debug:
    msg: "{{ [1,2,3] | first }}"  # 1
    msg: "{{ [1,2,3] | last }}"  # 3
    msg: "{{ [1,2,3] | length }}"  # 3
    msg: "{{ [1,2,3] | join(',') }}"  # 1,2,3

# Default values
- debug:
    msg: "{{ undefined_var | default('default_value') }}"

# Type conversion
- debug:
    msg: "{{ '123' | int }}"  # 123
    msg: "{{ 'true' | bool }}"  # True

# JSON and YAML
- debug:
    msg: "{{ my_dict | to_json }}"
    msg: "{{ my_dict | to_nice_json }}"
    msg: "{{ my_dict | to_yaml }}"

---
- name: Configure web server
  hosts: webservers
  tasks:
    - name: Install nginx
      apt:
        name: nginx
      tags:
        - packages
        - nginx

    - name: Configure nginx
      template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
      tags:
        - configuration
        - nginx

    - name: Start nginx
      systemd:
        name: nginx
        state: started
      tags:
        - services
        - nginx

    - name: Configure firewall
      ufw:
        rule: allow
        port: '80'
      tags:
        - security
        - firewall

# Run only nginx tasks
ansible-playbook site.yml --tags nginx

# Run configuration tasks only
ansible-playbook site.yml --tags configuration

# Skip certain tags
ansible-playbook site.yml --skip-tags packages

# Multiple tags
ansible-playbook site.yml --tags "nginx,firewall"

# tasks/main.yml
- name: Configure nginx
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify:
    - Validate nginx configuration
    - Restart nginx

- name: Add virtual host
  template:
    src: vhost.conf.j2
    dest: "/etc/nginx/sites-available/{{ vhost_name }}"
  notify:
    - Reload nginx

# handlers/main.yml
- name: Validate nginx configuration
  command: nginx -t
  changed_when: false

- name: Restart nginx
  systemd:
    name: nginx
    state: restarted

- name: Reload nginx
  systemd:
    name: nginx
    state: reloaded

# Task that supports check mode naturally (file module)
- name: Create directory
  file:
    path: /opt/myapp
    state: directory

# Task that doesn't support check mode, but can run anyway
- name: Check service status
  command: systemctl status myapp
  check_mode: no  # Always run, even in check mode
  changed_when: false

# Task that should be skipped in check mode
- name: Apply complex changes
  command: /usr/local/bin/complex-script.sh
  when: not ansible_check_mode

# Run in check mode (dry-run)
ansible-playbook site.yml --check

# Check mode with diff (show changes)
ansible-playbook site.yml --check --diff

# See what would change
ansible-playbook site.yml --check --diff | grep -A 10 "changed:"

---
# site.yml - Master playbook for deploying web application
#
# This playbook:
#   - Configures common settings on all hosts
#   - Deploys web servers
#   - Configures databases
#   - Sets up load balancers
#
# Usage:
#   ansible-playbook -i inventory/production site.yml
#
# Tags:
#   - common: Common configuration tasks
#   - webserver: Web server setup
#   - database: Database configuration
#
# Variables (see group_vars/all.yml):
#   - app_version: Application version to deploy
#   - environment: Environment name (production/staging)

- name: Configure common settings
  hosts: all
  roles:
    - common
  tags: common

- name: Deploy web servers
  hosts: webservers
  roles:
    - webserver
  tags: webserver

# Webserver Role

## Description

Installs and configures Nginx web server with virtual hosts and SSL support.

## Requirements

- Ansible >= 2.9
- Supported OS: Ubuntu 20.04, Debian 11

## Role Variables

### Required Variables

- `nginx_vhosts`: List of virtual hosts to configure (see example)

### Optional Variables

- `nginx_worker_processes`: Number of worker processes (default: auto)
- `nginx_worker_connections`: Max connections per worker (default: 1024)
- `nginx_enable_ssl`: Enable SSL support (default: false)

## Dependencies

None

## Example Playbook

```yaml
- hosts: webservers
  roles:
    - role: webserver
      vars:
        nginx_vhosts:
          - server_name: example.com
            port: 80
            document_root: /var/www/example

## Testing Best Practices

See the molecule configuration and testing section in the main skill.md for comprehensive testing guidance.

## Performance Tips

1. **Use pipelining** in ansible.cfg
   ```ini
   [ssh_connection]
   pipelining = True

Common Ansible Errors and Solutions

Overview

This document provides solutions to common Ansible errors, including syntax errors, module errors, connection issues, and runtime problems.

Syntax Errors

Error: mapping values are not allowed here

ERROR! Syntax Error while loading YAML.
  mapping values are not allowed here

Cause: YAML indentation error or missing quote

Example Problem:

- name: Configure app
  template:
    src: config.j2
    dest: /etc/app/config.yml
    vars:
      db_host: localhost:5432  # WRONG: colon not quoted

Solution:

- name: Configure app
  template:
    src: config.j2
    dest: /etc/app/config.yml
    vars:
      db_host: "localhost:5432"  # Quoted

Error: found undefined alias

ERROR! Syntax Error while loading YAML.
  found undefined alias 'anchor'

Cause: Using YAML anchor/alias incorrectly

Solution: Ensure anchors are defined before use

# Define anchor
common_packages: &common_packages
  - git
  - curl
  - vim

# Use alias
- name: Install common packages
  apt:
    name: *common_packages

Error: could not find expected ‘:’

ERROR! could not find expected ':'

Cause: Missing colon or improper YAML structure

Example Problem:

- name Install package  # Missing colon after name
  apt:
    name nginx  # Missing colon after name

Solution:

- name: Install package
  apt:
    name: nginx

Module Errors

Error: Unsupported parameters for module

ERROR! Unsupported parameters for (module) module: parameter_name

Cause: Using wrong parameter name or typo

Example Problem:

- name: Create file
  file:
    path: /tmp/test
    state: present
    mod: '0644'  # WRONG: should be 'mode'

Solution:

- name: Create file
  file:
    path: /tmp/test
    state: present
    mode: '0644'  # Correct parameter name

How to check: Use ansible-doc module_name to see correct parameters

Error: MODULE FAILURE

fatal: [host]: FAILED! => {"changed": false, "module_stderr": "..."}

Common Causes:

1. Python not installed on target
2. Wrong Python interpreter
3. SELinux blocking module execution

Solutions:

# Specify Python interpreter in inventory
[webservers]
server1 ansible_python_interpreter=/usr/bin/python3

# Or in playbook
- hosts: all
  vars:
    ansible_python_interpreter: /usr/bin/python3

Error: Missing required arguments

fatal: [host]: FAILED! => {"changed": false, "msg": "missing required arguments: name"}

Cause: Required module parameter not provided

Solution: Add the required parameter

# Wrong
- name: Install package
  apt:
    state: present

# Correct
- name: Install package
  apt:
    name: nginx
    state: present

Template Errors

Error: template error while templating string

fatal: [host]: FAILED! => {"msg": "An unhandled exception occurred while templating..."}

Common Causes:

1. Undefined variable
2. Wrong filter syntax
3. Jinja2 syntax error

Example Problem:

- name: Configure app
  template:
    src: config.j2
    dest: /etc/app/config.yml
  vars:
    port: "{{ app_port }}"  # app_port undefined

Solutions:

# Use default filter
vars:
  port: "{{ app_port | default(8080) }}"

# Or use required filter
vars:
  port: "{{ app_port | required('app_port must be defined') }}"

# Or check if defined
- name: Configure app
  template:
    src: config.j2
    dest: /etc/app/config.yml
  when: app_port is defined

Error: Unexpected templating type error

fatal: [host]: FAILED! => {"msg": "Unexpected templating type error occurred on (...)"}

Cause: Wrong variable type (e.g., trying to use int as string)

Solution: Use type conversion filters

# Convert to string
port: "{{ app_port | string }}"

# Convert to int
replicas: "{{ replica_count | int }}"

# Convert to bool
enabled: "{{ feature_enabled | bool }}"

Connection Errors

Error: Failed to connect to the host via ssh

fatal: [host]: UNREACHABLE! => {"msg": "Failed to connect to the host via ssh"}

Common Causes:

1. Host not accessible
2. Wrong SSH key
3. Wrong username
4. SSH not running on host

Solutions:

# Test SSH connectivity
ssh user@host

# Check Ansible can ping
ansible host -m ping

# Use correct SSH key
ansible-playbook -i inventory playbook.yml --private-key=~/.ssh/id_rsa

# Specify user in inventory
[webservers]
server1 ansible_user=ubuntu ansible_ssh_private_key_file=~/.ssh/id_rsa

Error: Permission denied (publickey)

fatal: [host]: UNREACHABLE! => {"msg": "Failed to connect to the host via ssh: Permission denied (publickey)."}

Solutions:

# Ensure SSH key is added to target
ssh-copy-id user@host

# Or specify key in inventory
[webservers]
server1 ansible_ssh_private_key_file=~/.ssh/custom_key

# Check SSH agent
ssh-add -l
ssh-add ~/.ssh/id_rsa

Error: Authentication or permission failure

fatal: [host]: UNREACHABLE! => {"msg": "Authentication or permission failure."}

Solutions:

# Use password authentication (less secure)
- hosts: all
  vars:
    ansible_ssh_pass: password  # Better to use vault
    ansible_become_pass: password

# Or use ask-pass
ansible-playbook -i inventory playbook.yml --ask-pass --ask-become-pass

Privilege Escalation Errors

Error: Missing sudo password

fatal: [host]: FAILED! => {"msg": "Missing sudo password"}

Solutions:

# Provide sudo password at runtime
ansible-playbook -i inventory playbook.yml --ask-become-pass

# Or configure passwordless sudo on target
# /etc/sudoers.d/ansible
ansible_user ALL=(ALL) NOPASSWD: ALL

Error: you must be root

fatal: [host]: FAILED! => {"msg": "Could not create file: Permission denied"}

Solution: Add become: yes to task or play

- name: Install package
  apt:
    name: nginx
    state: present
  become: yes

# Or for entire play
- hosts: all
  become: yes
  tasks:
    - name: Install package
      apt:
        name: nginx

Variable Errors

Error: The task includes an option with an undefined variable

fatal: [host]: FAILED! => {"msg": "The task includes an option with an undefined variable. The error was: 'variable' is undefined"}

Solutions:

# Use default filter
- name: Use variable with default
  debug:
    msg: "{{ my_var | default('default_value') }}"

# Check if defined before use
- name: Use variable conditionally
  debug:
    msg: "{{ my_var }}"
  when: my_var is defined

# Use required filter to make it explicit
- name: Require variable
  debug:
    msg: "{{ my_var | required('my_var must be defined') }}"

Error: Conflicting variable name

[WARNING]: Invalid characters were found in group names but not replaced, use -vvvv to see details

Cause: Variable or group name contains invalid characters (hyphens, spaces)

Solution: Use underscores instead

# Wrong
[web-servers]

# Correct
[web_servers]

Inventory Errors

Error: Could not match supplied host pattern

[WARNING]: Could not match supplied host pattern, ignoring: webservers

Cause: Host group not defined in inventory

Solution: Check inventory file

# inventory/hosts
[webservers]
web1.example.com
web2.example.com

[databases]
db1.example.com

Error: Unable to parse inventory

[WARNING]: Unable to parse /path/to/inventory as an inventory source

Cause: Invalid inventory format

Solution: Fix inventory syntax

# Wrong - mixing styles
[webservers]
web1 ansible_host=192.168.1.10
web2
  ansible_host: 192.168.1.11  # YAML syntax in INI file

# Correct - consistent INI format
[webservers]
web1 ansible_host=192.168.1.10
web2 ansible_host=192.168.1.11

Loop Errors

Error: Invalid data passed to ‘loop’

fatal: [host]: FAILED! => {"msg": "Invalid data passed to 'loop', it requires a list"}

Cause: Loop variable is not a list

Solution: Ensure loop variable is a list

# Wrong
- name: Install packages
  apt:
    name: "{{ item }}"
  loop: nginx  # String, not list

# Correct
- name: Install packages
  apt:
    name: "{{ item }}"
  loop:
    - nginx
    - python3

Error: with_items is deprecated

[DEPRECATION WARNING]: with_items is deprecated, use loop instead

Solution: Replace with_items with loop

# Old style (deprecated)
- name: Install packages
  apt:
    name: "{{ item }}"
  with_items:
    - nginx
    - python3

# New style
- name: Install packages
  apt:
    name: "{{ item }}"
  loop:
    - nginx
    - python3

Handler Errors

Error: Handler not found

ERROR! The requested handler 'restart nginx' was not found

Cause: Handler name mismatch or handler not defined

Solution: Ensure handler name matches exactly

# tasks/main.yml
- name: Configure nginx
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: restart nginx  # Must match handler name exactly

# handlers/main.yml
- name: restart nginx  # Must match notification exactly
  systemd:
    name: nginx
    state: restarted

Include/Import Errors

Error: Unable to retrieve file contents

fatal: [host]: FAILED! => {"msg": "Unable to retrieve file contents. Could not find or access 'file.yml'"}

Cause: File path incorrect or file doesn’t exist

Solution: Check file path (relative to playbook location)

# Wrong
- include_tasks: tasks/install.yml  # If tasks/ doesn't exist

# Correct
- include_tasks: install.yml  # File in same directory
# Or
- include_tasks: roles/common/tasks/install.yml  # Full path

Error: Include/Import loop detected

ERROR! Recursively included/imported file is causing infinite loop

Cause: Circular dependency (file A includes file B, file B includes file A)

Solution: Restructure includes to avoid circular dependencies

Collection Errors

Error: couldn’t resolve module/action

ERROR! couldn't resolve module/action 'community.general.docker_container'

Cause: Collection not installed

Solution: Install required collection

# Install single collection
ansible-galaxy collection install community.general

# Install from requirements.yml
# requirements.yml
collections:
  - name: community.general
    version: ">=5.0.0"

ansible-galaxy collection install -r requirements.yml

Error: Collection version conflict

ERROR! Requirement already satisfied by a different version

Solution: Update or downgrade collection

# Force reinstall
ansible-galaxy collection install community.general --force

# Install specific version
ansible-galaxy collection install community.general:5.0.0

Dry-Run / Check Mode Errors

Error: This module does not support check mode

fatal: [host]: FAILED! => {"msg": "This module does not support check mode"}

Cause: Module doesn’t support check mode

Solution: Skip check mode for this task

- name: Command that doesn't support check mode
  command: /usr/local/bin/custom-script.sh
  check_mode: no  # Always run, even in check mode

Debugging Tips

Enable Verbose Output

# Basic verbosity
ansible-playbook playbook.yml -v

# More details
ansible-playbook playbook.yml -vv

# Very verbose (shows module arguments)
ansible-playbook playbook.yml -vvv

# Connection debugging
ansible-playbook playbook.yml -vvvv

Use Debug Module

# Print variable
- name: Debug variable
  debug:
    var: my_variable

# Print message
- name: Debug message
  debug:
    msg: "Value is {{ my_variable }}"

# Print all facts
- name: Print all facts
  debug:
    var: ansible_facts

# Conditional debug
- name: Debug when condition met
  debug:
    msg: "Debug message"
  when: ansible_distribution == "Ubuntu"

Use assert Module

# Validate conditions
- name: Assert variables are defined
  assert:
    that:
      - app_version is defined
      - app_version | length > 0
      - app_port | int > 0
      - app_port | int < 65536
    fail_msg: "Invalid configuration"
    success_msg: "Configuration validated"

Performance Issues

Slow Playbook Execution

Solutions:

1. Enable SSH pipelining

# ansible.cfg
[ssh_connection]
pipelining = True

2. Use fact caching

# ansible.cfg
[defaults]
gathering = smart
fact_caching = jsonfile
fact_caching_connection = /tmp/ansible_facts
fact_caching_timeout = 86400

3. Disable fact gathering if not needed

- hosts: all
  gather_facts: no

4. Use async for long tasks

- name: Long running task
  command: /usr/bin/long-task
  async: 3600
  poll: 0

High Memory Usage

Solutions:

1. Process hosts in batches

- hosts: all
  serial: 10  # Process 10 hosts at a time

2. Use free strategy

- hosts: all
  strategy: free  # Don't wait for all hosts to complete task

Error Prevention Checklist

• Run yamllint before ansible-playbook
• Run ansible-lint on all playbooks
• Use –syntax-check before execution
• Test with –check mode first
• Start with limited host scope (–limit)
• Use tags for incremental testing
• Enable verbose mode for debugging (-vvv)
• Validate variables with assert
• Use molecule for role testing
• Test in staging before production
• Keep collections up to date
• Document custom variables
• Use version control for all playbooks

Quick Reference Commands

# Syntax check
ansible-playbook playbook.yml --syntax-check

# Dry run
ansible-playbook playbook.yml --check --diff

# Run with tags
ansible-playbook playbook.yml --tags webserver

# Limit to specific hosts
ansible-playbook playbook.yml --limit webserver1

# Verbose output
ansible-playbook playbook.yml -vvv

# List tasks
ansible-playbook playbook.yml --list-tasks

# List hosts
ansible-playbook playbook.yml --list-hosts

# Step through tasks
ansible-playbook playbook.yml --step

# Start at specific task
ansible-playbook playbook.yml --start-at-task="Install nginx"

Ansible Module Alternatives

Overview

This guide provides replacement alternatives for deprecated or legacy Ansible modules. Use this reference when ansible-lint reports deprecated module warnings or when updating older playbooks to modern best practices.

Quick Detection

Use the FQCN checker script to automatically detect non-FQCN module usage:

# Scan a playbook
bash scripts/check_fqcn.sh playbook.yml

# Scan a role
bash scripts/check_fqcn.sh roles/webserver/

# Scan entire directory
bash scripts/check_fqcn.sh .

The script identifies modules using short names and provides specific FQCN migration recommendations.

Deprecated Modules and Replacements

Package Management

Deprecated Module	Replacement	Notes
apt (short name)	ansible.builtin.apt	Use FQCN for clarity
yum (short name)	ansible.builtin.yum or ansible.builtin.dnf	dnf preferred for RHEL 8+
pip (short name)	ansible.builtin.pip	Use FQCN
easy_install	ansible.builtin.pip	easy_install is deprecated in Python
homebrew	community.general.homebrew	Moved to community.general
zypper	community.general.zypper	Moved to community.general
apk	community.general.apk	Moved to community.general

File Operations

Deprecated Module	Replacement	Notes
copy (short name)	ansible.builtin.copy	Use FQCN
file (short name)	ansible.builtin.file	Use FQCN
template (short name)	ansible.builtin.template	Use FQCN
lineinfile (short name)	ansible.builtin.lineinfile	Use FQCN
blockinfile (short name)	ansible.builtin.blockinfile	Use FQCN
synchronize	ansible.posix.synchronize	Moved to ansible.posix
acl	ansible.posix.acl	Moved to ansible.posix

Service Management

Deprecated Module	Replacement	Notes
service (short name)	ansible.builtin.service or ansible.builtin.systemd	Use systemd for systemd-based systems
systemd (short name)	ansible.builtin.systemd	Use FQCN
sysvinit	ansible.builtin.service	service module handles sysvinit

User and Group Management

Deprecated Module	Replacement	Notes
user (short name)	ansible.builtin.user	Use FQCN
group (short name)	ansible.builtin.group	Use FQCN
authorized_key (short name)	ansible.posix.authorized_key	Moved to ansible.posix

Networking

Deprecated Module	Replacement	Notes
get_url (short name)	ansible.builtin.get_url	Use FQCN
uri (short name)	ansible.builtin.uri	Use FQCN
iptables	ansible.builtin.iptables	Use FQCN
ufw	community.general.ufw	Moved to community.general
firewalld	ansible.posix.firewalld	Moved to ansible.posix

Command Execution

Deprecated Module	Replacement	Notes
command (short name)	ansible.builtin.command	Use FQCN; prefer specific modules
shell (short name)	ansible.builtin.shell	Use FQCN; prefer specific modules
raw (short name)	ansible.builtin.raw	Use FQCN; use only when necessary
script (short name)	ansible.builtin.script	Use FQCN

Cloud Providers

Deprecated Module	Replacement	Notes
ec2	amazon.aws.ec2_instance	Use amazon.aws collection
ec2_ami	amazon.aws.ec2_ami	Use amazon.aws collection
ec2_vpc	amazon.aws.ec2_vpc_net	Use amazon.aws collection
azure_rm_*	azure.azcollection.*	Use azure.azcollection
gcp_*	google.cloud.*	Use google.cloud collection
docker_container	community.docker.docker_container	Use community.docker collection
docker_image	community.docker.docker_image	Use community.docker collection

Database

Deprecated Module	Replacement	Notes
mysql_db	community.mysql.mysql_db	Use community.mysql collection
mysql_user	community.mysql.mysql_user	Use community.mysql collection
postgresql_db	community.postgresql.postgresql_db	Use community.postgresql collection
postgresql_user	community.postgresql.postgresql_user	Use community.postgresql collection
mongodb_*	community.mongodb.*	Use community.mongodb collection

Monitoring and Logging

Deprecated Module	Replacement	Notes
nagios	community.general.nagios	Use community.general collection
zabbix_*	community.zabbix.*	Use community.zabbix collection

FQCN Migration

Why Use Fully Qualified Collection Names (FQCN)?

1. Clarity: Explicitly shows which collection provides the module
2. Conflict Prevention: Avoids naming conflicts between collections
3. Future-Proofing: Prevents breakage when modules move between collections
4. Best Practice: Recommended by Ansible for all new playbooks

Migration Examples

# Old style (deprecated)
- name: Install nginx
  apt:
    name: nginx
    state: present

# New style (recommended)
- name: Install nginx
  ansible.builtin.apt:
    name: nginx
    state: present

# Old style (deprecated)
- name: Configure firewall
  ufw:
    rule: allow
    port: '443'

# New style (recommended)
- name: Configure firewall
  community.general.ufw:
    rule: allow
    port: '443'

Installing Required Collections

When migrating to FQCN modules, ensure the required collections are installed:

# Install common collections
ansible-galaxy collection install ansible.posix
ansible-galaxy collection install community.general
ansible-galaxy collection install community.docker
ansible-galaxy collection install community.mysql
ansible-galaxy collection install community.postgresql
ansible-galaxy collection install amazon.aws
ansible-galaxy collection install azure.azcollection
ansible-galaxy collection install google.cloud

Or create a requirements.yml:

---
collections:
  - name: ansible.posix
    version: ">=1.5.0"
  - name: community.general
    version: ">=6.0.0"
  - name: community.docker
    version: ">=3.0.0"
  - name: community.mysql
    version: ">=3.0.0"
  - name: community.postgresql
    version: ">=2.0.0"

Then install with:

ansible-galaxy collection install -r requirements.yml

Checking for Deprecated Modules

Use ansible-lint to identify deprecated modules in your playbooks:

# Check for deprecated module usage
ansible-lint --profile production playbook.yml

# Show rule documentation for deprecated modules
ansible-lint -L | grep deprecated

Version Compatibility Notes

• Ansible 2.9: Last version with many modules in ansible.builtin
• Ansible 2.10+: Collections separated from core
• Ansible 2.12+: Many deprecated modules removed from core
• Ansible 2.14+: FQCN strongly recommended for all modules

Resources

• Ansible Collections Index
• Ansible Changelog
• Community Collections
• ansible-lint Rules

Ansible Security Checklist

Overview

This checklist provides comprehensive security validation guidelines for Ansible playbooks, roles, and collections. Use this as a reference when reviewing Ansible code for security vulnerabilities.

Secrets Management

❌ Bad Practices

# Hardcoded passwords
- name: Create user
  user:
    name: admin
    password: "P@ssw0rd123"  # NEVER DO THIS

# Hardcoded API keys
- name: Configure API
  template:
    src: config.j2
    dest: /etc/app/config.yml
  vars:
    api_key: "sk-1234567890abcdef"  # NEVER DO THIS

# Credentials in variables
vars:
  db_password: "secret123"  # NEVER DO THIS
  aws_secret_key: "AKIAIOSFODNN7EXAMPLE"  # NEVER DO THIS

✅ Good Practices

# Use Ansible Vault for sensitive data
- name: Create user
  user:
    name: admin
    password: "{{ admin_password | password_hash('sha512') }}"
  no_log: true

# Load vaulted variables
- name: Include vaulted vars
  include_vars:
    file: secrets.yml  # This file is encrypted with ansible-vault

# Use environment variables
- name: Configure API
  template:
    src: config.j2
    dest: /etc/app/config.yml
  environment:
    API_KEY: "{{ lookup('env', 'API_KEY') }}"
  no_log: true

# Use external secret management
- name: Fetch secret from HashiCorp Vault
  set_fact:
    db_password: "{{ lookup('hashi_vault', 'secret=secret/data/db:password') }}"
  no_log: true

Best Practices

1. Always use Ansible Vault for sensitive data

   ansible-vault create secrets.yml
   ansible-vault encrypt existing_file.yml

2. Never commit unencrypted secrets to version control

3. Use no_log: true for tasks handling sensitive data

   - name: Set database password
     set_fact:
       db_password: "{{ vault_db_password }}"
     no_log: true

4. Rotate secrets regularly and use version control for vault IDs

5. Use different vault passwords for different environments

Privilege Escalation

❌ Bad Practices

# Running entire playbook as root unnecessarily
- hosts: all
  become: yes
  become_user: root
  tasks:
    - name: Check application status
      command: systemctl status myapp

    - name: Read configuration
      slurp:
        src: /etc/myapp/config.yml

# No privilege escalation when needed
- name: Install package
  apt:
    name: nginx
    state: present
  # This will fail without become

✅ Good Practices

# Only use become when necessary
- hosts: all
  tasks:
    - name: Check application status
      command: systemctl status myapp
      # No become needed for read-only systemctl

    - name: Install package
      apt:
        name: nginx
        state: present
      become: yes
      # Only escalate for this task

    - name: Configure application
      template:
        src: config.j2
        dest: /etc/myapp/config.yml
        owner: myapp
        group: myapp
        mode: '0640'
      become: yes

Best Practices

1. Principle of least privilege - only escalate when necessary
2. Use specific become_user instead of always root
3. Limit sudo access to specific commands in sudoers
4. Audit all become usage in playbooks
5. Use become_flags carefully and document why

File Permissions

❌ Bad Practices

# World-readable sensitive files
- name: Create SSH key
  copy:
    src: id_rsa
    dest: /home/user/.ssh/id_rsa
    mode: '0644'  # WRONG: Private key readable by all

# No mode specified
- name: Create config file
  template:
    src: database.conf.j2
    dest: /etc/app/database.conf
  # Missing mode - depends on umask

# Overly permissive
- name: Create script
  copy:
    src: deploy.sh
    dest: /usr/local/bin/deploy.sh
    mode: '0777'  # WRONG: World writable

✅ Good Practices

# Appropriate permissions for private keys
- name: Create SSH key
  copy:
    src: id_rsa
    dest: /home/user/.ssh/id_rsa
    owner: user
    group: user
    mode: '0600'

# Explicit permissions for config files
- name: Create config file
  template:
    src: database.conf.j2
    dest: /etc/app/database.conf
    owner: appuser
    group: appgroup
    mode: '0640'

# Minimal necessary permissions
- name: Create script
  copy:
    src: deploy.sh
    dest: /usr/local/bin/deploy.sh
    owner: root
    group: root
    mode: '0755'

# Set directory permissions properly
- name: Create secure directory
  file:
    path: /etc/app/secrets
    state: directory
    owner: appuser
    group: appgroup
    mode: '0750'

Permission Guidelines

File Type	Recommended Mode	Owner	Group
Private keys	0600	user	user
Public keys	0644	user	user
Config files (sensitive)	0640	app	app
Config files (public)	0644	app	app
Executables	0755	root	root
Directories (sensitive)	0750	app	app
Directories (public)	0755	app	app
Log files	0640	app	app

Command Injection Prevention

❌ Bad Practices

# Unvalidated user input in commands
- name: Process user file
  shell: "cat {{ user_provided_filename }}"
  # VULNERABLE: User could provide "; rm -rf /"

# Direct variable interpolation
- name: Search logs
  command: "grep {{ search_term }} /var/log/app.log"
  # VULNERABLE: User could inject commands

# Using shell when not needed
- name: Create directory
  shell: "mkdir -p {{ directory_name }}"
  # RISKY: Use file module instead

✅ Good Practices

# Use quote filter for variables in shell
- name: Process user file
  shell: "cat {{ user_provided_filename | quote }}"
  when: user_provided_filename is match('^[a-zA-Z0-9._-]+$')

# Better: Use modules instead of shell/command
- name: Create directory
  file:
    path: "{{ directory_name }}"
    state: directory
    mode: '0755'

# Validate input before use
- name: Search logs
  command: "grep {{ search_term }} /var/log/app.log"
  when:
    - search_term is defined
    - search_term | length > 0
    - search_term is match('^[a-zA-Z0-9 ]+$')
  args:
    warn: false

# Use args for command parameters
- name: Run script with arguments
  command: /usr/local/bin/script.sh
  args:
    stdin: "{{ user_input }}"

Best Practices

1. Prefer modules over command/shell whenever possible
2. Always use quote filter for variables in shell commands
3. Validate input with regex patterns
4. Use whitelist validation not blacklist
5. Never trust user input without validation

Network Security

❌ Bad Practices

# Unencrypted protocols
- name: Download file
  get_url:
    url: http://example.com/file.tar.gz  # WRONG: HTTP not HTTPS
    dest: /tmp/file.tar.gz

# Disabled SSL verification
- name: Call API
  uri:
    url: https://api.example.com/data
    validate_certs: no  # WRONG: Disables security

# Exposing on all interfaces unnecessarily
- name: Configure service
  template:
    src: config.j2
    dest: /etc/app/config.yml
  vars:
    bind_address: "0.0.0.0"  # RISKY: Expose to all

✅ Good Practices

# Use HTTPS
- name: Download file
  get_url:
    url: https://example.com/file.tar.gz
    dest: /tmp/file.tar.gz
    checksum: sha256:abc123...

# Validate SSL certificates
- name: Call API
  uri:
    url: https://api.example.com/data
    validate_certs: yes
    client_cert: /path/to/cert.pem
    client_key: /path/to/key.pem

# Bind to specific interface
- name: Configure service
  template:
    src: config.j2
    dest: /etc/app/config.yml
  vars:
    bind_address: "127.0.0.1"  # Localhost only

# Use firewall rules
- name: Configure firewall
  ufw:
    rule: allow
    port: '443'
    proto: tcp
    src: '10.0.0.0/8'  # Only from internal network

Best Practices

1. Always use HTTPS for external communications
2. Validate SSL certificates - only disable for testing
3. Bind services to specific interfaces when possible
4. Use firewall rules to restrict access
5. Encrypt sensitive data in transit (TLS/SSL)

SELinux and AppArmor

Best Practices

# Don't disable SELinux
- name: Configure SELinux
  selinux:
    policy: targeted
    state: enforcing  # Not permissive or disabled

# Set proper SELinux contexts
- name: Set SELinux context for web content
  sefcontext:
    target: '/web/content(/.*)?'
    setype: httpd_sys_content_t
    state: present

- name: Apply SELinux context
  command: restorecon -Rv /web/content

# Manage AppArmor profiles
- name: Load AppArmor profile
  command: apparmor_parser -r /etc/apparmor.d/usr.bin.myapp

Audit and Logging

Best Practices

# Log security-relevant actions
- name: Create admin user
  user:
    name: admin
    groups: sudo
    state: present
  register: admin_user_result

- name: Log user creation
  lineinfile:
    path: /var/log/ansible-changes.log
    line: "{{ ansible_date_time.iso8601 }} - Admin user created by {{ ansible_user_id }}"
    create: yes
  when: admin_user_result.changed

# Use tags for security-related tasks
- name: Configure SSH
  template:
    src: sshd_config.j2
    dest: /etc/ssh/sshd_config
  tags:
    - security
    - ssh

Security Validation Checklist

Before running playbooks in production, verify:

• No hardcoded secrets (passwords, API keys, tokens)
• All sensitive data encrypted with Ansible Vault
• no_log: true used for tasks handling secrets
• Privilege escalation only where necessary
• File permissions explicitly set (not relying on umask)
• Private keys have mode 0600
• No world-writable files or directories
• Input validation for user-provided variables
• Using modules instead of shell/command where possible
• Quote filter used for variables in shell commands
• HTTPS used instead of HTTP
• SSL certificate validation enabled
• Services bound to specific interfaces, not 0.0.0.0
• Firewall rules configured appropriately
• SELinux/AppArmor not disabled
• Security contexts set correctly
• Security-relevant actions logged
• Regular security updates applied
• Unused packages removed
• Default credentials changed
• Unnecessary services disabled

Tools for Security Scanning

1. ansible-lint - Includes security-focused rules

   ansible-lint --profile security playbook.yml

2. Ansible Galaxy Security Scan

   ansible-galaxy collection scan namespace.collection

3. Git-secrets - Prevent committing secrets

   git secrets --scan

4. Trivy - Scan for vulnerabilities

   trivy config .

Additional Resources

• Ansible Security Automation
• Ansible Best Practices - Security
• OWASP Top 10
• CIS Benchmarks