69 lines
3.8 KiB
Markdown
69 lines
3.8 KiB
Markdown
# 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!* |