Ansible fail with custom message example

The Objective

If you are a pioneer of Ansible, you might have come across or had this question "How to print a custom message with fail  or failed_when" or "How to print a custom error message in case of failure"

while running the ansible-playbook. What is so fun in displaying the built-in default error messages like "the command is wrong" or "the variable is undefined". Most of the time the ansible returned error messages would not justify their own purpose of conveying the message on what went wrong as it would be too vague.

So it is necessary that we should build our ansible playbooks to return highly intelligible and easily interpreted error messages when the task is failing for some reason.

 

Syntax: Sample Playbook with fail and custom message

---
 - name: Find files - Playbook
   hosts: app

   pre_tasks:
   - name: Make Sure the mandatory input values are passed (Directory and SearchString)
     fail:
      msg: "Directory and SearchString are the mandatory values to execute the playbook. Variables must be passed as extra variable -e "
     when: Directory is not defined or SearchString is not defined

 

The Real-time Example

In this post, we are going to see how to print custom error message with ansible fail module

For this post, Let me reuse the following playbook we have used in our another article/post, but with little modification

First, let us see the playbook from the tagged post which has no fail and custom message.

 

Ansible Playbook with  NO Fail and Custom message

---
 - name: Find files - Playbook
   hosts: appservers
   tasks:

   # Case1:  when Search String and Modified time is mentioned
   - name:  Find command with *SEARCH STRING* and *MODIFIED TIME*
     shell: "find {{Directory}} -name '{{SearchString}}' -mtime '{{mtime}}'"
     register: case1output
     when: Directory is defined and SearchString is defined and mtime is defined
     ignore_errors: true

   # Case2: when Only Search String is mentioend but NOT Modified time(age)
   - name:  Find command with only with *SEARCH STRING*
     shell: "find {{Directory}} -name '{{SearchString}}' "
     register: case2output
     when: Directory is defined and SearchString is defined and mtime is not defined
     ignore_errors: true
     
   # In case of Case1 Success
   - name: Case1 Output – Output will be displayed only if Case is Success (or) it will be skipped 
     debug: var=case1output.stdout_lines
     when: case1output.stdout_lines is defined

   # In case of Case2 Success
   - name: Case2 Output – Output will be displayed only if Case is Success (or) it will be skipped 
     debug: var=case2output.stdout_lines
     when: case2output.stdout_lines is defined

Explanation and the Requirement

As you could have already figured out (or) read in the article hyperlinked.  This playbook is created to find old log files based on the set of startup arguments given.

The playbook is designed to accept two cases/ two type of executions. In both cases, we need to pass Directory and Search String as mandatory arguments.

Based on the third variable's presence ( mtime or modified time), the playbook would switch cases and act accordingly.

Having said that, we are in need to pre-validate these two mandatory variables as they are needed irrespective of what case the user would like to execute. We need to print some message and exit or terminate the execution

 

The Problem

If it is a simple shell script. A Simple if statement and $# would do the validation for us. But in ansible? 

if [ $# -ne 3 ]
     echo -e "the script takes three argument but $# are found" 
     exit 5
fi

Now the Question is

How to fail the ansible playbook when the list of arguments are not passed/available? How to fail with the custom message so that we can tell the user what went wrong before exiting.

 

Solution

Now the pre-validation and the termination can be done using when or failed_when  inside the pre_tasks  segment of an ansible playbook.

But How to print custom message with fail?

that's where the fail with custom message plays the role. Now refer the following modified ansible playbook designed to fail with the custom message during pre-validation

 

The Playbook to Fail with Custom Message

---
 - name: Find files - Playbook
   hosts: app

   pre_tasks:
   - name: Make Sure the mandatory input values are passed (Directory and SearchString)
     fail:
      msg: "Directory and SearchString are the mandatory values to execute the playbook. Variables must be passed as extra variable -e "
     when: Directory is not defined or SearchString is not defined
   
   tasks:

   # Case1:  when Search String and Modified time is mentioned
   - name:  Find command with *SEARCH STRING* and *MODIFIED TIME*
     shell: "find {{Directory}} -name '{{SearchString}}' -mtime '{{mtime}}'"
     register: case1output
     when: Directory is defined and SearchString is defined and mtime is defined
     ignore_errors: true

   # Case2: when Only Search String is mentioend but NOT Modified time(age)
   - name:  Find command with only with *SEARCH STRING*
     shell: "find {{Directory}} -name '{{SearchString}}' "
     register: case2output
     when: Directory is defined and SearchString is defined and mtime is not defined
     ignore_errors: true
     
   # In case of Case1 Success
   - name: Case1 Output – Output will be displayed only if Case is Success (or) it will be skipped 
     debug: var=case1output.stdout_lines
     when: case1output.stdout_lines is defined

   # In case of Case2 Success
   - name: Case2 Output – Output will be displayed only if Case is Success (or) it will be skipped 
     debug: var=case2output.stdout_lines
     when: case2output.stdout_lines is defined

 

 failed_when and fail or two different modules. fail module is intentionally created to print custom message while failing. So Dont confuse yourself

See it in Action

Hope you learnt how to print custom message with the fail module and also to pre-validate the required variables.

Leave your ratings : [ratings]

Thanks,

SaravAK

---