Check Mode

Why It Matters

In production or when iterating on a large inventory, you often want to know what an Ansible playbook would do without actually applying any changes. Guessing can lead to downtime, broken services, or costly rollbacks. Check mode gives you a safe “dry‑run” that reports what would change, allowing you to spot mistakes before they hit reality.

Problem • Solution Flow

Problem	How check mode solves it
Unsure if a task will break services	Run with `--check` and inspect the `changed` flag before you hit a live host.
Running a new module on many nodes	Ansible tells you which hosts would be affected, helping you validate scope early.
Complex variable sets that might collide	Check mode can surface potential conflicts without touching files or services.
Auditing compliance	Generates a report of intended changes, useful for audit trails.

How It Works

Modules that support check mode return a changed status of false and may provide a simulated diff. The default is to let the module run as normal – many built‑in modules honour the global --check flag.
Task‑level override – you can set check_mode: yes on a task to force that task into check mode even if the playbook is run normally.
Playbook‑level flag – running the entire playbook with ansible‑playbook <file> --check (short‐hand -C) tells Ansible to execute all modules in simulation mode.

Practical Example

- hosts: webservers
  gather_facts: false
  tasks:
    - name: Ensure Apache is started
      service:
        name: apache2
        state: started
      # Even if we forget `--check`, this task will be skipped in check mode
      check_mode: yes

    - name: Update configuration file
      copy:
        dest: /etc/apache2/sites-available/000-default.conf
        content: "{{ apache_conf }}"
        owner: root
        group: root
        mode: '0644'
      # Default behaviour – will run in check mode if the playbook is invoked with --check

Run: ansible-playbook site.yml -C or ansible-playbook site.yml --check.

You’ll see output similar to:

TASK [Update configuration file] (skipping because of --check)
... changed: false

The diff section (if the module supports it) will show the line‑by‑line differences.

Tips & Gotchas

Not all modules support check mode – e.g., service may report changed even in --check. Check the module docs or run a small test.
Dependencies between tasks – a task that requires a successful change will not run in check mode. Use --diff to verify the intent.
Verbose output – -vvv shows the value‑of‐variables and the simulated changes, useful for debugging.
Ad‑hoc commands – you can also use --check with ansible <host> -m shell -a "...".
Idempotence – if a playbook is truly idempotent, running it in check mode should report no changes after the first pass.

Common Use Cases

CI/CD pipelines – add a check‑mode job to validate that the configuration will apply correctly before the actual deployment.
Policy enforcement – generate a dry‑run report to confirm that no unauthorized package updates will occur.
Learning & teaching – students can see the impact of changes before committing, reinforcing the concept of desired state.

3.8 KiB Raw Blame History Unescape Escape