DEV Community

Cover image for Event-Driven Ansible with a minimal example

Posted on • Updated on

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.


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 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.


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
    - ansible.eda.url_check:
          - https://<webserver_fqdn>
        delay: 10
    - name: Restart Nginx
      condition: event.url_check.status == "down"
          name: atix.eda.restart_nginx
Enter fullscreen mode Exit fullscreen mode

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
    - name: Restart Nginx
        name: nginx
        state: restarted
      become: true
Enter fullscreen mode Exit fullscreen mode

We can start monitoring the webserver with this command:

ansible-rulebook --rulebook check_url_rulebook.yml -i inventory.yml --verbose
Enter fullscreen mode Exit fullscreen mode

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 - Async channel connected
2023-11-29 13:53:07,184 - ansible_rulebook.rule_set_runner - INFO - Waiting for events, ruleset: Check url
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

Enter fullscreen mode Exit fullscreen mode


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.

Top comments (0)