Event-Driven Ansible controller user guide

Red Hat Ansible Automation Platform 2.4

Learn to configure and use Event-Driven Ansible controller to enhance and expand automation

Red Hat Customer Content Services

Abstract

This guide helps you configure your Event-Driven Ansible controller to set up new projects, decision environments, tokens to authenticate to Ansible Automation Platform Controller, and rulebook activation.

Preface

Event-Driven Ansible controller is a new way to enhance and expand automation by improving IT speed and agility while enabling consistency and resilience. Developed by Red Hat, this feature is designed for simplicity and flexibility.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Providing feedback on Red Hat documentation

We appreciate your feedback on our technical content and encourage you to tell us what you think. If you’d like to add comments, provide insights, correct a typo, or even ask a question, you can do so directly in the documentation.

Note

You must have a Red Hat account and be logged in to the customer portal.

To submit documentation feedback from the customer portal, do the following:

  1. Select the Multi-page HTML format.
  2. Click the Feedback button at the top-right of the document.
  3. Highlight the section of text where you want to provide feedback.
  4. Click the Add Feedback dialog next to your highlighted text.
  5. Enter your feedback in the text box on the right of the page and then click Submit.

We automatically create a tracking issue each time you submit feedback. Open the link that is displayed after you click Submit and start watching the issue or add more comments.

Chapter 1. Event-Driven Ansible controller overview

Event-Driven Ansible is a highly scalable, flexible automation capability that works with event sources such as other software vendors' monitoring tools. These tools watch IT solutions and identify events and automatically implement the documented changes or response in a rulebook to handle that event.

The following procedures form the user configuration:

Chapter 2. Projects

Projects are a logical collection of rulebooks. They must be a git repository and only http protocol is supported. The rulebooks of a project must be located in the /rulebooks folder at the root of the project or at the path defined for Event-Driven Ansible content in Ansible collections: /extensions/eda/rulebooks.

2.1. Setting up a new project

Prerequisites

  • You are logged in to the Event-Driven Ansible controller Dashboard as a Content Consumer.
  • You have set up a credential, if necessary. For more information, refer to the Credentials section of the automation controller documentation.
  • You have an existing repository containing rulebooks that are integrated with playbooks contained in a repository to be used by automation controller.

Procedure

  1. Log in to the Event-Driven Ansible controller Dashboard.
  2. From the navigation panel, select Projects → Create project.

  3. Insert the following:

    Name
    Enter project name.
    Description
    This field is optional.
    SCM type
    Git is the only SCM type available for use.
    SCM URL

    HTTP[S] protocol address of a repository, such as GitHub or GitLab.

    Note

    You cannot edit the SCM URL after you create the project.

    Credential
    This field is optional. This is the token needed to utilize the SCM URL.
  4. Select Create project.

Your project is now created and can be managed in the Projects screen.

After saving the new project, the project’s details page is displayed. From there or the Projects list view, you can edit or delete it.

2.2. Projects list view

On the Projects page, you can view the projects that you have created along with the Status and the Git hash.

Note

If a rulebook changes in source control you can re-sync a project by selecting the sync icon next to the project from the Projects list view. The Git hash updates represent the latest commit on that repository. An activation must be restarted or recreated if you want to use the updated project.

2.3. Editing a project

Procedure

  1. From the Projects list view, select the More Actions icon ⋮ next to the desired project.
  2. Select Edit project.
  3. Enter the required changes and select Save project.
Edit project

2.4. Deleting a project

Procedure

  1. From the Projects list view, select the More Actions icon ⋮ next to the desired project.
  2. Select Delete project.
  3. In the popup window, select Yes, I confirm that I want to delete this project.
  4. Select Delete project.

Chapter 3. Decision environments

Decision environments are a container image to run Ansible rulebooks. They create a common language for communicating automation dependencies, and provide a standard way to build and distribute the automation environment. The default decision environment is found in the Ansible-Rulebook.

To create your own decision environment refer to Building a custom decision environment for Event-Driven Ansible within Ansible Automation Platform.

3.1. Setting up a new decision environment

The following steps describe how to import a decision environment into your Event-Driven Ansible controller Dashboard.

Prerequisites

  • You are logged in to the Event-Driven Ansible controller Dashboard as a Content Consumer.
  • You have set up a credential, if necessary. For more information, refer to the Credentials section of the Automation controller documentation.
  • You have pushed a decision environment image to an image repository or you chose to use the image de-supported provided at registry.redhat.io.

Procedure

  1. Navigate to the Event-Driven Ansible controller Dashboard.
  2. From the navigation panel, select Decision Environments → Create decision environment.

  3. Insert the following:

    Name
    Insert the name.
    Description
    This field is optional.
    Image
    This is the full image location, including the container registry, image name, and version tag.
    Credential
    This field is optional. This is the token needed to utilize the decision environment image.
  4. Select Create decision environment.

