Ansible assert Module: Validate Conditions in Playbooks

Introduction

The assert module in Ansible is a powerful tool for validating conditions and ensuring the correctness of your automation workflows. By halting execution when a condition isn't met, it prevents cascading failures and provides valuable feedback to the user. In this article, we'll explore the quiet, fail_msg, and success_msg parameters, which enhance the flexibility and usability of assertions in playbooks.

Use ansible.builtin.assert for guard clauses in playbooks: check that variables, facts, ports, files, or other expressions match your expectations before running the tasks that depend on them.

What is the assert Module?

The assert module evaluates one or more conditions and ensures they are true. If any condition fails, the module raises an error and stops execution. It's particularly useful for debugging, validation, and ensuring preconditions in complex playbooks.

Basic Syntax

- name: Validate a condition
  assert:
    that:
      - some_variable == "expected_value"

If some_variable doesn't equal expected_value, the playbook will fail at this step.

Enhancing Assertions with quiet, fail_msg, and success_msg

1. quiet: Suppress Output for Passed Assertions

By default, the assert module outputs all evaluated conditions. However, in scenarios where you only want feedback on failures, quiet: true suppresses success messages.

Example:

- name: Ensure a directory exists
  assert:
    that:
      - ansible_facts['os_family'] == "RedHat"
    quiet: true

Use Case:

• Keeps playbook output clean and focused, especially when numerous assertions are involved.

2. fail_msg: Custom Error Messages for Failures

The fail_msg parameter allows you to define a custom error message displayed when the assertion fails. This is invaluable for providing context or instructions for resolving issues.

Example:

- name: Validate OS family
  assert:
    that:
      - ansible_facts['os_family'] == "Debian"
    fail_msg: "The target system is not running a Debian-based OS."

Output on Failure:

fatal: [localhost]: FAILED! => 
  msg: "The target system is not running a Debian-based OS."

Use Case:

• Improves debugging by clarifying the cause of failure and suggesting corrective actions.

3. success_msg: Provide Feedback on Success

The success_msg parameter lets you display a custom message when the assertion passes. This is useful for confirming critical preconditions or providing reassurance to the user.

Example:

- name: Ensure disk space is sufficient
  assert:
    that:
      - available_disk_space > 1024
    success_msg: "Sufficient disk space available for the deployment."

Output on Success:

ok: [localhost] => 
  msg: "Sufficient disk space available for the deployment."

Use Case:

• Provides positive feedback during playbook execution, boosting confidence in critical tasks.

Combining All Parameters: A Comprehensive Example

Here's how to use quiet, fail_msg, and success_msg together in a real-world scenario:

- name: Validate prerequisites for deployment
  assert:
    that:
      - ansible_facts['os_family'] == "RedHat"
      - available_memory_mb > 2048
    quiet: false
    fail_msg: >
      Validation failed: Ensure the target is a RedHat-based OS with at least 2GB of available memory.
    success_msg: >
      Prerequisites are met: The target is a RedHat-based OS with sufficient memory.

Output on Success:

ok: [localhost] => 
  msg: "Prerequisites are met: The target is a RedHat-based OS with sufficient memory."

Output on Failure:

fatal: [localhost]: FAILED! => 
  msg: "Validation failed: Ensure the target is a RedHat-based OS with at least 2GB of available memory."

Conclusion

The assert module is an essential tool for creating robust and reliable playbooks. By leveraging quiet, fail_msg, and success_msg, you can tailor its behavior to provide clear, actionable feedback, keeping your automation workflows efficient and user-friendly. Incorporate these features into your playbooks to streamline validation and debugging.

For more tips and real-world examples, explore my book Ansible by Example or check out additional resources below.