ansible-preflight

Ansible Preflight Validation

You are helping validate Ansible changes for the olympus Proxmox cluster before they are deployed. The goal is to catch errors that historically required follow-up fix commits.

Always run validation from the ansible/ directory with vault password available:

cd /path/to/home-lab/ansible

Step 1: Syntax Check

Run syntax-only validation (no connection required):

ansible-playbook --syntax-check -i inventory/hosts.yml proxmox_cluster.yml \
  --vault-password-file ~/.vault_pass.txt

ansible-playbook --syntax-check -i inventory/hosts.yml service_vms.yml \
  --vault-password-file ~/.vault_pass.txt

ansible-playbook --syntax-check -i inventory/hosts.yml openclaw_cluster.yml \
  --vault-password-file ~/.vault_pass.txt

For a specific role or tag only:

ansible-playbook --syntax-check -i inventory/hosts.yml proxmox_cluster.yml \
  --tags <role_name> --vault-password-file ~/.vault_pass.txt

Step 2: Lint Check

Run ansible-lint for best-practice violations:

cd ansible && uv run ansible-lint roles/<role_name>/
uv run ansible-lint playbooks/

Key lint rules to pay attention to:

• no-changed-when — shell/command tasks without changed_when
• risky-shell-pipe — shell commands piped without pipefail
• no-free-form — using free-form module args instead of structured YAML
• fqcn-builtins — using short names (e.g. copy) instead of FQCN (ansible.builtin.copy)

Step 3: Dry Run (Check Mode)

Test against live hosts without making changes:

# Full playbook dry-run with diff output
ansible-playbook --check --diff -i inventory/hosts.yml proxmox_cluster.yml \
  --vault-password-file ~/.vault_pass.txt --tags <role>

# Single host dry-run
ansible-playbook --check --diff -i inventory/hosts.yml proxmox_cluster.yml \
  --limit r420.infiquetra.com --vault-password-file ~/.vault_pass.txt

Note: Check mode does not work reliably for tasks that use delegate_to, run_once, or pvecm/pveceph CLI commands — these will show as "skipped" in check mode even though they have real effects.

Step 4: Variable Resolution Check

Verify variables are resolved before referencing them:

# Print all variables for a host (catches undefined vars before runtime)
ansible -i inventory/hosts.yml r420.infiquetra.com -m debug \
  -a "var=hostvars[inventory_hostname]" --vault-password-file ~/.vault_pass.txt

For template validation, test Jinja2 rendering:

ansible -i inventory/hosts.yml all -m debug \
  -a "msg={{ your_variable }}" --vault-password-file ~/.vault_pass.txt

Step 5: Common Mistakes Check

Before finalizing, review the common mistakes catalog (references/common-mistakes.md) and manually verify the change doesn't exhibit any of the known patterns extracted from the fix commit history.

Quick Preflight Checklist

When reviewing Ansible changes, check:

• become: true on all tasks that run as root (pvecm, pveceph, ceph, systemctl)
• delegate_to: "{{ proxmox_master }}" on all cluster-wide operations (pvecm join, ceph init)
• run_once: true paired with delegate_to when creating global resources
• serial: 1 on node-join and OSD-add plays (prevents race conditions)
• when: not ansible_check_mode on tasks that can't run in check mode
• changed_when: false or changed_when: result.rc != 0 on shell/command tasks
• ignore_errors: false — only use ignore_errors: true when genuinely OK to fail
• Variable defaults in defaults/main.yml for every variable used in tasks
• Idempotency: re-running the role should not change state if already applied
• Vault variables referenced as {{ vault_var }} exist in the encrypted vault file