Introduction to Event-Driven Ansible

You need to configure the rule engine with the URL and authentication credentials for your automation controller if you use the run_job_template or run_workflow_template actions. For example, you might change the preceding Ansible Rulebook to run a job template named Update packages on prod servers in the Production organization on your automation controller:

---
- name: Listen for events on a webhook
  hosts: host.lab.example.com

  sources:
    - ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000

  rules:
    - name: Update prod servers
      condition: event.payload.message == "force-update"
      action:
        run_job_template: 
          name: Update packages on prod servers 
          organization: Production 

The URL and authentication token for the automation controller must be configured in the rule engine. If you are using the ansible-rulebook command as your rule engine, it has environment variables or the --controller-url and --controller-token command-line options for this purpose. How to use the ansible-rulebook command to test rulebooks is covered in more detail at the end of this section.

You can use the ansible.eda.webhook event source to create a webhook to which a remote service can send events that Event-Driven Ansible then acts upon.

The extensions/eda/rulebooks/git-hook-deploy-rules.yml rulebook provides an example that runs a playbook and prints to stdout when an incoming request to the webhook contains specific content:

---
- name: Local Deploy Git Hook Rules
  hosts: all
  sources:
    - ansible.eda.webhook:
        port: 5001
  rules:
    - name: run tests 1 
      condition: event.payload.repo == "{{repo}}" 
      action:
        run_playbook: 
          name: ansible.eda.continuous_integration 
          var_root: payload 
          post_events: true 
    - name: print output 
      condition: event.output is defined
      action:
        print_event: 
          var_root: output
...

This sample rulebook creates a socket on TCP port 5001 to listen to incoming web requests, and contains two rules.

The following table lists the mandatory arguments for the ansible.eda.webhook event source plug-in.

Additional arguments are available to configure a TLS certificate or client authentication for the webhook.

The following example rulebook uses the ansible.eda.webhook event source plug-in:

---
- name: Listen for events on a webhook
  hosts: all

  sources:
    - name: Match events posted to port 5000
      ansible.eda.webhook:
        host: 192.168.5.10
        port: 5000

  rules:
    - name: Run actions if the webhook has a payload
      condition: event.payload is defined
      actions: 
        - run_module:
            name: ansible.builtin.debug
            module_args:
              msg: "Webhook received"
        - run_playbook:
            name: log_write.yml
            extra_vars:
              message: "Message 001"

Event-Driven Ansible can use the ansible.eda.journald event source plug-in to react to log events recorded by the local system journal.

The extensions/eda/rulebooks/journald_events.yml rulebook provides an example of printing messages related to sudo events:

---
- name: Journald events
  hosts: all
  sources:
    - name: Match all messages
      ansible.eda.journald:
        match: "ALL"
  rules:
    - name: Print sudo journald event message
      condition: event.journald._comm == 'sudo'
      action:
        print_event:
          pretty: true
          var_root:
            journald.message: journald.message
...

This rulebook tests all journal messages and then has a rule that displays the message for any event that matches the sudo command.

Rather than processing all journal events, you might only process specific journal events. The top of the extensions/eda/plugins/event_source/journald.py file displays examples of other matching criteria:

...output omitted...
Examples:
--------
    - name: Return severity 6 messages
      ansible.eda.journald:
        match: "PRIORITY=6"

    - name: Return messages when sudo is used
      ansible.eda.journald:
        match: "_EXE=/usr/bin/sudo"

...output omitted...

The journalctl command with the -o verbose option displays log entries with all fields. You might use this information to help construct rulebook conditions.

For example, the following command displays all journal fields for log entries related to the SSHD service:

[user@host ~]$ sudo journalctl _SYSTEMD_UNIT=sshd.service -o verbose
Mon 2024-01-22 13:41:33.974742 UTC [s=e9ee3399119d415eafd57bbc7b04fc83;i=219;b=da5b9bb0c9cc461da9d89ae42be98731;m=c7c33f;t=60f88f>
    PRIORITY=6
    _BOOT_ID=da5b9bb0c9cc461da9d89ae42be98731
    _MACHINE_ID=8317e4e5bd33466ebe75abdc86a14055
    _HOSTNAME=workstation
    _RUNTIME_SCOPE=system
    _UID=0
    _GID=0
    _SYSTEMD_SLICE=system.slice
    _CAP_EFFECTIVE=1ffffffffff
    _TRANSPORT=syslog
    SYSLOG_FACILITY=10
    SYSLOG_TIMESTAMP=Jan 22 13:41:33
    SYSLOG_IDENTIFIER=sshd
    SYSLOG_PID=1355
    MESSAGE=Server listening on 0.0.0.0 port 22.
...output omitted...

The following sample rulebook prints journal events that match the workstation host where the sshd service was either reloaded or restarted:

---
- name: Journald events
  hosts: all
  sources:
    - name: Match SSHD messages
      ansible.eda.journald:
        match: "_SYSTEMD_UNIT=sshd.service" 
  rules:
    - name: Print SSHD SIGHUP and signal 15 events
      condition: > 
        ((event.journald.message == 'Received SIGHUP; restarting.') or
        (event.journald.message == 'Received signal 15; terminating.') and
        (event.journald._hostname == 'workstation'))
      action:
        print_event:
          pretty: true

Event-Driven Ansible can react to the status of a URL by using the ansible.eda.url_check event source plug-in.

The extensions/eda/rulebooks/ directory does not contain an example rulebook for this event source, but the extensions/eda/plugins/event_source/url_check.py plug-in file contains code similar to the following example near the top of the file:

...output omitted...
    - name: check web server
      ansible.eda.url_check:
        urls:
          - http://192.0.2.56:8000/docs
        delay: 10
...output omitted...

The previous example polls http://192.0.2.56:8000/docs every 10 seconds and sends the status of the URL as an event. The event returns the status, status_code, and url keys with their corresponding values.

The following rulebook uses the ansible.eda.url_check event source plug-in:

---
- name: Listen for URL events
  hosts: all

  sources:
    - name: Match events from web application 
      ansible.eda.url_check:
        urls:
          - http://webapp.example.lab.com
        delay: 60

  rules:
    - name: Web application is up 
      condition: event.url_check.status == "up"
      action:
        run_module:
          name: ansible.builtin.debug
          module_args:
            msg: "Web application is up"

    - name: Web application error 
      condition: event.url_check.status_code == 500
      action:
        run_playbook:
          name: redeploy_webapp.yml

    - name: Web application is down 
      condition: event.url_check.status == "down"
      action:
        run_playbook:
          name: restart_services.yml