playbook

Files (2)

• SKILL.md
• role-reference.rst · references/

SKILL.md (first lines)

# Ansible Skill

Write, modify, debug, and optimise Ansible content.

When you create, scaffold, or restructure a role, read
[references/role-reference.rst](references/role-reference.rst) (role layout,
defaults vs vars, meta, handlers, templates). Playbook, inventory, variable,
and single-task work does not need it.

## Dependencies

The user's project should have these installed (via pip, pipx, pixi, or devcontainer):

| Package | Version | Purpose |
|---------|---------|---------|
| `ansible-core` | >= 2.16 | Playbook execution, modules |
| `ansible-lint` | >= 24.0 | Linting playbooks and roles |
| `jmespath` | >= 1.0 | `json_query` filter support |
| `ansible-navigator` | latest | Local execution and testing (optional, often provided by devcontainer) |

```bash
# Lint a playbook or role
ansible-lint playbooks/site.yml

# Syntax check without a live inventory
ansible-playbook --syntax-check playbooks/site.yml -i localhost,

# Install collections from requirements.yml
ansible-galaxy collection install -r requirements.yml
```

## Core Principles

These aren't arbitrary rules — they reflect how the team actually works and what keeps
production stable.

### FQCN Everywhere

Always use fully qualified collection names. Never use short module names. The team uses
`ansible-core` with collections installed via `requirements.yml`, and FQCN prevents ambiguity
and makes collection dependencies explicit.

```yaml
# Correct
- ansible.builtin.dnf:
    name: chrony
    state: present

# Wrong — never do this
- dnf:
    name: chrony
    state: present
```

### Lean Role Structure

Only create directories that contain files. An empty `vars/` or `meta/` directory is noise.
A role with only tasks needs only `tasks/`. Grow the structure as the role's needs grow.

A minimal role is just:
```
roles/my_role/
└── tasks/
    └── main.yml
```

A role with configuration templates and tuneable defaults expands to:
```
roles/my_role/
├── defaults/
│   └── main.yml
├── handlers/
│   └── main.yml
├── tasks/
│   └── main.yml
└── templates/
    └── my_config.j2
```

See [references/role-reference.rst](references/role-reference.rst) for the full pattern.

### Task Splitting by Concern

When a role does more than one logical thing, split tasks into focused files and delegate
from `main.yml`. This keeps diffs reviewable and lets team members reason about changes
in isolation.

```yaml
# roles/vm_configure/tasks/main.yml
---
- name: Configure system packages
  ansible.builtin.import_tasks: packages.yml

- name: Configure NTP via chrony
  ansible.builtin.import_tasks: chrony.yml

- name: Configure SELinux policies
  ansible.builtin.import_tasks: selinux.yml
```

Use `import_tasks` for static inclusion (the default). Use `include_tasks` only when you
need conditional or looped inclusion at runtime.

### Layered Playbook Architecture

Playbooks are organised in numbered layers that run in dependency order, with a `site.yml`
that orchestrates the full stack and a `preflight_checks.yml` gate that validates prerequisites
before any changes.

```
playbooks/
├── site.yml                  # Orchestrator — imports layers in order
├── preflight_checks.yml      # Validation gate — runs first
├── layer1_hypervisor.yml     # Physical host / hypervisor setup
├── layer2_vm_config.yml      # VM-level OS configuration
└── layer3_application.yml    # Application-layer setup (example)
```

New playbooks should follow this layering convention. If a playbook doesn't fit a layer,

From nq-rdl/agent-extensions, CC-BY-4.0.

More from nq-rdl/agent-extensions