Using Ansible Check Mode to Preview Changes Safely

Problem: You need confidence before applying a playbook

When preparing a change across many servers, it’s common to worry that a typo or an unexpected variable will cause unwanted modifications. Running the playbook first in a safe preview mode lets you verify what Ansible would do without touching the systems.

Thesis: Ansible’s check mode (``--check``) provides a reliable dry‑run that shows would‑be changes while leaving remote hosts untouched.

How check mode works

When you invoke ``ansible-playbook --check``, Ansible still gathers facts (unless ``gather_facts: no``) and then executes each task. Modules that support check mode are called with a special argument that makes them report whether they would change the system, but they do not perform the actual change. Modules without check‑mode support are either skipped or, if they have safety guards like ``creates`` or ``removes``, they may still run in a limited way. The result is a task‑by‑task report of ``changed: true`` or ``changed: false`` that reflects the current system state.

Enabling check mode

• Global flag: add ``--check`` to the command line.
• Per‑task or per‑block: set ``check_mode: yes`` inside the task or block definition.
• To disable check mode for a specific task while the playbook runs in check mode, use ``check_mode: no``.

These controls let you simulate most of a playbook while still allowing certain tasks (e.g., a cleanup script) to run for real if needed.

Worked example: previewing a file copy

Assume you have an inventory file ``inventory.ini`` and a simple playbook ``copy_demo.yml``:

---
- hosts: all
  become: yes
  tasks:
    - name: Ensure a test file exists with specific content
      copy:
        dest: /tmp/ansible_check_demo.txt
        content: "This is a test file created by Ansible check mode demo."
        mode: '0644'

To run the preview:

1. Log in to a control node with SSH access to the target hosts (the user must be able to become root or have sudo rights).
2. Execute:

ansible-playbook -i inventory.ini copy_demo.yml --check

You should see output similar to:

TASK [Ensure a test file exists with specific content] ***********************
ok: [host1] => {
    "changed": true,
    "msg": ""
}

The ``changed: true`` indicates that, if the playbook were run normally, the file would be created or updated. Importantly, after the command finishes, you can verify that ``/tmp/ansible_check_demo.txt`` does **not** exist on the hosts:

ssh host1 "ls -l /tmp/ansible_check_demo.txt"
# returns: No such file or directory

Running the same playbook without ``--check`` will create the file, and a subsequent ``--check`` run will again report ``changed: true`` because the file already matches the desired state.

Trade‑offs and limitations

Check mode is valuable for spotting intentional modifications, but it cannot catch errors that only appear after a change is applied. For example, a task that updates a configuration file and then restarts a service may report success in check mode, yet the service could fail to start when the real file is in place. Therefore, a follow‑up run in normal mode is still required for validation.

Additionally, not all modules implement check mode. Modules like ``shell`` or ``command`` are skipped unless they include arguments such as ``creates`` or ``removes`` that allow Ansible to infer safety. Review the module documentation (e.g., ``ansible-doc -t copy copy``) to confirm ``check_mode: true`` support before relying on the simulation.

Practical verification steps

1. Run the playbook with ``--check`` and note which tasks report ``changed``.
2. After the check run, inspect the relevant files or services on a target host to ensure they remain unchanged.
3. Run the playbook without ``--check`` to apply the changes.
4. Confirm the expected state is now present.
5. Optionally run ``--check`` again; tasks should now show ``changed: false`` if the state matches the desired configuration.

These steps give you confidence that the preview accurately reflects the real effect.

Actionable closing

Incorporate ``--check`` into your change‑control workflow: run every new or modified playbook in check mode first, review the ``changed`` output, and only proceed to the normal run once the preview matches your expectations. Remember to verify module support and to treat check mode as a preview, not a substitute for post‑change validation.