RunBook AcademyAnsible

← All checklists in Ansible

Before deploymentDeployment

Checklist: Role readiness before merge

18 items ·12 critical ·6 warn ·0 info

Run this on the pull request, before the role is merged into the branch that production runs from. It is a code review aid: most of it is a static read of roles/, and the reviewer runs it from a checkout of the branch under review.

The commands are written against a role directory named webapp and a repository whose roles live in roles/. Substitute your own names. Several checks loop over roles/*/ and will therefore report on every role in the repository, not only the one under review - filter the output to the role you are reviewing, or the pre-existing findings will drown the new ones.

What a failure means

The critical items are the ones that make a role behave differently for its next caller than for its author. A role with an unnamespaced handler, an undeclared variable or an assumed sibling works perfectly in the repository it was written in and breaks the first time somebody reuses it - which is the whole reason the role exists.

Access this needs

Everything except the two Molecule items is a static read and needs only a checkout. Read them before you run anything.

Where the evidence goes

The Molecule run output - converge, idempotence and verify - is the evidence that belongs on the pull request. So does the platform list, because “tested on every supported platform” is a claim about a set, and a reviewer cannot check a set they cannot see.

Sign-off

Author: _________________ Date: ___________
Reviewer: ________________ Date: ___________

Critical12 items

The role has meta/argument_specs.yml. Without it, a caller who misspells a variable gets the role default silently, and the first evidence is a host configured with something nobody asked for. With it, the run stops before the first task. Prints one line per role that lacks the file.
```
for r in roles/*/; do test -f "$r/meta/argument_specs.yml" || echo "MISSING argument_specs: $r"; done
```

Every variable the role uses is either declared in defaults/, declared in vars/, or supplied by the argument spec. Prints any variable the role reads without defining anywhere - those are the ones that work on the author machine because something else in the repository happened to set them.

python3 - <<'PY'
import glob, os, re, yaml
for role in sorted(glob.glob('roles/*/')):
    name = os.path.basename(role.rstrip('/'))
    known = set()
    for f in (role + 'defaults/main.yml', role + 'vars/main.yml'):
        if os.path.exists(f):
            known |= set((yaml.safe_load(open(f)) or {}).keys())
    used = set()
    for f in glob.glob(role + '**/*', recursive=True):
        if os.path.isdir(f): continue
        used |= set(re.findall(r'\{\{\s*([a-z][a-z0-9_]*)', open(f, errors='ignore').read()))
    for v in sorted(used - known):
        if v.startswith(('ansible_', 'item', 'inventory_', 'group_', 'hostvars', 'lookup', 'play_')):
            continue
        print(f"UNDOCUMENTED: {name}: uses {v!r} but neither defaults/ nor vars/ defines it")
PY

Every handler name is namespaced to the role. Handler names are global within a play: two roles that both define `restart nginx` become one handler, and which body runs is decided by load order. Prints one line per handler that is not prefixed with its role name.

for h in roles/*/handlers/main.yml; do
  r=$(basename "$(dirname "$(dirname "$h")")")
  python3 -c "
import sys, yaml
role, path = sys.argv[1], sys.argv[2]
for t in (yaml.safe_load(open(path)) or []):
    n = (t or {}).get('name', '')
    if not n.startswith(role):
        print(f'FINDING: {path}: handler {n!r} is not namespaced with {role!r}')
" "$r" "$h"
done

The role does not depend on another role having run first unless that dependency is declared in meta/main.yml or the role asserts it. A role that assumes `common` created a directory works in the repository it was written in and fails the first time somebody uses it alone.
```
cat roles/*/meta/main.yml 2>/dev/null; grep -rn 'include_role\|import_role' roles/
```
ansible-lint is clean at the production profile for the role. Exit 2 means findings, exit 0 means clean.
```
ansible-lint --nocolor -q --profile production roles/webapp; echo "exit=$?"
```
No credential is present in defaults/ or vars/, even as a placeholder. A default password is a real password on every host whose caller forgot to override it. Prints any secret-shaped key with a literal value; no output is the pass condition.
```
grep -rInE '(pass|password|passwd|secret|token|api_key|private_key)[a-z_]*:[[:space:]]*[^[:space:]{]' roles/*/defaults/ roles/*/vars/ 2>/dev/null
```
Every `command` and `shell` task declares `changed_when`, or uses `creates`/`removes`. A command task with neither reports `changed` on every run, which destroys the role idempotence signal and makes drift detection impossible. The lint item above catches this as no-changed-when; this is the item that says it is not optional.
```
ansible-lint --nocolor -q --profile production roles/webapp 2>/dev/null | grep -A1 'no-changed-when'
```

The role has at least one Molecule scenario, and it converges. Prints one line per role with no scenario.

for r in roles/*/; do test -f "$r/molecule/default/molecule.yml" || echo "MISSING molecule scenario: $r"; done

