Check-mode simulation accuracy for state-dependent Ansible modules

To ensure a custom Python module provides an accurate check-mode simulation, you must explicitly implement a read-only state comparison logic that mirrors the actual modification path without executing the change. Ansible does not automatically simulate state transitions; it relies on the module to report whether a change would have occurred.

Best Practices for Custom Module Implementation

For a module to be "check-mode aware," it must handle the check_mode boolean passed via the module arguments. Follow these implementation patterns:

• Perform a Read-Only Comparison: Instead of skipping the task, the module should fetch the current state of the target system and compare it against the desired state. If they differ, set changed=True and return the result.
• Isolate Side Effects: Wrap all state-changing operations (API calls, file writes, shell commands) in a conditional block that checks if not module.check_mode:.
• Provide Diff Data: To support --diff, calculate the difference between the current and desired state during the check-mode pass and include this in the diff key of the return dictionary.
• Declare Lack of Support: If the module relies on an external tool that cannot predict outcomes without execution, set supports_check_mode=False in the module's metadata. This prevents the module from reporting misleading results.

Detecting Unsupported Check-Mode Tasks

There is no native Ansible engine mechanism to automatically scan a playbook and detect "improperly" implemented check-mode logic. Because the engine trusts the module's return value, a module that fails to implement check_mode logic but returns changed=False will appear successful but be functionally invisible during a dry run.

To identify these gaps, use the following verification workflow:

1. The Divergence Test: Run the playbook with --check --diff. Note all tasks reported as ok (unchanged).
2. The Actual Run: Execute the same playbook without --check. Any task that reports changed during the actual run but reported ok during the check run is an improperly implemented module.
3. The Side-Effect Audit: Run --check and verify via system logs or manual inspection that no actual changes occurred on the target node.

Verification Example

# Verify if a custom module accurately predicts change
ansible-playbook site.yml --check --diff

# Compare result with actual execution
ansible-playbook site.yml

Missing Diagnostic Detail: Are you utilizing the AnsibleModule` base class or writing raw Python scripts? The implementation of the check_mode variable differs slightly between the legacy API and the modern AnsibleModule class.