Ansible Playbook Dry Run: Run Playbook in "Check Mode"

Introduction

Ansible is an Infrastructure as Code tool that allows you to use a single control node to monitor and manage remote servers.

Ansible lets you manage remote servers by creating playbooks, which contain lists of tasks for the remote servers to perform. It also provides a check mode in which you can test a playbook.

This tutorial shows you how to do a dry run of an Ansible playbook by using the built-in check mode feature.

Prerequisites

• A Linux system (we are using Ubuntu 20.04)
• Access to the command line / terminal window
• Ansible installed and configured (see our guides on Installing Ansible on Windows or Installing Ansible on Ubuntu)

When to Use Ansible Dry Run

Using Ansible’s dry run feature enables users to execute a playbook without making changes to the servers. It uses the built-in check mode to proof a playbook for errors before execution.

This option is very useful when executing complex playbooks that contain commands which make major changes to servers. Using the dry run feature helps find fatal errors before they shut down servers and make them unusable.

Ansible Dry Run – Executing Playbooks in Check Mode

The easiest way to do a dry run in Ansible is to use the check mode. This mode works like the --syntax-check command, but on a playbook level.

Check Mode

Use the -C or --check flag with the ansible-playbook command to do a dry run of an Ansible playbook:

ansible-playbook playbook.yaml --check

This produces the same output as actually running the playbook, except it will report on changes it would have made rather than making them.

Another way to run a playbook in check mode is to add the check_mode parameter to the playbook content:

---
- hosts: all
  tasks:
  - name: A command to run in check mode
    command: /your/command
    check_mode: on

Diff Option

Using the --diff flag with the ansible-playbook command reports what changes were made while executing the playbook:

ansible-playbook playbook.yaml --diff

Using the --diff flag produces a lengthy output, so it’s best used when checking for changes on a single host.

Combining Check and Diff

Combining the --check and --diff flags with the ansible-playbook command gives you a more detailed overview of all the changes made by your playbook:

ansible-playbook playbook.yaml --check --diff

This produces the same detailed output you get when using the --diff flag, but without actually executing any of the changes.

When Not to Use Ansible Dry Run

Using the dry run feature is useful for node-by-node basic configuration management.

However, if your playbook contains conditional or result-based tasks, it won’t work in check mode. This is because the conditions for those tasks can’t be satisfied without actually executing the playbook and making changes.

Conclusion

After following this tutorial, you should know how to use the --check and --diff flags to perform a dry run of an Ansible playbook.

You should also be able to recognize when and when not to perform dry runs.