Red Hat Insights Collection for Event-Driven Ansible

Event-Driven Ansible became generally available in Ansible Automation Platform 2.4. As part of the release, Red Hat Insights and Ansible teams collaborated to implement and certify a Red Hat Insights collection integrating Insights events as a source of events for Ansible Automation Platform. This provides a consistent way to receive and handle events triggered from Insights to drive and track automation within the Ansible Automation Platform. The collection is available for installation on Ansible automation hub.

In this article, we explore how to get, configure and use the Red Hat Insights collection for Event-Driven Ansible, and provide an end-to-end example of an automation flow using Ansible Automation Platform and its Event-Driven Ansible functionality. Our goal is to automate the creation of a ServiceNow incident ticket with all relevant information when malware is detected by Insights on one of our Red Hat Enterprise Linux (RHEL) systems. We show how we can track and audit all automation from the Event-Driven Ansible controller as part of Ansible Automation Platform.

Introducing a new certified  collection for Event-Driven Ansible

In a previous article, we looked at exposing and consuming Insights events to drive automation with Event-Driven Ansible. We validated that events triggered from Insights can successfully be received and handled by an Ansible Rulebook and processed according to defined automation actions. This simple example demonstrated the possibility of using Insights as a source of events for Event-Driven Ansible, and handling automation according to event data.

Meanwhile, we worked on implementing and certifying an Insights collection as part of the ecosystem of Ansible Content Collection. The collection lays out a jumpstart for integrating Insights events in new automation projects, and provides Red Hat Ansible Certified and Ansible validated content for best practice implementation. 

The collection provides a new source plugin (redhat.insights_eda.insights) supporting secured connection and authentication using Basic Auth (not recommended for production) and Bearer Token. Examples of using the event source in a rulebook and handling Insights events data are provided as templates for getting started, as well as simple playbooks for automation.

The Red Hat Ansible Certified Collection is available and supported on Ansible automation hub. You can also use the community version to access the latest experimentations on Ansible Galaxy, where contributions are welcome.

In the following sections, we will use the Red Hat Ansible Certified Collection in our example.

Building a custom decision environment using the Insights collection for Event-Driven Ansible

In our example, we use a third party event source plugin that is not available in the default decision environment provided in Ansible Automation Platform 2.4. As a result, we need to build and provide Ansible Automation Platform with our own custom decision environment for Event-Driven Ansible.

We can build such a custom environment by following the suggestions provided in the knowledge base article and documentation. It consists of a de-minimal decision environment as base image, with the addition of the required collections: ansible.eda, redhat.insights_eda.insights.

Here is the Ansible builder definition file used in our example:

---
version: 3

images:
  base_image:
    name: 'registry.redhat.io/ansible-automation-platform-24/de-supported-rhel8'

dependencies:
  galaxy:
    collections:
      - name: ansible.eda
      - name: community.general
      - name: redhat.insights_eda
      - name: servicenow.itsm
    system:
pkgconf-pkg-config [platform:rpm]
systemd-devel [platform:rpm]
gcc [platform:rpm]
python39-devel [platform:rpm]

Additional information about building custom decision environments can be found in the Ansible Rulebook: Decision Environments and Ansible Builder: Execution Environment Definition documentation.

Running an end-to-end example with Insights event triggers

Once this custom decision environment is built and available with the required collections, we can use them in a rulebook that allows us to connect our event source (redhat.insights_eda.insights) to event handlers according to conditions. Handlers can launch playbooks or automation controller’s job templates based on rules defined to match data from received events.

Here is the Ansible Rulebook definition used in our example:

---
- name: Listen for Red Hat Insights events
  hosts: localhost
  sources:
    - redhat.insights_eda.insights:
        host: 0.0.0.0
        port: 5000
  rules:
    - name: Match Malware detected-malware event
      condition: 
        event.payload.application == "malware-detection"
        and event.payload.event_type == "detected-malware"
      action:
        run_job_template:
          name: "handle-malware-detection"
          organization: Default
          job_args: 
            extra_vars: "{{ event.payload }}"

We are only interested in the detected-malware event types triggered by the malware-detection application from Insights. The condition rule in our example above looks for these values in the event’s payload. Once a match is found, we take the action of running a Job Template called handle-malware-detection. This job template was previously defined in our Ansible Automation Platform environment, and consists of creating an incident ticket in a ServiceNow environment and passing all details collected from the received event.

Note that the rulebook must be located in a GitHub repository with a specific project structure in order to be imported in an Event-Driven Ansible controller. Our example can be found in this repository.

More information about Ansible Rulebooks can be found in the documentation.

Here is the playbook associated with the handle-malware-detection job template. Our goal is to extract data from the incoming Insights event and use it as part of the required fields for creating an Incident ticket in our ServiceNow instance.

