What is an Ansible Rulebook?

An Ansible® Rulebook is a set of conditional rules that Event-Driven Ansible uses to perform IT actions in an event-driven automation model. Rulebooks are the means by which users tell Event-Driven Ansible which source to monitor for an event and—when that event occurs—what to do when certain conditions are met.

Rulebooks are written in human-readable YAML—just like Ansible Playbooks—but use if-this-then-that conditional rules to define when an event should trigger an action. Following a rulebook’s instructions, Event-Driven Ansible monitors the target source for the event, recognizes when it happens, and automatically executes the appropriate action. 

Using Ansible Rulebooks, IT teams can codify the decisions they want to be made and design any action they want to be taken when certain conditions are met, so that actions are performed the same way every time. Rulebooks can also initiate existing Ansible Playbooks when conditions are met, extending the value of trusted playbooks that teams have built and enhanced over time. 

By building their knowledge into rulebooks, teams can use Event-Driven Ansible to minimize errors caused by tired staff performing repetitive tasks—and build more efficient, consistent IT processes.

Event-Driven Ansible provides the event-handling capability needed to automate time-consuming tasks and respond to changing conditions in any IT domain. It can process events containing discrete intelligence about conditions in the IT environment, determine the appropriate response to the event, then execute automated actions to address or remediate the event. Event-Driven Ansible can be used to automate IT service management tasks—such as ticket enhancement, remediation, and user management—and a variety of other tasks across an IT environment.

For example, let’s say your observability tool—the event source—is watching network routers and discovers that a router is not responding, recognizing this as an event. Event-Driven Ansible will receive this event, feed the event data through the rulebook’s conditions, and match the event with your desired action—which could be re-applying a configuration, resetting the router, creating a service ticket, or rerouting traffic. Following the rulebook’s instructions, Event-Driven Ansible can trigger the action to reset the router, restoring it to normal function. This can happen at any time—even at 2 AM, while the network engineer stays asleep.

Event-Driven Ansible’s flexibility is enabled by Ansible Rulebooks, which connect sources of events with corresponding actions via rules.

Learn more about Event-Driven Ansible

Ansible Rulebooks contain the source of the event and conditional instructions—the rules—that specify which actions to perform when a certain condition is met. A rule includes a single condition and its corresponding action. A ruleset is a group of multiple rules and actions. Rulebooks can include multiple rulesets.

Rulebooks are designed to be flexible. They can:

• Monitor one source—or multiple sources. 
• Include one rule—or multiple rules.
• Trigger one action—or multiple actions. 

This flexibility of sources, rules, and actions is built into Event-Driven Ansible so that users can set up whatever actions they desire when specific IT conditions are present.

Watch a quick overview of rulebooks

The first part of a rulebook defines the source or sources you want to monitor for events. Event-Driven Ansible relies on intelligent event sources—like external observation tools and applications—to identify events and gather data about them. Event Source Plugins are used to connect Event-Driven Ansible to these sources to listen for events. 

The ansible.eda Red Hat® Ansible Certified Content Collection contains a number of pre-built Event Source Plugins that can be used to get started with Event-Driven Ansible. However, Red Hat encourages partners and vendors to provide custom plugins designed specifically for their technology, to simplify the integration process and make it easier to get more value from event data.

Ansible.eda certified content plugins

By using Event Source Plugins from the ansible.eda collection, users can quickly start processing events. These source plugins allow Event-Driven Ansible to listen to events, which it can then process with a rulebook's conditional logic to determine which action should be taken. If an event doesn’t meet the rulebook’s conditions, Event-Driven Ansible won’t trigger an action and the event will be discarded. 

Some of the common source plugins found in the ansible.eda collection are webhooks, Kafka, and Prometheus Alertmanager. These cater to generic webhooks that can come from multiple systems and tools, messaging queues, and alerts from enterprise event-monitoring systems like Prometheus. 

In addition to these plugins, Red Hat partners provide additional certified Event Source Plugins which are tailored more specifically for their technologies and solutions. These plugins may include additional functionality for Event-Driven Ansible to better work with these partner technologies. Users can also create their own source plugins for homegrown sources of events.

For example, if you have a network switch and want to know only when a port goes down, a partner can build a plugin that specifies exactly what Event-Driven Ansible should be listening for on the switch. Using this partner plugin, you won't be bombarded with irrelevant information about everything that happens with the switch, 24/7. The certified plugin might deliver just the device host name, the issue, and an incident number, whereas a generic plugin like a webhook might include additional details like sender name, URL, or other data that isn’t relevant to the troubleshooting action.

Once a source plugin has detected an event and delivered information about it, Event-Driven Ansible filters that data through the rulebook’s conditional rules to determine which actions to take. Rules are flexible, if-this-then-that scenarios that define which steps to perform when event data meets certain conditions. 

For example, if the source plugin is monitoring ports on a network router, the rules might dictate: if the port goes down and is unresponsive for 5 minutes, restart the router. If the event data is filtered through the rules and doesn’t meet the conditions, no action will be taken. 

Rulebooks can:

