Functionality - Advanced

Rescue

Both built-in & plugin actions can be rescued if they raise an error.

Summary

Rescuing an action allows you to:

  • Determine the type of raised error
  • View/inspect the raised error message
  • Perform actions when errors are raised

Rescue Variables

These can be used in all rescue block actions.

Error Message

  • Jinja2: rescue.error
  • Python: rescue["error"]

Error Type (Advanced)

  • Jinja2: rescue.type
  • Python: rescue["type"]

Behaviour

When rescuing failed actions you have the opportunity to:

  • Run rescue actions before failing the task
  • Run rescue actions before continuing to the next action

By default the task will:

  • Perform all applicable actions in the rescue block
  • Proceed to the next step action or step

If the task should fail when a specific error is rescued, you must make it fail in the rescue block.

You can do this using the exit action with a non-zero exit code.

Example Action

This Playbook actions gets all interfaces from a Cisco switch.

A rescue block is supplied to display more useful error messages in different failure cases.

Each failure case is described below, with the completed action example shown at the end.

DNS Failure

If the connection fails due to a DNS problem, the rescued error is "Name does not resolve".

In this scenario the task uses when conditions to:

  • Display a more useful error message using a PPA plugin action
  • Fail the task using exit with an exit_code of 1
Catching DNS Error
1
2
3
4
5
6
7
      rescue:
        - ppa.ui.output_error:
            text: Failed to resolve switch DNS address '{{ cisco_switch.address }}'
          when: "Name does not resolve" in rescue.error
        - exit:
            exit_code: 1
          when: "Name does not resolve" in rescue.error

Other Failures

If the error was not DNS related, the following rescue actions will:

  • Display a generic error message using a PPA plugin action
  • Fail the task using exit with an exit_code of 2

These actions should be supplied to the rescue block after the DNS error actions.

As these these actions catch any other error, they do not need when conditions.

All Other Errors
1
2
3
4
    - ppa.ui.output_error:
        text: Failed to connect to the switch. Please view the logs for more information.
    - exit:
        exit_code: 2

Completed Example

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
- cisco_ios_switch.interfaces.get_all:
  load:
    cisco_switch: cisco_switch
  rescue:

    # Catch DNS error
    - ppa.ui.output_error:
        text: Failed to resolve switch DNS address '{{ cisco_switch.address }}'
      when: "Name does not resolve" in rescue.error
    - exit:
        exit_code: 1
      when: "Name does not resolve" in rescue.error

    # Catch other errors
    - ppa.ui.output_error:
        text: Failed to connect to the switch. Please view the logs for more information.
    - exit:
        exit_code: 2