---
- name: Create Malware Incident
  hosts: localhost
  gather_facts: no
  tasks:
  - name: Create a Malware incident
    servicenow.itsm.incident:
      instance:
        host: <https://instance_id.service-now.com>
        username: <username>
        password: <password>
      state: new
      short_description: "{{ ansible_eda.event.payload.application | upper }}: {{ item.payload.matched_rules | default('Malware') }}"
      description: |-
        Account id: {{ ansible_eda.event.payload.account_id | default("") }}
        Affected system: {{ ansible_eda.event.payload.context.display_name | default("") }}
        Event type: {{ ansible_eda.event.payload.event_type | default("") }}
        Matched rules: {{ item.payload.matched_rules | default("") }} 
        Bundle: {{ ansible_eda.event.payload.bundle | default("") }}
        Created at: {{ ansible_eda.event.payload.timestamp | default("") }}
    loop: "{{ ansible_eda.event.payload.events | default([]) }}"

Note that we use the servicenow.itsm certified collection for integrating with ServiceNow in our example. More information about this collection can be found on Ansible automation hub.

Configuring our rulebook in the Event-Driven Ansible controller

At this point, we can follow the Event-Driven Ansible controller user guide to configure our project and decision environment for our example.

First, we create a new Project making sure we select Git for the SCM type, and provide required credentials.

Next, we create a new Decision Environment making sure we select the custom image we created earlier for including ansible.eda and redhat.insights_eda.insights collections.

Because our rulebook action is to launch a job template in automation controller, we must create a Controller Token that can be used to authenticate our Event-Driven Ansible controller service account (detailed in this documentation). 

You can create your token in automation controller using the documentation found here and depicted below.  

1. Create the application in automation controller to represent the Event-Driven Ansible controller

 

2. Create a Normal User in automation controller to represent the eda_service_account user from Event-Driven Ansible controller

3. Be sure to log out of the admin account in automation controller and log back in as the Normal User you just created to generate the token (you must be logged in as the user you are generating the token for).
 

Configure our job template that creates the ServiceNow incident 

Many of the steps required to create a job template have likely already been performed in your environment, so we won’t go into great detail here on how to do that. The high-level steps to be completed are: 

• Create and or synchronize the Project that contains the playbook that will create the ServiceNow incident.
• Make sure you have Credentials to authenticate into your ServiceNow instance.
• Note that there is no need for a custom execution environment for the job template as servicenow.itsm collection is already present in the installed Default execution environment.
• You can use the Demo Inventory that is installed with automation controller that represents the localhost.
• Important: you must select “Prompt on launch” for the Variables field/section. This allows for the job template to ingest the extra_vars: "{{ event.payload }}" passed from the rulebook.

Activate the rulebook in Event-Driven Ansible controller

Finally, we must create a rulebook activation. In this step, we select the project we created and locate the corresponding rulebook (our rulebook should automatically appear in the list as long as the project structure is correct in our repository). We select the custom decision environment previously created as it includes all collection dependencies required. The policy can be restarted whenever the rulebook finishes, and we select Always as restart policy.

Prepare Insights to publish events to the Event-Driven Ansible controller

In your Red Hat Insights environment, the Event-Driven Ansible integration and appropriate notifications must be configured for the account triggering Insights events. Our previous article documents all steps required. Below is a screenshot of our configuration where eda.controller.instance needs replacement with your Event-Driven Ansible controller fully qualified domain name (fqdn) accessible on port 5000:

Monitoring executions from Event-Driven Ansible controller

Projects, decision environments and rulebook activations can be monitored from the Event-Driven Ansible controller dashboard. This provides a quick overview of their state, as well as an audit of the latest runs. This is a great starting point to manage, visualize and dig in a particular run to troubleshoot failures or validate successes.

As an example, we can list previous successful rules triggered according to our condition on Insights events. In the following screenshot, we validate that our Match Malware detected-malware event defined in our rulebook triggered.

Diving further into a specific rule, we can display additional details, as well as retrieve the event received from Insights and look at its data. Note that this can be very useful when building new rulebooks and playbooks to validate the data fields provided as part of incoming events. 

From the actions tab, we also validate that our job template was launched, according to our rulebook definition for actions.

By following the run_job_template link in the Actions screen above, you can be taken directly to the automation controller job associated with this event action:

In turn, the playbook associated with the job template was launched and a ServiceNow incident ticket was created passing all data from the event according to the playbook. We can validate the run in Ansible Automation Platform and the ticket creation in our ServiceNow instance.

Summary

Event-Driven Ansible provides event-handling capability required for integrating applications and driving operational workflows. In this article, we explored how Insights can act as a source of events for Event-Driven Ansible. We used our Insights for Event-Driven Ansible certified collection for this integration, and showed how it can be used to quickly get started receiving and handling Insights events.

We hope this article is useful in providing a concrete end-to-end example of the use of the Insights collection for Event-Driven Ansible and utilizing Insights event data as part of your existing organization workflows. We are always looking for additional use cases and any feedback that can help the product grow. Contributions to our collection via Ansible Galaxy or to our example on GitHub are welcome. 

I would also like to thank Michael Bredemeier, senior specialist solutions architect at Red Hat, for his Ansible expertise and assistance throughout all aspects of this exercise, as well as for his help in writing this article.

Call to Action

• Check out the Getting Started with Event-Driven Ansible training.
• Visit the Event-Driven Ansible web page.
• Check out the Event-Driven Ansible playlist on YouTube. 
• Try Ansible Automation Platform free for 60 days.