Your decision environment is now created and can be managed on the Decision Environments screen.

After saving the new decision environment, the decision environment’s details page is displayed. From there or the Decision Environments list view, you can edit or delete it.

3.2. Building a custom decision environment for Event-Driven Ansible within Ansible Automation Platform

Refer to this section if you need a custom decision environment to provide a custom maintained or third-party event source plugin that is not available in the default decision environment.

Prerequisites

  • Ansible Automation Platform > = 2.4
  • Event-Driven Ansible
  • Ansible Builder > = 3.0

Procedure

  • Add the de-supported decision environment. This image is built from a base image provided by Red Hat called de-minimal.

    Note

    Red Hat recommends using de-minimal as the base image with Ansible Builder to build your custom decision environments.

The following is an example of the Ansible builder definition file using de-minimal as a base image to build a custom decision environment with the ansible.eda collection: 

version: 3

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

dependencies:
  galaxy:
    collections:
      - ansible.eda
  python_interpreter:
    package_system: "python39"

options:
  package_manager_path: /usr/bin/microdnf

Additionally, if other python packages or RPM are needed, you can add the following to a single definition file: 

version: 3

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

dependencies:
  galaxy:
    collections:
      - ansible.eda
  python:
    - six
    - psutil
  system:
    - iputils [platform:rpm]
  python_interpreter:
    package_system: "python39"

options:
  package_manager_path: /usr/bin/microdnf

Chapter 4. Setting up a token

Automation controller must contain a project based on a repository with certain playbooks designed to work with the Event-Driven Ansible rulebooks. Automation controller must also have corresponding job templates set up based on the playbooks in that project.

4.1. Setting up a token to authenticate to Ansible Automation Platform Controller

Prerequisites

  • You are logged in to the Event-Driven Ansible controller Dashboard as a Content Consumer.
  • You have created a user.
  • You can log in to the Event-Driven Ansible controller Dashboard or you are added as a user in the organization.

Procedure

  1. Navigate to the Event-Driven Ansible controller Dashboard.
  2. From the top navigation panel, select your profile.
  3. Go to User details.
  4. Select Controller Tokens → Create controller token.

  5. Insert the following:

    Name
    Insert the name.
    Description
    This field is optional.
    Token

    Create the token in automation controller. For more information on creating the token, refer to the Users - Tokens section of the Automation controller User Guide.

    Note

    The token must be in write-scope.

  6. Select Create controller token.

After saving the new token, you are brought to the Controller Tokens tab where you can delete the token.

Chapter 5. Rulebook activations

A rulebook activation is a process running in the background defined by a decision environment executing a specific rulebook.

5.1. Setting up a rulebook activation

Prerequisites

  • You are logged in to the Event-Driven Ansible controller Dashboard as a Content Consumer.
  • You have set up a project.
  • You have set up a decision environment.
  • You have set up an automation controller token.

Procedure

  1. Navigate to the Event-Driven Ansible controller Dashboard.
  2. From the navigation panel, select Rulebook Activations → Create rulebook activation.

  3. Insert the following:

    Name
    Insert the name.
    Description
    This field is optional.
    Project
    Projects are a logical collection of rulebooks.
    Rulebook
    Rulebooks will be shown according to the project selected.
    Decision environment
    Decision environments are a container image to run Ansible rulebooks.
    Restart policy

    This is a policy to decide when to restart a rulebook.

    • Policies:

      1. Always: Restarts when a rulebook finishes
      2. Never: Never restarts a rulebook when it finishes
      3. On failure: Only restarts when it fails
    Rulebook activation enabled?
    This automatically enables the rulebook activation to run.
    Variables
    The variables for the rulebook are in a JSON/YAML format. The content would be equivalent to the file passed through the --vars flag of ansible-rulebook command.
  4. Select Create rulebook activation.

Your rulebook activation is now created and can be managed in the Rulebook Activations screen.

After saving the new rulebook activation, the rulebook activation’s details page is displayed. From there or the Rulebook Activations list view you can edit or delete it.

5.2. Rulebook activation list view

On the Rulebook Activations page, you can view the rulebook activations that you have created along with the Activation status, Number of rules associated with the rulebook, the Fire count, and Restart count.

If the Activation Status is Running, it means that the rulebook activation is running in the background and executing the required actions according to the rules declared in the rulebook.

You can view more details by selecting the activation from the Rulebook Activations list view.