• Contain one or multiple rules. 
• Include one condition, multiple conditions that all need to match the event status, or multiple conditions of which only one needs to match. 
• Support all traditional mathematical operators, like =, ≠, >, and <.
• Support integers, strings, booleans (like and, or, and not), floats, and null condition data types. 

For example, if you’re evaluating a single event and trying to match multiple conditions, you can use the boolean and—this means that each of these conditions will need to be met before the action is triggered.
 

name: Combining ‘and’ operators
condition: event.version == "2.0" and event.name == "test" and event.alert_count > 10
action:
  debug:

If you are monitoring multiple events and trying to match multiple conditions, you can use all—this means that each of the conditions need to be met before the condition is considered a match. Because these conditions are related to multiple events, the conditions are listed on separate lines.
 

name: Condition using both a fact and an event
condition:
  all:
    - fact.meta.hosts == "localhost"
    - event.target_os == "windows"
action:
  debug:

By using any, if any of the conditions are met, the condition is considered a match and the action triggers. As with the above example, this code is looking at multiple events, so the conditions are listed on separate lines.
 

name: Any condition can match
condition:
  any:
    - event.target_os == "linux"
    - event.target_os == "windows"
action:
  debug:

Note: in the above examples, the debug action would print the event information so that you can see this data displayed in Event-Driven Ansible.

When event data meets a rulebook’s conditions, Event-Driven Ansible triggers the specified action or actions. 

Some common actions include:

• Run_playbook runs an existing Ansible Playbook that you’ve already designed to automate certain actions, like troubleshooting a server. 
• Run_job_template runs a job template via the automation controller in Red Hat Ansible Automation Platform. Since you’re running the template within Ansible Automation Platform, you get the associated benefits like inventory management, user and access controls, and analytics about the completed action. 
• Run_module runs an existing Ansible module, which executes a more specific, targeted action, for when you don’t want to run an entire playbook.
• Post_event allows you to post an event to a running ruleset. This is typically included after the run_playbook or run_job_template action, and provides the ability to feed information about the action’s result back into Event-Driven Ansible.
• Set_fact records specific data about an event or action so that it can be fed back into Event-Driven Ansible and used for other actions. Event data is fleeting, transient data—setting facts allows you to save specific information about events and make that data persistent.
• Debug is similar to the debug found in Ansible Playbooks. If no arguments are provided, it will print the matching event payload and any additional important information.

Read the rulebook docs for more technical details

This section includes a couple of simple examples of Ansible Rulebooks. It’s ok if some of the details don’t stick—these examples are meant to give you a basic idea of how sources, rules, and actions work together in the context of a complete rulebook. 

This first example is dedicated to a fairly straightforward, single action. Following the below code, if there is an outage in the event source, Event-Driven Ansible will run a remediation playbook.
 

rules:
  - name: An automatic remediation rule
    condition: event.outage == true
    action:
      run_playbook:
        name: remediate_outage.yml

In the below example of a slightly more complicated rulebook, we define the event source as the Dynatrace certified source plugin. The rules define conditions which we are listening for—in this case, they specify some application and hardware utilization conditions.
 

---
- name: Listen for events on a webhook
  hosts: all
  sources:
    - dynatrace.eda.dt_esa_api:
        dt_api_host: "https://abc.live.dynatrace.com"
        dt_api_token: "asjfsjkfjfjh"
        delay: 60 

  Rules:

    - name: Problem payload Dynatrace for CPU issue
      condition: event.payload.problemTitle contains "CPU saturation"
      action:
        run_job_template:
          name: "Remediate CPU saturation issue"
          organization: "Default"

    - name: Problem payload Dynatrace for App Failure rate increase issue
      condition: event.payload.problemTitle contains "Failure rate increase"
      action:
        run_job_template:
          name: "Remediate Application issue"
          organization: "Default"

    - name: Update comments in Dynatrace
      condition: 
        all: 
          - event.status == "OPEN"
      action:
        run_playbook:
          name: dt-update-comments.yml

The event payload that we receive will be checked for the “CPU saturation” or “Failure rate increase” messages. If these messages are in the payload, Event-Driven Ansible will match these events to remediation playbooks or job templates to resolve the issue.

Watch a more in-depth demo of Ansible Rulebooks

Red Hat Ansible Automation Platform uses human-readable YAML language so users can share, vet, and manage automation content. It includes all the tools needed to implement enterprise-wide automation, including Event-Driven Ansible, playbooks, and analytics. And it allows your teams to centralize and control your IT infrastructure with a visual dashboard, role-based access control, and more features that will help you reduce operational complexity.

With a Red Hat subscription, you get certified content from our robust partner ecosystem, access to hosted management services, and life cycle technical support to scale automation across your organization. And you’ll get expert knowledge gained from our success with thousands of customers.

The introduction of Red Hat Ansible Lightspeed with IBM watsonx Code Assistant makes Ansible more accessible to beginners and helps experienced Ansible creators be more productive, efficient, and error-free. Developers can enter a task request in plain English, and Ansible Lightspeed interacts with IBM watsonx foundation models to generate code recommendations that are then used to create Ansible Playbooks.

Learn more about Ansible Automation Platform