GPT-OSS additions

check-mode.md

@@ -1,14 +1,69 @@
-## Check Mode
+# Check Mode
 
-Run playbooks in simulation mode without making changes:
+## 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
-- name: Restart service (check mode)
-  service:
-    name: apache2
-    state: restarted
-  check_mode: yes
+- 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
 
-# Run with check mode:
-# ansible-playbook site.yml --check
-```
+    - 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!*