Rulebook activation][width=25px

For all activations that have run, you can view the Details and History tabs to get more information about what happened.

5.2.1. Viewing activation output

You can view the output of the activations in the History tab.

Procedure

  1. Select the History tab to access the list of all the activation instances. An activation instance represents a single execution of the activation.
  2. Then select the activation instance in question, this will show you the Output produced by that specific execution.
Rulebook activation history

To view events that came in and triggered an action, you can use the Rule Audit section in the Event-Driven Ansible controller Dashboard.

5.3. Enabling and disabling rulebook activations

  1. Select the switch on the row level to enable or disable your chosen rulebook.
  2. In the popup window, select Yes, I confirm that I want to enable/disable these X rulebook activations.
  3. Select Enable/Disable rulebook activation.

5.4. Restarting rulebook activations

Note

You can only restart a rulebook activation if it is currently enabled and the restart policy was set to Always when it was created.

  1. Select the More Actions icon ⋮ next to Rulebook Activation enabled/disabled toggle.
  2. Select Restart rulebook activation.
  3. In the popup window, select Yes, I confirm that I want to restart these X rulebook activations.
  4. Select Restart rulebook activations.

5.5. Deleting rulebook activations

  1. Select the More Actions icon ⋮ next to the Rulebook Activation enabled/disabled toggle.
  2. Select Delete rulebook activation.
  3. In the popup window, select Yes, I confirm that I want to delete these X rulebook activations.
  4. Select Delete rulebook activations.

5.6. Activating webhook rulebooks

In Openshift environments, you can allow webhooks to reach an activation-job-pod over a given port by creating a Route that exposes that rulebook activation’s Kubernetes service.

Prerequisites

  • You have created a rulebook activation in the Event-Driven Ansible controller Dashboard.
Note

The following is an example of rulebook with a given webhook: 

- name: Listen for storage-monitor events
  hosts: all
  sources:
    - ansible.eda.webhook:
        host: 0.0.0.0
        port: 5000
  rules:
    - name: Rule - Print event information
    condition: event.meta.headers is defined
    action:
      run_job_template:
        name: StorageRemediation
        organization: Default
        job_args:
          extra_vars:
             message: from eda
             sleep: 1

Procedure

  1. Create a Route (on OpenShift Container Platform) to expose the service. The following is an example Route for an ansible-rulebook source that expects POST’s on port 5000 on the decision environment pod: 

    kind: Route
apiVersion: route.openshift.io/v1
metadata:
  name: test-sync-bug
  namespace: dynatrace
  labels:
    app: eda
    job-name: activation-job-1
spec:
  host: test-sync-bug-dynatrace.apps.aap-dt.ocp4.testing.ansible.com
  to:
    kind: Service
    name: activation-job-1
    weight: 100
  port:
    targetPort: 5000
  wildcardPolicy: None

  2. When you create the Route, test it with a Post to the Route URL: 

    curl -H "Content-Type: application/json" -X POST
test-sync-bug-dynatrace.apps.aap-dt.ocp4.testing.ansible.com -d
'{}'
    Note

    You do not need the port as it is specified on the Route (targetPort).

5.7. Testing with Kubernetes

With Kubernetes you can create an Ingress, or expose the port, but not for production.

Procedure

  1. Run the following command to expose the port on the cluster for a given service: 

    kubectl port-forward svc/<ACTIVATION_SVC_NAME> 5000:5000

  2. Make the HTTP requests against the localhost:5000 to trigger the rulebook: 

    curl -H "Content-Type: application/json" -X POST test-sync-bug-dynatrace.apps.aap-dt.ocp4.testing.ansible.com -d '{}'

Chapter 6. Rule Audit

Rule audit allows the auditing of rules which have been triggered by all the rules that were activated at some point.

The Rule Audit list view shows you a list of every time an event came in that matched a condition within a rulebook and triggered an action. The list shows you rules within your rulebook and each heading matches up to a rule that has been executed.

6.1. Viewing rule audit details

From the Rule Audit list view you can check the event that triggered specific actions.

Rule audit list view

Procedure

  1. From the navigation panel select Rule Audit.
  2. Select the desired rule, this brings you to the Details tab.

From here you can view when it was created, when it was last fired, and the rulebook activation that it corresponds to.

6.2. Viewing rule audit events

Procedure

  1. From the navigation panel select Rule Audit.
  2. Select the desired rule, this brings you to the Details tab. To view all the events that triggered an action, select the Events tab. This shows you the event that triggered actions.
  3. Select an event to view the Event log, along with the Source type and Timestamp.
Event details

6.3. Viewing rule audit actions

Procedure

  1. From the navigation panel select Rule Audit.
  2. Select the desired rule, this brings you to the Actions tab.

From here you can view executed actions that were taken. Some actions are linked out to automation controller where you can view the output.

Legal Notice

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.