Event-Driven Ansible is an open source developer preview designed to flexibly enable teams to create event-driven automation scenarios across various IT domains (network, DevOps, security, CloudOps, infrastructure, and more).
This article aims to teach you how to install the ansible-rulebook command-line interface (CLI) tools and use them when executing the rulebooks. Our rulebook will be used to create a conditional event, so whenever that event occurs, it will trigger and execute the playbook that we defined in action. This is the first step to event-driven development.
ansible-rulebook CLI setup
To install the ansible-rulebook CLI on your local system. Make sure you have installed all the components listed in the requirements section before starting the installation.
Requirements
- Python >= 3.8
- Python 3 pip
The following instructions will guide you through the installation of Java and other components. Depending on your Linux distribution, you can follow the following commands.
On Red Hat Enterprise Linux (RHEL), CentOS, Fedora, or Rocky Linux-like systems:
dnf --assumeyes install java-17-openjdk python3-pip
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk
pip3 install ansible ansible-rulebook ansible-runner
On Ubuntu or Debian systems:
apt-get --assume-yes install openjdk-17-jdk python3-pip
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$PATH:~/.local/bin
pip3 install ansible ansible-rulebook ansible-runner
After installation of ansible, ansible-runner and ansible-rulebook, we have to install the required collection so we can execute the rulebook successfully. To install the following collection by using ansible-galaxy:
ansible-galaxy collection install ansible.eda
Once the collection is installed, a couple more dependencies are still left. For those, use the below command to install them:
ansible-playbook -i localhost, -c local ansible.eda.install_rulebook_cli
Check ansible-rulebook CLI successfully installed.
$ ansible-rulebook
usage: ansible-rulebook [-h] [--rulebook RULEBOOK] [--vars VARS] [--env-vars ENV_VARS] [--debug] [--verbose] [--version] [--redis-host-name REDIS_HOST_NAME] [--redis-port REDIS_PORT] [-S SOURCE_DIR] [-i INVENTORY] [--websocket-address WEBSOCKET_ADDRESS] [--id ID] [--worker] [--project-tarball PROJECT_TARBALL] [--controller-url CONTROLLER_URL] [--controller-token CONTROLLER_TOKEN] [--print-events]
Event-driven rulebook
The rulebook, shown below, is a simple example of webhook based event-driven. In this rulebook we are going to listen on port 5000. When a request comes on port 5000, the rulebook gets triggered and runs as per logic written in the rule.
This GitHub repository contains the following rulebooks and other files.
---
- name: Listen for events on a webhook
hosts: localhost
## Define our source for events
sources:
- ansible.eda.webhook:
host: 0.0.0.0
port: 5000
## Define the conditions we are looking for
rules:
- name: Say Hello
condition: event.payload.message == "Ansible is super cool"
## Define the action we should take should the condition be met
action:
run_playbook:
name: say-what.yml
Create an Inventory.yml inventory file where we can define the host where we can launch the rulebook.
localhost
In the above rulebook, you might notice that we have defined one playbook in the action section. The event condition must be true. In that playbook, you can define any task which you want to run on.
say-what.yml
---
- name: say thanks
hosts: localhost
gather_facts: false
tasks:
- debug:
msg: "Thank you, {{ event.sender | default('my friend') }}!"
We are ready to execute the rulebook using ansible-rulebook.
ansible-rulebook --rulebook hit_try.yaml -i inventory.yaml --verbose
2023-02-22 17:39:02,332 - ansible_rulebook.app - INFO - Starting sources
2023-02-22 17:39:02,332 - ansible_rulebook.app - INFO - Starting rules
2023-02-22 17:39:02,332 - ansible_rulebook.engine - INFO - run_ruleset
2023-02-22 17:39:02,744 - ansible_rulebook.engine - INFO - ruleset define: {"name": "Listen for events on a webhook", "hosts": ["localhost"], "sources": [{"EventSource": {"name": "ansible.eda.webhook", "source_name": "ansible.eda.webhook", "source_args": {"host": "0.0.0.0", "port": 5000},say-what.yml
Now the rulebook started listening on port 5000.
NOTE: After execution of the rulebook, make sure you don’t interrupt the terminal. Switch to the second tab.
Testing
Open the other terminal and execute the following command.
curl -H 'Content-Type: application/json' -d "{\"message\": \"Ansible is alright\"}" 127.0.0.1:5000/endpoint
After executing the first command check back the terminal 1 you will notice nothing is happening. The reason is the conditions defined in the playbook are not matched.
Go back to terminal 2 again, hit the curl command mentioned below and check the logs or results of the rulebook on terminal 1.
curl -H 'Content-Type: application/json' -d "{\"message\": \"Ansible is super cool\"}" 127.0.0.1:5000/endpoint
2023-02-22 17:39:36,818 - ansible_rulebook.builtin - INFO - ruleset: Listen for events on a webhook, rule: Say Hello
2023-02-22 17:39:36,818 - ansible_rulebook.builtin - INFO - Calling Ansible runner
PLAY [say thanks] **************************************************************
TASK [debug] *******************************************************************
ok: [localhost] => {
"msg": "Thank you, my friend!"
}
PLAY RECAP *********************************************************************
localhost : ok=1 changed=0 unreachable=0 failed=0 skipped=0 rescued=0 ignored=0
Summary
In this article, we learned about how to install the ansible-rulebook CLI on a local machine and executed one sample rulebook that listens to the events on port 5000. When someone hits a request on that port, the rulebook will trigger but unless the condition is not true it will not execute the playbook from the action.
Get started with the Ansible Automation Platform by exploring interactive labs. You can download Ansible Automation Platform for personal use at no cost.
