Chapter 8. Rulebook activations

PDF

A rulebook is a set of conditional rules that Event-Driven Ansible uses to perform IT actions in an event-driven automation model. Rulebooks are the means by which users tell Event-Driven Ansible which source to check for an event and when that event occurs what to do when certain conditions are met.

A rulebook specifies actions to be performed when a rule is triggered. A rule gets triggered when the events match the conditions for the rules. The following actions are currently supported:

run_playbook (only supported with ansible-rulebook CLI)
run_module
run_job_template
run_workflow_template
set_fact
post_event
retract_fact
print_event
shutdown
debug
none

To view further details, see Actions.

A rulebook activation is a process running in the background defined by a decision environment executing a specific rulebook. You can set up your rulebook activation by following Setting up a rulebook activation.

Warning

Red Hat does not recommend the use of a non-supported source plugin with 1 postgres database. This can pose a potential risk to your use of Ansible Automation Platform.

Important

To meet high availability demands, Event-Driven Ansible controller shares centralized Redis (REmote DIctionary Server) with the Ansible Automation Platform UI. When Redis is unavailable, the following functions will not be available:

Creating an activation, if is_enabled is True
Deleting an activation
Enabling an activation, if not already enabled
Disabling an activation, if not already disabled
Restarting an activation

8.1. Setting up a rulebook activation

Prerequisites

You are logged in to the Ansible Automation Platform Dashboard as a Content Consumer.
You have set up a project.
You have set up a decision environment.

Procedure

Log in to Ansible Automation Platform.
Navigate to the Automation Decisions Rulebook Activations.
Click Create rulebook activation.
Insert the following:
Name
Insert the name.
Description
This field is optional.
Organization
Enter your organization name or select Default from the list.
Project
Projects are a logical collection of rulebooks. This field is optional.
Rulebook
Rulebooks are displayed according to the project selected.
Credential
Select 0 or more credentials for this rulebook activation. This field is optional.
Note
The credentials that display in this field are customized based on your rulebook activation and only include the following credential types: Vault, Red Hat Ansible Automation Platform, or any custom credential types that you have created. For more information about credentials, see Setting up credentials for Event-Driven Ansible controller.
Decision environment
Decision environments are a container image to run Ansible rulebooks.
Note
In Event-Driven Ansible controller, you cannot customize the pull policy of the decision environment. By default, it follows the behavior of the always policy. Every time an activation is started, the system tries to pull the most recent version of the image.
Restart policy
This is the policy that determines how an activation should restart after the container process running the source plugin ends.
Policies:
Always: This restarts the rulebook activation immediately, regardless of whether it ends successfully or not, and occurs no more than 5 times.
Never: This never restarts a rulebook activation when the container process ends.
On failure: This restarts the rulebook activation after 60 seconds by default, only when the container process fails, and occurs no more than 5 times.
Log level
This field defines the severity and type of content in your logged events.
Levels:
Error: Logs that contain error messages that are displayed in the History tab of an activation.
Info: Logs that contain useful information about rulebook activations, such as a success or failure, triggered action names and their related action events, and errors.
Debug: Logs that contain information that is only useful during the debug phase and might be of little value during production. This log level includes both error and log level data.
Service name
This defines a service name for Kubernetes to configure inbound connections if the activation exposes a port. This field is optional.
Rulebook activation enabled?
This automatically enables the rulebook activation to run.
Variables
The variables for the rulebook are in a JSON or YAML format. The content would be equivalent to the file passed through the --vars flag of ansible-rulebook command.
Options
Check the Skip audit events option if you do not want to see your events in the Rule Audit.
Click Create rulebook activation.

Your rulebook activation is now created and can be managed on the Rulebook Activations page.

After saving the new rulebook activation, the rulebook activation’s details page is displayed, with either a Pending, Running, or Failed status. From there or the Rulebook Activations list view, you can restart or delete it.

Note

Occasionally, when a source plugin shuts down, it causes a rulebook to exit gracefully after a certain amount of time. When a rulebook activation shuts down, any tasks that are waiting to be performed will be canceled, and an info level message is sent to the activation log. For more information, see Rulebooks.

8.2. Rulebook activation list view

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

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

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

8.2.1. Viewing activation output

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

Procedure

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

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

8.3. Enabling and disabling rulebook activations

Procedure

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

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

Procedure

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

8.5. Deleting rulebook activations

Procedure

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

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

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

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-5000
spec:
  host: test-sync-bug-dynatrace.apps.aap-dt.ocp4.testing.ansible.com
  to:
    kind: Service
    name: activation-job-1-5000
    weight: 100
  port:
    targetPort: 5000
  tls:
    termination: edge
    insecureEdgeTerminationPolicy: Redirect
  wildcardPolicy: None

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

8.7. Testing with Kubernetes

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

Procedure

Run the following command to expose the port on the cluster for a given service:
```
kubectl port-forward svc/<ACTIVATION_SVC_NAME> 5000:5000
```

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 8. Rulebook activations

8.1. Setting up a rulebook activation

8.2. Rulebook activation list view

8.2.1. Viewing activation output

8.3. Enabling and disabling rulebook activations

8.4. Restarting rulebook activations

8.5. Deleting rulebook activations

8.6. Activating webhook rulebooks

8.7. Testing with Kubernetes

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links