The Molecule idempotence step passes: a second converge reports zero changed tasks. This is the single check that separates a role that configures a host from a role that merely writes to it.
```
molecule test -s default
```
The scenario runs on every platform the role claims to support in meta/main.yml. A role that lists Debian and EL and is only tested on Debian is a role whose EL support is a hypothesis.
```
grep -A10 'platforms:' roles/*/meta/main.yml 2>/dev/null; grep -rn 'image:\|box:' roles/*/molecule/*/molecule.yml 2>/dev/null
```
The scenario verifies the outcome, not the action. Asserting that a file exists proves the template task ran; asserting that the service answers on its port proves the role did its job. Only the second one fails when a valid template produces a configuration the daemon rejects.
```
ls roles/*/molecule/*/verify.yml 2>/dev/null || echo "FINDING: no verify.yml - the scenario converges but checks nothing"
```
The role is consumed by version - a Git tag or a Galaxy version in requirements.yml - not by branch. A playbook that pulls a role from `main` has no fixed behaviour, and the same commit of the playbook does different things on different days.
```
grep -nE 'version:|src:' requirements.yml
```

Warning6 items

Every default is prefixed with the role name. Two roles that both define `app_port` collide in the same play, and the winner depends on include order rather than on anything a reader can see. Prints one line per unprefixed default.

for d in roles/*/defaults/main.yml; do
  r=$(basename "$(dirname "$(dirname "$d")")")
  python3 -c "
import sys, yaml
role, path = sys.argv[1], sys.argv[2]
for k in (yaml.safe_load(open(path)) or {}):
    if not k.startswith(role.replace('-', '_') + '_'):
        print(f'FINDING: {path}: default {k!r} is not prefixed with {role!r}')
" "$r" "$d"
done

Values a caller is expected to change live in defaults/, not vars/. A variable in vars/ can only be overridden by a small number of higher-precedence sources, so a role that puts its interface in vars/ is one the caller cannot configure without editing the role.
```
ls -la roles/*/vars/main.yml 2>/dev/null && cat roles/*/vars/main.yml
```
Where the role genuinely requires something it cannot create, it asserts that up front rather than failing halfway through. An `assert` in the first task fails the host before any change; a missing directory discovered in task nine fails the host after eight changes.
```
grep -rn 'ansible.builtin.assert' roles/*/tasks/
```
The role does not turn on privilege escalation for itself. `become` belongs to the caller, who knows the connection user and the escalation method; a role that hardcodes `become: true` cannot be used by a caller who is already root or who escalates differently.
```
grep -rn 'become' roles/*/tasks/ roles/*/defaults/ roles/*/meta/
```
Where the scenario runs in a container and the role touches something a container cannot represent - systemd as PID 1, a reboot, a kernel module, a real filesystem - the gap is written down in the role README. An untested path is acceptable; an untested path nobody knows about is not.
The README states what the role does, what it requires, every variable with its default and its effect, and one worked example of calling it. The argument spec is machine-readable; the README is what a colleague reads at 03:00.
```
for r in roles/*/; do test -s "$r/README.md" || echo "MISSING or empty README: $r"; done
```