# 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
1. **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.
2. **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.
3. **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
```yaml
- 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
1. **CI/CD pipelines** – add a check‑mode job to validate that the configuration will apply correctly before the actual deployment.
2. **Policy enforcement** – generate a dry‑run report to confirm that no unauthorized package updates will occur.
3. **Learning & teaching** – students can see the impact of changes before committing, reinforcing the concept of desired state.

## Further Reading
- [Ansible documentation – Running in Check Mode](https://docs.ansible.com/ansible/latest/user_guide/playbooks_check_mode.html)
- [Module reference – Check mode support](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/index.html)
- [Troubleshooting Check Mode Issues](https://docs.ansible.com/ansible/latest/user_guide/troubleshooting.html#check-mode-issues)

---

*Happy dry‑running!*