Ansible

---
name: ansible
description: "Covers Ansible across all versions: playbooks, roles, inventory, modules, collections, AWX/Tower, and configuration management. WHEN: \"Ansible\", \"ansible-playbook\", \"ansible-vault\", \"playbook\", \"role\", \"inventory\", \"Ansible Galaxy\", \"AWX\", \"Ansible Tower\", \"Jinja2 template\", \"ansible.cfg\", \"ansible-lint\". Do NOT use for Ansible against network devices (IOS/NX-OS/Junos/EOS modules, network_cli) — that's the `ansible-network` skill (in the `networking` plugin)."
license: MIT
---

# Ansible Technology Expert

This skill covers Ansible across all supported versions (ansible-core 2.16 through 2.20, Ansible community package 9 through 11), including:

- Playbook design (plays, tasks, handlers, roles, blocks, error handling)
- Inventory management (static, dynamic, groups, host_vars, group_vars)
- Module ecosystem (2800+ modules across 200+ collections)
- Collection architecture (namespaces, dependencies, Galaxy, Automation Hub)
- Jinja2 templating (filters, tests, lookups, custom filters)
- Variable precedence (22 levels of precedence)
- Vault encryption (file-level, variable-level, multi-password)
- AWX / Automation Controller (job templates, workflows, RBAC, inventories)
- Network automation (ios, nxos, eos, junos, panos modules)
- Windows automation (WinRM, win_* modules, DSC integration)

When a question is version-specific, read the matching file under `references/versions/`. When the version is unknown, provide general guidance and note where behavior differs.

## How to Approach Tasks

1. **Classify** the request:
   - **Troubleshooting** -- Load `references/diagnostics.md` for debugging, connection issues, and common errors
   - **Architecture / design** -- Load `references/architecture.md` for execution model, plugin types, and collection internals
   - **Best practices** -- Load `references/best-practices.md` for playbook design, security, performance, and CI/CD
   - **AAP / Tower / Controller** -- Load `references/aap-platform.md` for Automation Platform management, workflows, RBAC, EDA, Receptor mesh, EEs, API usage, and troubleshooting
   - **Inventory** -- Cover static, dynamic, patterns, and variable precedence
   - **Module usage** -- Identify the correct collection and module, provide examples
   - **Vault / secrets** -- Cover encryption, decryption, multi-vault, and integration

2. **Identify version** -- Determine which ansible-core version the user runs (`ansible --version`). Features like `ansible.builtin.include_role` improvements, module defaults groups, and argspec validation differ across versions.

3. **Load context** -- Read the relevant reference file.

4. **Analyze** -- Apply Ansible-specific reasoning. Consider idempotency, connection type, privilege escalation, variable precedence.

5. **Recommend** -- Provide actionable guidance with YAML examples and CLI commands.

6. **Verify** -- Suggest validation steps (`ansible-lint`, `--check --diff`, `--syntax-check`).

## Core Architecture

### Execution Model

```
ansible-playbook site.yml -i inventory/
        │
        ▼
┌──────────────┐
│  Parse YAML  │  Load playbooks, roles, vars, inventory
└──────┬───────┘
       │
┌──────▼───────┐
│  Build play  │  Resolve variables, evaluate conditionals
│   context    │
└──────┬───────┘
       │
┌──────▼───────┐
│  For each    │  Iterate hosts in the play's host pattern
│    host      │
└──────┬───────┘
       │
┌──────▼───────┐
│  Generate    │  Module code + arguments → Python script
│   module     │
└──────┬───────┘
       │
┌──────▼───────┐
│  Transfer &  │  SSH/WinRM → copy module to target → execute → return JSON
│   Execute    │
└──────────────┘
```

**Key characteristics:**
- **Agentless** — No daemon on managed nodes. Uses SSH (Linux) or WinRM (Windows).
- **Push-based** — Control node pushes tasks to managed nodes (pull mode available via `ansible-pull`).
- **Idempotent** — Well-written tasks produce the same result regardless of how many times they run.
- **Ordered** — Tasks execute sequentially within a play (parallelism across hosts via `forks`).

### Inventory

```ini
# Static inventory (INI format)
[webservers]
web1.example.com ansible_host=10.0.1.10
web2.example.com ansible_host=10.0.1.11

[dbservers]
db1.example.com ansible_host=10.0.2.10

[production:children]
webservers
dbservers

[production:vars]
ansible_user=deploy
ansible_become=true
```

```yaml
# Static inventory (YAML format)
all:
  children:
    production:
      children:
        webservers:
          hosts:
            web1.example.com:
              ansible_host: 10.0.1.10
            web2.example.com:
              ansible_host: 10.0.1.11
        dbservers:
          hosts:
            db1.example.com:
              ansible_host: 10.0.2.10
      vars:
        ansible_user: deploy
        ansible_become: true
```

**Dynamic inventory:** Scripts or plugins that query external sources (AWS EC2, Azure, VMware, CMDB) to generate inventory at runtime.

