Event-Driven Ansible with a minimal example

Event-Driven Ansible is here and it opens a whole new world of possibilities for working with Ansible. This article gives an introduction to it and shows a minimal example.

What is Event-Driven Ansible?

Event-Driven Ansible is a new way of working with Ansible based on events. When a specific event occurs a corresponding action is triggered. This allows for immediate and automated response to issues or unexpected occurrences. It is currently available as a developer preview.

How it Works

The information about which events should be monitored and what actions should be taken are included in a so-called “Ansible Rulebook”.

This is a file in YAML format which should include the following fields.

sources

This is a list of possible sources from which events can be gathered. At the moment there are already a few sources available. For example the webhook source plugin provides a webhook which can be triggered from any application. The kafka plugin allows to receive events via a kafka topic. You can find the current list of supported sources here.

rules

Rules describe what actions should be taken depending on specific events. Some of the possible actions are: run_playbook, run_job_template, run_workflow_template, and many more. You can find a complete list here.

A rulebook is started with the ansible-rulebook CLI tool, available through pip. Alternatively, for customers of the Ansible Automation Platform, there is also the possibility of installing the EDA controller: a web UI for Event-Driven Ansible.

Example

Let’s have a look at a minimal example which demonstrates how Event-Driven Ansible works. We imagine a situation in which we have a webserver running and want to monitor it. We can do that with the following rulebook:

# check_url_rulebook.yml
---
- name: Check webserver
  hosts: all
  sources:
    - ansible.eda.url_check:
        urls:
          - https://<webserver_fqdn>
        delay: 10
  rules:
    - name: Restart Nginx
      condition: event.url_check.status == "down"
      action:
        run_playbook:
          name: atix.eda.restart_nginx

This rulebook uses the url_check plugin to query the webpage at https://<webserver_fqdn> every 10 seconds. There is only one rule. When the URL check returns a status of down, an Ansible playbook is automatically started. In this case, the Playbook started is installed under a private collection, atix.eda, and simply tries to restart the nginx service:

# restart_nginx.yml
---
- hosts: all
  gather_facts: false
  tasks:
    - name: Restart Nginx
      ansible.builtin.service:
        name: nginx
        state: restarted
      become: true

We can start monitoring the webserver with this command:

ansible-rulebook --rulebook check_url_rulebook.yml -i inventory.yml --verbose

Note that we must also pass an inventory file, inventory.yml, containing the hosts to be addresssed by the atix.eda.restart_nginx playbook. In this case, the inventory contains only one host, the webserver.

The above command runs in the foreground and listens for events.

When it hasn't received an event yet, the output looks like this:

2023-11-29 13:53:07,183 - ansible_rulebook.rule_set_runner - INFO - Waiting for actions on events from Check url
2023-11-29 13:53:07 183 [drools-async-evaluator-thread] INFO org.drools.ansible.rulebook.integration.api.io.RuleExecutorChannel - Async channel connected
2023-11-29 13:53:07,184 - ansible_rulebook.rule_set_runner - INFO - Waiting for events, ruleset: Check url

Now, if we stop the webserver by hand, we will see first that the event is registered:

2023-11-29 13:54:37 407 [main] INFO org.drools.ansible.rulebook.integration.api.rulesengine.RegisterOnlyAgendaFilter - Activation of effective rule "Restart Nginx" with facts: {m={url_check={url=https://<webserver_fqdn>, status=down, error_msg=Cannot connect to host <webserver_fqdn> ssl:default [Connect call failed ('<webserver_ip>', 443)]}, meta={source={name=ansible.eda.url_check, type=ansible.eda.url_check}, received_at=2023-11-29T13:54:37.366718Z, uuid=709d45b8-803a-48e2-ad17-99d993c6e957}}}
2023-11-29 13:54:37,419 - ansible_rulebook.rule_generator - INFO - calling Restart Nginx

and then that the corresponding playbook is started:

2023-11-29 13:54:37,423 - ansible_rulebook.action.run_playbook - INFO - ruleset: Check url, rule: Restart Nginx
2023-11-29 13:54:38,425 - ansible_rulebook.action.run_playbook - INFO - Calling Ansible runner

PLAY [all] *********************************************************************

TASK [Restart Nginx] ***********************************************************
changed: [<webserver_fqdn>]

PLAY RECAP *********************************************************************
<webserver_fqdn>         : ok=1    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0   
2023-11-29 13:54:44,628 - ansible_rulebook.action.runner - INFO - Ansible runner Queue task cancelled

Conclusion

Event-Driven Ansible has the potential to revolutionize the way of dealing with issues. The project is still in its early stages. Let us hope that new exciting event sources are added in the coming months.