Run control: check, diff, tags, limit

Every flag here answers the same nervous question: what exactly will this playbook do when I hit enter? Since lesson 12 you’ve run ansible-playbook bare — fine against a lab VM. Against machines people depend on, you run a ritual first. Every step is a flag on the same command.

Check mode: the dry run

--check puts the whole run into check mode : every module reports what it would do — changed or ok per task — without touching the host. Every module already compares desired state against current state before acting; check mode stops after the comparison and reports the verdict.

Add --diff and file-shaping modules like template and lineinfile print the line-by-line diff of what would change. Learn the two flags as one word: --check --diff means “show me the edit before you make it.”

Tags: run a slice

Any task or play can carry tags:. They do nothing until you ask for them:

- name: Renew the TLS certificate
  ansible.builtin.command: certbot renew # command task — skipped under --check
  tags: [certs]

- name: Push the nginx config
  ansible.builtin.template: # file-shaping task — previews under --diff
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  tags: [nginx]

--tags certs runs only the tasks tagged certs — everything untagged is skipped for that run. --skip-tags is the inverse: run everything except. That’s how a 40-task playbook re-runs just its certificate steps.

Narrowing and resuming

Tags slice tasks; --limit (lesson 10) slices hosts — the same flag as on ad-hoc commands. When a run dies at task 31 of 40, --start-at-task resumes from a named task instead of replaying the 30 that already converged:

ansible-playbook site.yml --tags certs --limit web01 # just certs, one host
ansible-playbook site.yml --skip-tags nginx # everything except nginx tasks
ansible-playbook site.yml --start-at-task 'Push the nginx config' # resume

Seeing more: the verbosity ladder

When a run confuses you, the same command takes -v flags. -v prints each task’s full result dict — what register: would have captured. -vvv adds connection detail and the exact arguments each module received. That settles lesson 16’s question of which value won precedence: you see the value Ansible actually used. -vvvv turns on connection debugging — SSH’s own debug output — for “why can’t it even reach the host” problems. Start at -v; escalate only when needed.

The ritual

Before a playbook touches anything real, four commands in order:

ansible-playbook site.yml --syntax-check # parse errors; nothing runs
ansible-playbook site.yml --list-tasks # the run plan: task names + tags
ansible-playbook site.yml --check --diff # what would change, shown as diffs
ansible-playbook site.yml # the real run

You met --syntax-check in lesson 13 — it catches YAML and playbook-structure errors without contacting a single host. --list-tasks also runs nothing. It prints every task name with its tags: your preview, and the fastest way to find the exact string --start-at-task and --tags want.

The flags compose into sentences: --limit web --tags nginx --check --diff reads as “show me what the nginx tasks would change on the web hosts.” When a colleague says run it in check mode first, they mean this ritual, not just the one flag.