### Variable Precedence (Simplified)

From lowest to highest priority:

1. Role defaults (`roles/x/defaults/main.yml`)
2. Inventory `group_vars/all`
3. Inventory `group_vars/<group>`
4. Inventory `host_vars/<host>`
5. Playbook `group_vars/all`
6. Playbook `group_vars/<group>`
7. Playbook `host_vars/<host>`
8. Host facts (`ansible_*`)
9. Play `vars:`
10. Play `vars_files:`
11. Role vars (`roles/x/vars/main.yml`)
12. Block `vars:`
13. Task `vars:`
14. `set_fact` / `register`
15. Extra vars (`-e` / `--extra-vars`) — **always wins**

**Rule of thumb:** Put defaults in role defaults, environment-specific values in group_vars, and emergency overrides in extra vars.

## Playbook Patterns

### Role Structure

```
roles/
  webserver/
    tasks/main.yml       # Required: task list
    handlers/main.yml    # Handlers (notify-triggered)
    templates/           # Jinja2 templates
    files/               # Static files
    vars/main.yml        # High-priority variables
    defaults/main.yml    # Low-priority defaults
    meta/main.yml        # Dependencies, metadata
    molecule/            # Testing (Molecule)
```

### Error Handling

```yaml
- name: Deploy application
  block:
    - name: Pull latest code
      ansible.builtin.git:
        repo: "{{ app_repo }}"
        dest: /opt/app
        version: "{{ app_version }}"

    - name: Restart service
      ansible.builtin.systemd:
        name: myapp
        state: restarted

  rescue:
    - name: Rollback to previous version
      ansible.builtin.git:
        repo: "{{ app_repo }}"
        dest: /opt/app
        version: "{{ previous_version }}"

    - name: Notify on failure
      ansible.builtin.debug:
        msg: "Deployment failed, rolled back to {{ previous_version }}"

  always:
    - name: Ensure service is running
      ansible.builtin.systemd:
        name: myapp
        state: started
```

### Vault Encryption

```bash
# Encrypt a file
ansible-vault encrypt group_vars/production/vault.yml

# Encrypt a single variable value
ansible-vault encrypt_string 'SuperSecret123' --name 'db_password'

# Run playbook with vault password
ansible-playbook site.yml --ask-vault-pass
ansible-playbook site.yml --vault-password-file ~/.vault_pass

# Multiple vault IDs (different passwords for different secrets)
ansible-playbook site.yml --vault-id dev@prompt --vault-id prod@/path/to/prod_pass
```

### Common Modules

| Module | Purpose | Example |
|---|---|---|
| `ansible.builtin.apt` / `yum` / `dnf` | Package management | Install, remove, update packages |
| `ansible.builtin.service` / `systemd` | Service management | Start, stop, enable, restart |
| `ansible.builtin.copy` | Copy files | Static file transfer |
| `ansible.builtin.template` | Jinja2 templates | Dynamic config file generation |
| `ansible.builtin.file` | File/directory management | Permissions, ownership, symlinks |
| `ansible.builtin.user` / `group` | User management | Create users, manage groups |
| `ansible.builtin.lineinfile` | Line editing | Modify specific lines in files |
| `ansible.builtin.uri` | HTTP requests | API calls, health checks |
| `ansible.builtin.command` / `shell` | Run commands | **Use as last resort** — not idempotent |
| `ansible.builtin.debug` | Debugging | Print variables, messages |

## Version-Specific Guidance

| Version | Reference | What's new |
|---|---|---|
| ansible-core 2.18 | `references/versions/2.18.md` | Python 3.11+ control-node requirement, improved collection dependency resolution, module defaults groups, removed legacy callback plugins |
| ansible-core 2.19 | `references/versions/2.19.md` | Enhanced argspec validation, improved async task handling, new inventory plugin features, Jinja2 3.2 requirement |
| ansible-core 2.20 | `references/versions/2.20.md` | Execution environment improvements, enhanced FQCN enforcement, new testing utilities, declarative role dependencies |

## Reference Files

- `references/architecture.md` — Plugin system (connection, callback, lookup, filter, inventory), execution internals, collection structure, AWX architecture
- `references/best-practices.md` — Playbook organization, idempotency patterns, performance tuning, security hardening, testing with Molecule
- `references/diagnostics.md` — Connection failures (SSH, WinRM), module errors, variable resolution issues, performance debugging
- `references/aap-platform.md` — Ansible Automation Platform (AAP) / Tower platform management: Controller, Private Automation Hub, EDA, Receptor mesh, Execution Environments, RBAC, workflows, credentials, API usage, backup/restore, upgrades, and troubleshooting

## Diagnostic Scripts

Ready-made dry-run/verification scripts (read-only) in `scripts/`.

- `scripts/01-inventory-and-ping.sh` -- Inventory graph plus connectivity sweep
- `scripts/02-check-mode-diff.sh` -- --check --diff preview with non-idempotence caveats