ansible.builtin.assert module – Asserts given expressions are true

Note

This module is part of ansible-core and included in all Ansible installations. In most cases, you can use the short module name assert even without specifying the collections: keyword. However, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

Synopsis

  • This module asserts that given expressions are true with an optional custom message.

  • This module is also supported for Windows targets.

Note

This module has a corresponding action plugin.

Parameters

Parameter

Comments

fail_msg

aliases: msg

string

added in Ansible 2.7

The customized message used for a failing assertion.

This argument was called ‘msg’ before Ansible 2.7, now it is renamed to ‘fail_msg’ with alias ‘msg’.

quiet

boolean

added in Ansible 2.8

Set this to yes to avoid verbose output.

Choices:

  • false ← (default)

  • true

success_msg

string

added in Ansible 2.7

The customized message used for a successful assertion.

that

list / elements=string / required

A list of string expressions of the same form that can be passed to the ‘when’ statement.

Attributes

Attribute

Support

Description

action

Support: full

Indicates this has a corresponding action plugin so some parts of the options can be executed on the controller

async

Support: none

Supports being used with the async keyword

become

Support: none

Is usable alongside become keywords

bypass_host_loop

Support: none

Forces a ‘global’ task that does not execute per host, this bypasses per host templating and serial, throttle and other loop considerations

Conditionals will work as if run_once is being used, variables used will be from the first available host

This action will not work normally outside of lockstep strategies

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target

connection

Support: none

Uses the target’s configured connection information to execute code on it

delegation

Support: none

Aside from register and/or in combination with delegate_facts, it has little effect.

Can be used in conjunction with delegate_to and related keywords

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode

platform

Platforms: all

Target OS/families that can be operated against

See Also

See also

ansible.builtin.debug

Print statements during execution.

ansible.builtin.fail

Fail with custom message.

ansible.builtin.meta

Execute Ansible ‘actions’.

Examples

- ansible.builtin.assert: { that: "ansible_os_family != 'RedHat'" }

- ansible.builtin.assert:
    that:
      - "'foo' in some_command_result.stdout"
      - number_of_the_counting == 3

- name: After version 2.7 both 'msg' and 'fail_msg' can customize failing assertion message
  ansible.builtin.assert:
    that:
      - my_param <= 100
      - my_param >= 0
    fail_msg: "'my_param' must be between 0 and 100"
    success_msg: "'my_param' is between 0 and 100"

- name: Please use 'msg' when ansible version is smaller than 2.7
  ansible.builtin.assert:
    that:
      - my_param <= 100
      - my_param >= 0
    msg: "'my_param' must be between 0 and 100"

- name: Use quiet to avoid verbose output
  ansible.builtin.assert:
    that:
      - my_param <= 100
      - my_param >= 0
    quiet: true

Authors

  • Ansible Core Team

  • Michael DeHaan