Using automation decisions


Red Hat Ansible Automation Platform 2.5

Configure and use Event-Driven Ansible controller to enhance and expand automation

Red Hat Customer Content Services

Abstract

Learn how to configure your Event-Driven Ansible controller to set up credentials, 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.

Providing feedback on Red Hat documentation

If you have a suggestion to improve this documentation, or find an error, you can contact technical support at https://access.redhat.com to open a request.

Event-Driven Ansible is a highly scalable, flexible automation capability that works with event sources such as other software vendors' monitoring tools. These tools monitor 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:

Note
  • API documentation for Event-Driven Ansible controller is available at https://<gateway-host>/api/eda/v1/docs
  • 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, you will not be able to create or sync projects, or enable rulebook activations.

Chapter 2. Credentials

You can use credentials to store secrets that can be used for authentication purposes with resources, such as decision environments, rulebook activations and projects for Event-Driven Ansible controller, and projects for automation controller.

Credentials authenticate users when launching jobs against machines and importing project content from a version control system.

You can grant users and teams the ability to use these credentials without exposing the credential to the user. If a user moves to a different team or leaves the organization, you do not have to rekey all of your systems just because that credential was previously available.

Note

In the context of automation controller and Event-Driven Ansible controller, you can use both extra_vars and credentials to store a variety of information. However, credentials are the preferred method of storing sensitive information such as passwords or API keys because they offer better security and centralized management, whereas extra_vars are more suitable for passing dynamic, non-sensitive data.

2.1. Credentials list view

When you log in to the Ansible Automation Platform and select Automation DecisionsInfrastructureCredentials, the Credentials page has a pre-loaded Decision Environment Container Registry credential. When you create your own credentials, they will be added to this list view. .

From the menu bar, you can search for credentials in the Name search field.

You also have the following options in the menu bar:

  • Manage columns - You can choose how fields are shown in the list view by clicking this option. You have four ways you can arrange your fields:

    • Column - Shows the column in the table.
    • Description - Shows the column when the item is expanded as a full width description.
    • Expanded - Shows the column when the item is expanded as a detail.
    • Hidden - Hides the column.
  • List view or Card view - You can choose between these views by clicking the applicable icons.

2.2. Setting up credentials

You can create a credential to use with a source plugin or a private container registry that you select. You can make your credential available to a team or individuals.

Procedure

  1. Log in to the Ansible Automation Platform Dashboard.
  2. From the navigation panel, select Automation DecisionsInfrastructureCredentials.
  3. Click Create credential.
  4. Insert the following:

    Name
    Insert the name.
    Description
    This field is optional.
    Organization
    Click the list to select an organization or select Default.
    Credential type

    Click the list to select your Credential type.

    Note

    When you select the credential type, the Type Details section is displayed with fields that are applicable for the credential type you chose.

  5. Complete the fields that are applicable to the credential type you selected.
  6. Click Create credential.

Next steps

After saving the credential, the credentials details page is displayed. From there or the Credentials list view, you can edit or delete it.

2.3. Editing a credential

You can edit existing credentials to ensure the appropriate level of access for your organization.

Procedure

  1. Edit the credential by using one of these methods:

    • From the Credentials list view, click the Edit credential icon next to the desired credential.
    • From the Credentials list view, select the name of the credential, click Edit credential.
  2. Edit the appropriate details and click Save credential.

2.4. Duplicating a credential

When setting up a new credential with field inputs that are similar to your existing credentials, you can use the Duplicate credential feature in the Details tab to duplicate information instead of manually entering it. While setting up credentials can be a lengthy process, the ability to duplicate the required fields from an existing credential saves time and, in some cases, reduces the possibility of human error.

Procedure

  1. On the Credentials list page, click the name of the credential that you want to duplicate. This takes you to the Details tab of the credential.
  2. Click Duplicate credential in the top right of the Details tab.

    Note

    You can also click the Duplicate credential icon next to the desired credential on the Credentials list page.

    A message is displayed confirming that your selected credential has been duplicated: "<Name of credential> duplicated."

  3. Click the Back to credentials tab to view the credential you just duplicated.

    The duplicated credential is displayed with the same name as the original credential followed by a time stamp in 24-hour format (for example, <Name of credential> @ 17:26:30).

  4. Edit the details you prefer for your duplicated credential.
  5. Click Save credential.

2.5. Deleting a credential

You can delete credentials if they are no longer needed for your organization.

Procedure

  1. Delete the credential by using one of these methods:

    • From the Credentials list view, click the More Actions icon next to the desired credential and click Delete credential.
    • From the Credentials list view, select the name of the credential, click the More Actions icon next to Edit credential, and click Delete credential.
  2. In the pop-up window, select Yes, I confirm that I want to delete this credential.

    Note

    If your credential is still in use by other resources in your organization, a warning message is displayed letting you know that the credential cannot be deleted. Also, if your credential is being used in an event stream, you cannot delete it until the event stream is deleted or attached to a different credential. In general, avoid deleting a credential that is in use because it can lead to broken activations.

  3. Click Delete credential.

Results

You can delete multiple credentials at a time by selecting the checkbox next to each credential, clicking the More Actions icon in the menu bar, and then clicking Delete selected credentials.

Chapter 3. Credential types

Event-Driven Ansible controller comes with several built-in credental types that you can use for syncing projects, running rulebook activations, executing job templates through Automation Execution (automation controller), fetching images from container registries, and processing data through event streams.

These built-in credential types are not editable. So if you want credential types that support authentication with other systems, you can create your own credential types that can be used in your source plugins. Each credential type contains an input configuration and an injector configuration that can be passed to an Ansible rulebook to configure your sources.

For more information, see Custom credential types.

3.1. Custom credential types

As a system administrator, you can define a custom credential type that works in ways similar to existing credential types in a standard format using a YAML or JSON-like definition.

Each credential type displays its own unique configurations in the Input Configuration and the Injector Configuration fields, if applicable. Both YAML and JSON formats are supported in the configuration fields.

Custom credentials support Ansible extra variables as a means of injecting their authentication information.

You can attach one or more cloud, vault, and Red Hat Ansible Automation Platform credential types to a rulebook activation.

Note
  • When creating a new credential type, you must avoid collisions in the extra_vars.
  • Extra variable names must not start with EDA_ because they are reserved.
  • You must have System administrator (superuser) permissions to be able to create and edit a credential type and to be able to view the Injector configuration field.

When you customize your own credential types, they display on the Credential Types page along with a list of built-in credential types.

3.1.1. Input Configuration

The Input configuration has two attributes:

  • fields - a collection of properties for a credential type.
  • required - a list of required fields.

Fields can have multiple properties, depending on the credential type you select.

Expand
Table 3.1. Input Configuration Field Properties
FieldsDescriptionMandatory (Y/N)

id

Unique id of the field; must be a string type and stores the variable name

Yes

type

Can be string or boolean type

No, default is string

label

Used by the UI when rendering the UI element

Yes

secret

Will be encrypted

No, default false

multiline

If the field contains data from a file the multiline can be set to True

No, default false

help_text

The help text associated with this field

No

3.1.2. Injector Configuration

You can use Injector configuration to extract information from Input configuration fields and map them into injector types that can be sent to ansible-rulebook when running a rulebook activation. Event-Driven Ansible supports the following types of injectors:

  • Environment variables (env) - Used in source plugins for the underlying package or shared library.
  • Ansible extra variables (extra_vars) - Used for substitution in the rulebook conditions, actions or source plugin parameters.
  • File-based templating (file) - Used to create file contents from the credential inputs such as certificates and keys, which might be required by source plugins. File injectors provide a way to deliver these certificates and keys to ansible-rulebook at runtime without having to store them in decision environments. As a result, ansible-rulebook creates temporary files and the file names can be accessed using eda.filename variables, which are automatically created for you after the files have been created (for instance, "{{eda.filename.my_cert}}”).
Important

When creating extra_vars in rulebook activations and credential type injectors, avoid using eda or ansible as key names since that conflicts with internal usage and might cause failure in both rulebook activations and credential type creation.

Injectors enable you to adjust the fields so that they can be injected into a rulebook as one of the above-mentioned injector types, which cannot have duplicate keys at the top level. If you have two sources in a rulebook that both require parameters such as username and password, the injectors, along with the rulebook, help you adapt the arguments for each source.

To view a sample injector and input, see the following GitHub gists, respectively:

3.2. Creating a new credential type

You can create a credential type to use with a source plugin that you select based on the supported, default credential types. You can make your credential type available to a team or individuals.

Procedure

  1. Log in to the Ansible Automation Platform Dashboard.
  2. From the navigation panel, select Automation DecisionsInfrastructureCredential Types.
  3. Click Create credential type.
  4. Insert the following:

    Name
    Insert the name.
    Description
    This field is optional.
  5. In the Input Configuration field, specify an input schema that defines a set of ordered fields for that type. The format can be in YAML or JSON:

    YAML

    fields:
      - type: string
        id: username
        label: Username
      - type: string
        id: password
        label: Password
        secret: true
    required:
      - username
      - password
    Copy to Clipboard Toggle word wrap

    View more YAML examples at the YAML page.

    JSON

    {
    "fields": [
      {
      "type": "string",
      "id": "username",
      "label": "Username"
      },
      {
      "secret": true,
      "type": "string",
      "id": "password",
      "label": "Password"
       }
      ],
     "required": ["username", "password"]
    }
    Copy to Clipboard Toggle word wrap

    View more JSON examples at The JSON website.

  6. In the Injector Configuration field, enter environment variables or extra variables that specify the values a credential type can inject. The format can be in YAML or JSON (see examples in the previous step).

    The following configuration in JSON format shows each field and how they are used:

    {
        "extra_vars": {
          "some_extra_var": "{{ username }}:{{ password }}"
      }
    }
    Copy to Clipboard Toggle word wrap
  7. Click Create credential type.

    Your newly created credential type is displayed in the list of credential types.

  8. Click the Edit credential type Edit icon to modify the credential type options.

Verification

  • Verify that the newly created credential type can be selected from the Credential Type list when creating a new credential.

Next steps

  • On the Edit page, you can modify the details or delete the credential.
  • If the Delete option is disabled, this means that the credential type is being used by a credential, and you must delete the credential type from all the credentials that use it before you can delete it.

Additional resources

Setting up credentials.

Chapter 4. Projects

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

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, you will not be able to create or sync projects.

4.1. Setting up a new project

You can set up projects to manage and store your rulebooks in Event-Driven Ansible controller.

Prerequisites

  • You are logged in to the Ansible Automation Platform Dashboard as a Content Consumer.
  • You have set up a credential, if necessary. For more information, see the Setting up credentials[Setting up credentials] section.
  • You have an existing repository containing rulebooks.

Procedure

  1. Log in to the Ansible Automation Platform Dashboard.
  2. Navigate to Automation DecisionsProjects.
  3. Click Create project.
  4. Insert the following:

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

    Enter Git, SSH, or HTTP[S] protocol address of a repository, such as GitHub or GitLab. This required field is editable. See Editing a project to view details of how editing this field impacts rulebook activations.

    Note

    This field accepts SSH private key or private key phrase. To enable the use of these private keys, your project URL must begin with git@.

    Proxy
    This is used to access HTTP or HTTPS servers. This field is optional and editable. See Editing a project to view details of how editing this field impacts rulebook activations.
    Source control branch/tag/commit
    This is the branch to checkout. In addition to branches, you can input tags, commit hashes, and arbitrary refs. Some commit hashes and refs may not be available unless you also provide a custom refspec. This field is optional and editable. See Editing a project to view details of how editing this field impacts rulebook activations.
    Source control refspec
    A refspec to fetch (passed to the Ansible git module). This parameter allows access to references via the branch field not otherwise available. This field is optional and editable. See Editing a project to view details of how editing this field impacts rulebook activations. For more information, see Examples.
    Source control credential
    This is an optional credential used to authenticate with the provided Source control URL.
    Content signature validation credential
    Enable content signing to verify that the content has remained secure when a project is synced. If the content has been tampered with, the job will not run. This field is optional.
    Options

    The Verify SSL option is enabled by default. Enabling this option verifies the SSL with HTTPS when the project is imported.

    Note

    You can disable this option if you have a local repository that uses self-signed certificates.

  5. Select Create project.

Results

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

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.

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

4.3. Editing a project

You can modify various aspects of a project after you create it. Depending on the changes you make, a rulebook activation might be impacted, requiring you to review and restart it.

Procedure

  1. From the Projects list view, select the More Actions icon next to the desired project. The Edit page is displayed.
  2. Edit the desired fields.

    Important

    When you update a project’s Source control URL, Source control branch/tag/commit, or Source control refspec, Event-Driven Ansible automatically triggers a project resync. This process updates the rulebooks available within Event-Driven Ansible controller and can significantly impact existing rulebook activations:

    • Rulebook Content Updates: Running activations continue to use old content when a rulebook’s content changes. To apply the newer content, you must restart the affected rulebook activation. If the rulebook content you update is attached to an activation that uses event streams, you must re-attach the event stream to that activation after the updates are applied and then, restart the activation.
    • New Rulebooks: Any new rulebook added to the repository becomes available in the database after the sync.
    • Deleted Rulebooks: A removed rulebook is deleted from the database upon sync. Its associated activations, however, continue to run and can be restarted. Review and update any activations detached from their source rulebook.
  3. Select Save project.

4.4. Deleting a project

If you need to delete a project, the Event-Driven Ansible controller interface provides multiple options.

Procedure

  1. To delete a project, complete one of the following:

    • From the Projects list view, select the checkbox next to the desired project, and click the More Actions icon from the page menu.
    • From the Projects list view, click the More Actions icon next to the desired project.
  2. Select Delete project.
  3. In the Permanently delete projects window, select Yes, I confirm that I want to delete this project.
  4. Select Delete project.

Chapter 5. Decision environments

Decision environments are container images that run Ansible rulebooks. They create a common language for communicating automation dependencies, and give a standard way to build and distribute the automation environment. You can find the default decision environment in the Ansible-Rulebook.

To create your own decision environment, see Installing ansible-builder and Building a custom decision environment for Event-Driven Ansible within Ansible Automation Platform.

5.1. Installing ansible-builder

To build images, you must have Podman or Docker installed, along with the ansible-builder Python package.

The --container-runtime option must correspond to the Podman or Docker executable you intend to use.

When building a decision environment image, it must support the architecture that Ansible Automation Platform is deployed with.

For more information, see Quickstart for Ansible Builder or Creating and using execution environments.

Decision Environments are execution environments tailored towards running Ansible Rulebooks.

Similar to execution environments that run Ansible playbooks for automation controller, decision environments are designed to run rulebooks for Event-Driven Ansible controller.

You can create a custom decision environment for Event-Driven Ansible that provides a custom maintained or third-party event source plugin that is not available in the default decision environment.

Prerequisites

  • Ansible Automation Platform > = 2.5
  • Event-Driven Ansible
  • Ansible Builder > = 3.0
Important
  • Use the correct Event-Driven Ansible controller decision environment in Ansible Automation Platform to prevent rulebook activation failure.

    • If you want to connect Event-Driven Ansible controller to Ansible Automation Platform 2.4, you must use registry.redhat.io/ansible-automation-platform-24/de-minimal-rhel9:latest
    • If you want to connect Event-Driven Ansible controller to Ansible Automation Platform 2.5, you must use registry.redhat.io/ansible-automation-platform-25/de-minimal-rhel9:latest

Procedure

Example

The following is an example of the Ansible Builder definition file that uses 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-25/de-minimal-rhel9:latest'

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

options:
  package_manager_path: /usr/bin/microdnf
Copy to Clipboard Toggle word wrap

Additionally, if you need other Python packages or RPMs, you can add the following to a single definition file:

version: 3

images:
  base_image:
    name: 'registry.redhat.io/ansible-automation-platform-25/de-minimal-rhel9: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
Copy to Clipboard Toggle word wrap

5.3. Setting up a new decision environment

You can import a decision environment into your Event-Driven Ansible controller using a default or custom decision environment.

Prerequisites

  • You have set up a credential, if necessary. For more information, see the Setting up credentials section.
  • You have pushed a decision environment image to an image repository or you chose to use the de-minimal image located in registry.redhat.io.

Procedure

  1. Log in to Ansible Automation Platform.
  2. Navigate to Automation DecisionsDecision Environments.
  3. Click Create decision environment.
  4. Insert the following:

    Name
    Insert the name.
    Description
    This field is optional.
    Organization
    Select an organization to associate with the decision environment.
    Image
    This is the full image location, including the container registry, image name, and version tag.
    Credential
    This field is optional. This is the credential needed to use the decision environment image.
  5. Select Create decision environment.

Results

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

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.

When Event-Driven Ansible controller is deployed on Ansible Automation Platform 2.5, you can create a Red Hat Ansible Automation Platform credential to connect to automation controller through the use of an automation controller URL and a username and password. After it has been created, you can attach the Red Hat Ansible Automation Platform credential to a rulebook and use it to run rulebook activations. These credentials provide a simple way to configure communication between automation controller and Event-Driven Ansible controller, enabling your rulebook activations to launch job templates.

Note

If you deployed Event-Driven Ansible controller with Ansible Automation Platform 2.4, you probably used controller tokens to connect automation controller and Event-Driven Ansible controller. These controller tokens have been deprecated in Ansible Automation Platform 2.5. To delete deprecated controller tokens and the rulebook activations associated with them, complete the following procedures starting with Replacing controller tokens in Ansible Automation Platform 2.5 before proceeding with Setting up a Red Hat Ansible Automation Platform credential.

To use Event-Driven Ansible controller in Red Hat Ansible Automation Platform 2.5, you must replace legacy controller tokens configured in your environment with Red Hat Ansible Automation Platform credentials because controller tokens have been deprecated.

To replace the controller tokens, you must delete the rulebook activations that were associated with them.

Procedure

  1. Log in to the Ansible Automation Platform Dashboard.
  2. From the top navigation panel, select Automation DecisionsRulebook Activations.
  3. Select the rulebook activations that have controller tokens.
  4. Select the More Actions icon next to the Rulebook Activation enabled/disabled toggle.
  5. Select Delete rulebook activation.
  6. In the window, select Yes, I confirm that I want to delete these X rulebook activations.
  7. Select Delete rulebook activations.

6.1.2. Deleting controller tokens

Before you can set up Red Hat Ansible Automation Platform credentials, you must delete any existing controller tokens.

Prerequisites

  • You have deleted all rulebook activations that use controller tokens.

Procedure

  1. Log in to the Ansible Automation Platform Dashboard.
  2. From the top navigation panel, select your profile.
  3. Click User details.
  4. Select the Tokens tab.
  5. Delete all of your previous controller tokens.

Next steps

After deleting the controller tokens and rulebook activations, proceed with Setting up a Red Hat Ansible Automation Platform credential.

You can create a Red Hat Ansible Automation Platform credential type to run your rulebook activations.

Prerequisites

  • You have created a user.
  • You have obtained the URL and the credentials to access automation controller.

Procedure

  1. Log in to the Ansible Automation Platform Dashboard.
  2. From the navigation panel, select Automation DecisionsInfrastructureCredentials.
  3. Click Create credential.
  4. Insert the following:

    Name
    Insert the name.
    Description
    This field is optional.
    Organization
    Click the list to select an organization or select Default.
    Credential type

    Click the list and select Red Hat Ansible Automation Platform.

    Note

    When you select the credential type, the Type Details section is displayed with fields that are applicable for the credential type you chose.

  5. In the required Red Hat Ansible Automation Platform field, enter your automation controller URL.

    Note

    For Event-Driven Ansible controller 2.5 with automation controller 2.4, use the following example: https://<your_controller_host>

    For Ansible Automation Platform 2.5, use the following example: https://<your_gateway_host>/api/controller/

  6. Enter a valid Username and Password, or Oauth Token.
  7. Click Create credential.

Next step

After you create this credential, you can use it for configuring your rulebook activations.

Chapter 7. Rulebook activations

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

7.1. Supported event sources

Event sources are a fundamental component of Event-Driven Ansible because they determine where a rulebook can receive events from. The effectiveness of a rulebook activation depends on selecting an event source that is compatible with your automation environment. Certain event sources are designed for use with the web-based Event-Driven Ansible controller, while others, due to their reliance on local host functionality, are exclusive to the ansible-rulebook command-line interface (CLI). Understanding this distinction is crucial for successful rulebook activations.

The following list includes currently supported event sources for use with the web-based Event-Driven Ansible controller. You can decide which event sources provide the desired outcome for your rulebook activations.

  • alertmanager
  • aws_cloudtrail
  • aws_sqs_queue
  • azure_service_bus
  • kafka
  • pg_listener
  • webhook

7.2. Setting up a rulebook activation

You can create and configure a rulebook activation within the Ansible Automation Platform Dashboard. This process ensures effective management and deployment of your event-driven automation.

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

  1. Log in to Ansible Automation Platform.
  2. Navigate to the Automation DecisionsRulebook Activations.
  3. Click Create rulebook activation.
  4. 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 Credentials.
    • If you plan to use a Red Hat Ansible Automation Platform credential, you can only select 1 Red Hat Ansible Automation Platform credential type for a rulebook activation.
    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:

      1. Always: This restarts the rulebook activation immediately, regardless of whether it ends successfully or not, and occurs no more than 5 times.
      2. Never: This never restarts a rulebook activation when the container process ends.
      3. 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:

      1. Error: Logs that contain error messages that are displayed in the History tab of an activation.
      2. 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.
      3. 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.

    Note

    In the context of automation controller and Event-Driven Ansible controller, you can use both extra_vars and credentials to store a variety of information. However, credentials are the preferred method of storing sensitive information such as passwords or API keys because they offer better security and centralized management, whereas extra_vars are more suitable for passing dynamic, non-sensitive data.

    Options
    Check the Skip audit events option if you do not want to see your events in the Rule Audit.
  5. Click Create rulebook activation.

Results

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.

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

7.3.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 you want to view. The Output for the activation instance is displayed.

Next steps

To view events that came in and triggered an action, navigate to Automation DecisionsRule Audit and follow instructions in the Rule Audit section.

7.4. Enabling and disabling rulebook activations

You can enable or disable rulebook activations to control when they run. Disabling an activation is useful for troubleshooting or to temporarily halt automation without deleting the configuration.

Procedure

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

7.5. Restarting rulebook activations

You can restart a rulebook activation to quickly re-engage its automation, which is useful after making updates or to recover from an error.

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

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

7.6. Editing a rulebook activation

You can edit a rulebook activation after you have created or run it to correct input for fields (log levels, Restart policy, turn auditing off or on, and the like) or help mitigate issues caused by failure.

Procedure

  1. On the Rulebook Activations page, next to the activation you want to edit, toggle the Rulebook Activation enabled button to the off position first to disable the activation.

    The Disable rulebook activations message is displayed asking you to confirm that you want to disable the activation.

  2. Select the Yes, I confirm that I want to disable these <1> rulebook activations checkbox and click Disable rulebook activations.
  3. Next to the rulebook activation, click the Edit icon. This takes you to the Edit form.

    Note

    You can also access the Edit feature by clicking the rulebook activation on the Rulebook Activations page, toggling the Rulebook activation enabled button to the off position, confirming that you want to disable the activation, and clicking the Edit rulebook activation button on the top right of the page to access the Edit form.

  4. Edit the desired fields.

    Note

    If you prefer to run your activation immediately, you can toggle the Rulebook activation enabled button to the on position, and then save your changes.

  5. Click Save rulebook activation.

Results

This takes you back to the Rulebook Activations page.

7.7. Duplicating a rulebook activation

When setting up a new rulebook activation with field inputs that are similar to one of your existing rulebook activations, you can use the Duplicate rulebook activation feature instead of manually entering input into each field. While setting up rulebook activations can be a lengthy process, the ability to duplicate the required fields from an existing activation saves time and, in some cases, reduces the possibility of human error.

Procedure

  1. On the Rulebook Activations page, click the More Actions icon on the row of the activation you want to duplicate. The More Actions list is displayed with three options:

    • Restart rulebook activation
    • Duplicate rulebook activation
    • Delete rulebook activation
  2. Select Duplicate rulebook activation.

    A message is displayed: "<Name of rulebook activation 1> duplicated." Initially, the newly duplicated activation is displayed as disabled on the Rulebook Activations page with the same name as the original activation followed by a time stamp in 24-hour format (for example, <Name of rulebook activation 1> @ 18:43:27).

    Important

    The original rulebook activation continues to run after you have duplicated it. If you try to enable the duplicated activation without editing the fields (including the Name field) to distinguish it from the original, a message is displayed reminding you that the rulebook activation was duplicated from an original, and enabling it might fail or result in duplicate jobs and other complications.

  3. Before you run the duplicated rulebook activation, edit the fields by completing the following:

    1. Next to the duplicated rulebook activation, click the Edit icon. This takes you to the Edit form.
    2. Edit the desired fields.

      Note

      Ensure that you have given your newly duplicated activation a meaningful Name that distinguishes it from the original activation.

  4. Toggle the Enable rulebook activation button to the on position.
  5. After confirming all of your edits are complete, click Save rulebook activation.

Results

This initiates the rulebook activation, and if it runs successfully, the status changes to Running or Completed.

7.8. Deleting rulebook activations

You can delete rulebook activations to permanently remove them when they are no longer needed.

Procedure

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

7.9. 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
Copy to Clipboard Toggle word wrap

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-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
    Copy to Clipboard Toggle word wrap
  2. When you create the Route, test it with a Post to the Route URL:

    Note

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

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

7.10. 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
    Copy to Clipboard Toggle word wrap
  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 '{}'
    Copy to Clipboard Toggle word wrap

Chapter 8. Rulebook activations troubleshooting

Occasionally, rulebook activations might fail due to a variety of reasons that can be resolved. In many cases, log filtering provides information that could be helpful in determining the cause of activation failure.

For improved log filtering, there are two different tracking IDs available for troubleshooting after an action is performed (for example, when you initiate a rulebook activation). Both tracking IDs are universally unique identifiers (UUIDs):

  • Log tracking ID [tid]- Created for each activation and persists across all activation instances. It allows users to track the complete history of an activation and its lifecycle. The Log tracking ID can be retrieved from the activation instance logs under the History tab.
  • X-request-ID [rid] - A standard HTTP header that is returned to the user as part of the HTTP response. If you want to fetch this ID, you must inspect the HTTP response headers. This ID results from actions such as triggering a restart of an activation. It allows tracking of a specific API request from platform gateway to Event-Driven Ansible controller.

You can use both tracking IDs to locate specific log entries in your backend logs (for example, API or worker logs).

Review the list of possible issues that can cause activation failures and suggestions on how you can resolve them.

8.1. Activation stuck in Pending state

Perform the following steps if your rulebook activation is stuck in Pending state.

Procedure

  1. Confirm whether there are other running activations and if you have reached the limits (for example, memory or CPU limits).

    1. If there are other activations running, terminate one or more of them, if possible.
    2. If not, check that the default worker, Redis, and activation worker are all running. If all systems are working as expected, check your eda-server internal logs in the worker, scheduler, API, and nginx containers and services to see if the problem can be determined.

      Note

      These logs reveal the source of the issue, such as an exception thrown by the code, a runtime error with network issues, or an error with the rulebook code. If your internal logs do not provide information that leads to resolution, report the issue to Red Hat support.

    3. If you need to make adjustments, see the Modifying the number of simultaneous rulebook activations.

      Note

      To adjust the maximum number of simultaneous activations for Ansible Automation Platform Operator on OpenShift Container Platform deployments, see Modifying the number of simultaneous rulebook activations during or after Event-Driven Ansible controller installation in Installing on OpenShift Container Platform.

8.2. Activation keeps restarting

Perform the following steps if your rulebook activation keeps restarting.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation DecisionsRulebook Activations.
  3. From the Rulebook Activations page, select the activation in your list that keeps restarting. The Details page is displayed.
  4. Click the History tab for more information and select the rulebook activation that keeps restarting. The Details tab is displayed and shows the output information.
  5. Check the Restart policy field for your activation.

    There are three selections available: On failure (restarts a rulebook activation when the container process fails), Always (always restarts regardless of success or failure with no more than 5 restarts), or Never (never restarts when the container process ends).

    1. Confirm that your rulebook activation Restart policy is set to On failure. This is an indication that an issue is causing it to fail.
    2. To possibly diagnose the problem, check the YAML code and the instance logs of the rulebook activation for errors.
    3. If you cannot find a solution with the restart policy values, proceed to the next steps related to the Log level.
  6. Check your log level for your activation.

    1. If your default log level is Error, go back to the Rulebook Activation page and recreate your activation following procedures in Setting up rulebook a activation.
    2. Change the Log level to Debug.
    3. Run the activation again and navigate to the History tab from the activation details page.
    4. On the History page, click one of your recent activations and view the Output.

If your rulebook activation is running but not processing events, the most common cause is a mismatch between the expected event source and the source defined in the rulebook.

Procedure

  1. Check the rulebook source: Review the source plugin defined in your rulebook YAML (for example, ansible.eda.webhook, ansible.eda.kafka).
  2. Verify event input: Confirm that the events you are sending to Event-Driven Ansible controller are compatible with the source plugin defined in the rulebook. If the rulebook expects a Kafka message, it cannot process a generic webhook event.
  3. Confirm activation mapping: If you are using event streams, ensure the correct event stream is mapped to the rulebook during the activation setup. A mismatch here will result in the activation receiving no data.

If your rulebook activation is Running and successfully receiving events, but no actions are being executed, the issue is likely within the logic of your rulebook.

Procedure

  1. Check rule conditions: Review the rulebook YAML to confirm that the conditions (the when statements) are accurately written and precisely match the structure and values of the incoming event payload.
  2. Verify indentation and syntax: Ensure all rulebook syntax and indentation are correct, as a simple error can prevent the rule engine from evaluating conditions.
  3. Validate actions: Confirm that the specified action is a recognized and correctly configured action (for example, run_job_template with the proper arguments).

If you are using event streams to send events to your rulebook activations, occasionally those events might not be successfully routed to your rulebook activation.

Procedure

  • Try the following options to resolve this.

    1. Ensure that each of your event streams in Event-Driven Ansible controller is not in Test mode . This means activations would not receive the events.
    2. Verify that the origin service is sending the request properly.
    3. Check that the network connection to your platform gateway instance is stable. If you have set up event streams, this is the entry of the event stream request from the sender.
    4. Verify that the proxy in the platform gateway is running.
    5. Confirm that the event stream worker is up and running, and able to process the request.
    6. Verify that your credential is correctly set up in the event stream.
    7. Confirm that the request complies with the authentication mechanism determined by the set credential (for example, basic must contain a header with the credentials or HMAC must contain the signature of the content in a header, and similar).

      Note

      The credentials might have been changed in Event-Driven Ansible controller, but not updated in the origin service.

    8. Verify that the rulebook that is running in the activation reacts to these events. This would indicate that you wrote down the event source and added actions that consume the events coming in. Otherwise, the event does reach the activation but there is nothing to activate it.
    9. If you are using self-signed certificates, you might want to disable certificate validation when sending webhooks from vendors. Most of the vendors have an option to disable certificate validation for testing or non-production environments.

You might experience a failed connection to automation controller when you run your activations.

Procedure

  1. To help resolve the issue, confirm that you have set up a Red Hat Ansible Automation Platform credential and have obtained the correct automation controller URL.

    1. If you have not set up a Red Hat Ansible Automation Platform credential, follow the procedures in Setting up a Red Hat Ansible Automation Platform credential. Ensure that this credential has the host set to the following URL format: https://<your_gateway>/api/controller
    2. When you have completed this process, try setting up your rulebook activation again.

Chapter 9. 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.

9.1. Viewing rule audit details

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

Procedure

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

Results

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

9.2. Viewing rule audit events

You can select a specific rule to view a list of its corresponding events, then inspect each event’s log, source type, and timestamp for detailed information.

Procedure

  1. From the navigation panel, select Automation DecisionsRule 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.

9.3. Viewing rule audit actions

You can select a specific rule to view a list of its corresponding actions and view their output.

Procedure

  1. From the navigation panel select Automation DecisionsRule Audit.
  2. Select the desired rule, then select the Actions tab.

Results

From here, you can view executed actions that were taken. Some actions are linked out to Automation Execution where you can view the output.

Chapter 10. Simplified event routing

Simplified event routing enables Event-Driven Ansible controller to capture and analyze data from various remote systems using event streams. With event streams, you can send events from a remote system like GitHub or GitLab into Event-Driven Ansible controller. You can attach 1 or more event streams to an activation by swapping out sources in a rulebook.

Event streams are an easy way to connect your sources to your rulebooks. This capability lets you create a single endpoint to receive alerts from an event source and then use the events in multiple rulebooks.

10.1. Event streams

Event streams can send events from remote systems to Event-Driven Ansible controller. In a typical set-up, a server sends data to an event stream over the internet to an Event-Driven Ansible event stream receiver. When the data comes over the internet, the request must be authenticated. Depending on the webhook vendor or remote system, the authentication method could differ.

Event-Driven Ansible controller supports six different event stream types.

Expand
Table 10.1. Event Stream Types
TypeDescriptionVendors

HMAC

Hashed Message Authentication Code (HMAC). Uses a shared secret between Event-Driven Ansible controller and the vendors webhook server. This guarantees message integrity.

Github

Basic Authentication

Uses HTTP basic authentication.

Datadog, Dynatrace

Token Authentication

Uses Token Authentication. Usually the HTTP Header is Authorization but some vendors like Gitlab use X-Gitlab-Token.

Gitlab, ServiceNow

OAuth2

Uses Machine-to-Machine (M2M) mode with a grant type called client credentials. The token is opaque.

Dynatrace

OAuth2 with JWT

Uses M2M mode with a grant type called client credentials. The token is JSON Web Token (JWT).

Datadog

ECDSA

Elliptic Curve Digital Signature Algorithm

SendGrid, Twilio

Event-Driven Ansible controller also supports four other specialized event streams that are based on the six basic event stream types:

  • GitLab Event Stream
  • GitHub Event Stream
  • ServiceNow Event Stream
  • Dynatrace Event Stream

These specialized types limit the parameters you use by adding default values. For example, the GitHub Event Stream is a specialization of the HMAC Event Stream with many of the fields already populated. After the GitHub Event Stream credential has been saved, the recommended defaults for the GitHub Event Stream are displayed.

10.2. Creating an event stream credential

You must create an event stream credential first before you can use an event stream.

Prerequisites

  • Each event stream must have exactly one credential.

Procedure

  1. Log in to the Ansible Automation Platform Dashboard.
  2. From the navigation panel, select Automation DecisionsInfrastructureCredentials.
  3. Click Create credential.
  4. Insert the following:

    Name
    Insert the name.
    Description
    This field is optional.
    Organization
    Click the list to select an organization or select Default.
    Credential type

    Click the list to select your Credential type.

    Note

    When you select the credential type, the Type Details section is displayed with fields that are applicable for the credential type you selected.

    Type Details
    Add the requested information for the credential type you selected. For example, if you selected the GitHub Event Stream credential type, you are required to add an HMAC Secret (symmetrical shared secret) between Event-Driven Ansible controller and the remote server.
  5. Click Create credential.

Results

The Details page is displayed. From there or the Credentials list view, you can edit or delete it.

10.3. Creating an event stream

You can create event streams that will be attached to a rulebook activation.

Prerequisites

  • If you will be attaching your event stream to a rulebook activation, ensure that your activation has a decision environment and project already set up.
  • If you plan to connect to automation controller to run your rulebook activation, ensure that you have created a Red Hat Ansible Automation Platform credential type in addition to the decision environment and project. For more information, see Setting up a Red Hat Ansible Automation Platform credential.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation DecisionsEvent Streams.
  3. Click Create event stream.
  4. Insert the following:

    Name
    Insert the name.
    Organization
    Click the list to select an organization or select Default.
    Event stream type

    Select the event stream type you prefer.

    Note

    This list displays at least 10 default event stream types that can be used to authenticate the connection coming from your remote server.

    Credentials
    Select a credential from the list, preferably the one you created for your event stream.
    Headers
    Enter HTTP header keys, separated by commas, that you want to include in the event payload. To include all headers, leave the field empty.
    Forward events to rulebook activation

    Use this option to enable or disable the capability of forwarding events to rulebook activations.

    Note

    The event stream’s event forwarding can be disabled for testing purposes while diagnosing connections and evaluating the incoming data. Disabling the Forward events to rulebook activation option allows you to test the event stream connection with the remote system, analyze the header and payload, and if necessary, diagnose credential issues. This ensures that events are not be forwarded to rulebook activations causing rules and conditions to be triggered inadvertently while you are in test mode. Some enterprises might have policies to change secrets and passwords at regular cadence. You can enable/disable this option anytime after the event stream is created.

  5. Click Create event stream.

Results

After creating your event stream, the following outputs occur:

  • The Details page is displayed. From there or the Event Streams list view, you can edit or delete it. Also, the Event Streams page shows all of the event streams you have created and the following columns for each event: Events received, Last event received, and Event stream type. As the first two columns receive external data through the event stream, they are continuously updated to let you know they are receiving events from remote systems.
  • If you disabled the event stream, the Details page is displayed with a warning message, This event stream is disabled.

    Note

    After an event stream is created, the associated credential cannot be deleted until the event stream it is attached to is deleted.

  • Your new event stream generates a URL that is necessary when you configure the webhook on the remote system that sends events.

After you have created your event stream, you must configure your remote system to send events to Event-Driven Ansible controller. The method used for this configuration varies, depending on the vendor for the event stream credential type you select.

Prerequisites

  • The URL that was generated when you created your event stream
  • Secrets or passwords that you set up in your event stream credential

Procedure

The following example demonstrates how to configure webhooks in a remote system like GitHub to send events to Event-Driven Ansible controller. Each vendor will have unique methods for configuring your remote system to send events to Event-Driven Ansible controller.

  1. Log in to your GitHub repository.
  2. Click Your profile name → Your repositories.

    Note

    If you do not have a repository, click New to create a new one, select an owner, add a Repository name, and click Create repository.

  3. Navigate to Settings (tool bar).
  4. In the General navigation pane, select Webhooks.
  5. Click Add webhook.
  6. In the Payload URL field, paste the URL you saved when you created your event stream.
  7. Select application/json in the Content type list.
  8. Enter your Secret.
  9. Click Add webhook.

Results

After the webhook has been added, it attempts to send a test payload to ensure there is connectivity between the two systems (GitHub and Event-Driven Ansible controller). If it can successfully send the data, you will see a green check mark next to the Webhook URL with the message, Last delivery was successful.

10.5. Verifying your event streams work

Verify that you can use your event stream to connect to a remote system and receive data.

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation DecisionsEvent Streams.
  3. Select the event stream that you created to validate connectivity and ensure that the event stream sends data to the rulebook activation.
  4. Verify that the events were received. The number of Events received is displayed along with a header that contains details about the event.

    Verify event streams work

    If you scroll down in the UI, you can also see the body of the payload with more information about the webhook.

    The Header and Body sections for the event stream are displayed on the Details page. They differ based on the vendor who is sending the event. The header and body can be used to check the attributes in the event payload, which will help you in writing conditions in your rulebook.

  5. Toggle the Forward events to rulebook activation option to enable you to push your events to a rulebook activation.

Results

This moves the event stream to production mode and makes it easy to attach to rulebook activations. When this option is toggled off, your ability to forward events to a rulebook activation is disabled and the This event stream is disabled message is displayed.

When you create rulebook activations, you can use event streams to swap out source mappings in rulebook activations and simplify routing from external sources to Event-Driven Ansible controller.

There are several key points to keep in mind regarding source mapping:

  1. An event stream can only be used once in a rulebook source swap. If you have multiple sources in the rulebook, you can only replace each source once.
  2. The source mapping happens only in the current rulebook activation. You must repeat this process for any other activations using the same rulebook.
  3. The source mapping is valid only if the rulebook doesn’t get modified. If the rulebook gets modified during the source mapping process, the source mapping would fail and it would have to be repeated.
  4. If the rulebook is modified after the source mapping has been created and a Restart happens, the rulebook activation fails.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation DecisionsRulebook Activations.
  3. Click Create rulebook activation.
  4. 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.

    Note

    Although this field is optional, selecting a project helps refine your list of rulebooks choices.

    Rulebook

    Rulebooks are shown according to the project selected. Select a rulebook.

    Note

    After you have selected a rulebook, the Event streams field is enabled. You can click the gear icon to display the Event streams mapping form.

    Event streams

    All the event streams available and set up to forward events to rulebook actiavtions are displayed. If you have not created any event streams, this field remains disabled.

    Click the gear icon to display the Event streams mapping UI.

    Event streams mapping UI

    Complete the following fields:

    Rulebook source

    A rulebook can contain multiple sources across multiple rulesets. You can map the same rulebook in multiple activations to multiple event streams. While managing event streams, unnamed sources are assigned temporary names (__SOURCE {n}) for identification purposes.

    Select __SOURCE_1 from the list.

    Event stream

    Select your event stream name from the list.

    Click Save.

    Event streams can replace matching sources in a rulebook, and are server-side webhooks that enable you to connect various event sources to your rulebook activations. Source types that can be replaced with the event stream’s source of type ansible.eda.pg_listener include ansible.eda.webhook and other compatible webhook source plugins. Replacing selected sources affects this activation only, and modifies the rulebook’s source type, source name, and arguments. Filters, rules, conditions, and actions are all unaffected.

    You can select which source you want to replace with a single event stream. If there are multiple sources in your rulebook, you can choose to replace each one of them with event streams, but you are not required to replace each one. The following image displays which sources can be replaced.

    Event streams replacement sources

    The items in pink demonstrate the sources that can be replaced: source type, source name, and arguments. The remaining items (filters, rules, and actions) are not replaced.

    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 on credentials, see Credentials.

    Decision environment

    A decision environment is a container image used 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:

      1. Always: This restarts the rulebook activation immediately, regardless of whether it ends successfully or not, and occurs no more than 5 times.
      2. Never: This never restarts a rulebook activation when the container process ends.
      3. 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:

      1. Error: Logs that contain error messages that are displayed in the History tab of an activation.
      2. 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.
      3. 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.
  5. Click Create rulebook activation.

Results

After you create your rulebook activation, the Details page is displayed. You can navigate to the Event streams page to confirm your events have been received.

After you have replaced your sources with the event stream you created, you can now resend data from the event stream to ensure that it is attached to your rulebook activation. In the example shared earlier, the GitHub event stream was used. The following example demonstrates how to resend webhook data if you were using a GitHub event stream.

Procedure

  1. Go back to the GitHub Webhook / Manage webhook page.
  2. Click the Recent Deliveries tab.
  3. Click the ellipsis.
  4. Click Redeliver. A Redeliver payload? window is displayed with a delivery message.
  5. Click Yes, redeliver this payload.
  6. Return to the Ansible Automation Platform to check your rule audit.

When events have been sent and received by Event-Driven Ansible controller, you can confirm that actions have been triggered by going to the Rule Audit page and viewing the event stream results.

Procedure

  1. Log in to Ansible Automation Platform.
  2. From the navigation panel, select Automation DecisionsRule Audit.

Results

If your rulebook activation received the event data from the event stream type you selected, the Rule Audit page displays the results for Status, Rulebook activation, and the Last fired date fields.

Event-Driven Ansible is a highly scalable, flexible automation capability. Event-Driven Ansible controller provides the interface in which Event-Driven Ansible automation performs. Tune your Event-Driven Ansible controller to optimize performance and scalability through:

  • Characterizing your workload
  • System level monitoring
  • Performance troubleshooting

11.1. Characterizing your workload

In Event-Driven Ansible controller, your workload includes the number of rulebook activations and events being received. Consider the following factors to characterize your Event-Driven Ansible controller workload:

  1. Number of simultaneous rulebook activations
  2. Number of events received by Event-Driven Ansible controller

Memory usage is based on the number of events that Event-Driven Ansible controller has to process. By default, each rulebook activation container has a 200 MB memory limit. For example, with 4 CPU and 16 GB of RAM, one rulebook activation container with an assigned 200 MB memory limit cannot handle more than 150,000 events per minute. If the number of parallel running rulebook activations is higher, then the maximum number of events each rulebook activation can process is reduced. If there are too many incoming events at a very high rate, the container can run out of memory trying to process the events. This will kill the container, and your rulebook activation will fail with a status code of 137.

To mitigate this status, you can modify the default memory limit for each rulebook activation during or after installation.

Procedure

  1. Perform the following steps to modify your default memory limit for your rulebook activations during installation:

    1. Navigate to the setup inventory file.
    2. Add automationedacontroller_podman_mem_limit in the [all:vars] section. For example, automationedacontroller_podman_mem_limit='400m'.
    3. Run the setup.
  2. Perform the following steps to modify your default memory limit for your rulebook activations after installation:

    1. Navigate to the environment file at /etc/ansible-automation-platform/eda/settings.yaml.
    2. Modify the default container memory limit. For example, PODMAN_MEM_LIMIT = '300m'.
    3. Restart the Event-Driven Ansible controller services using automation-eda-controller-service restart.

After characterizing your workload to determine how many rulebook activations you are running in parallel and how many events you are receiving at any given point, you must consider monitoring your Event-Driven Ansible controller host at the system level. Using system level monitoring to review information about Event-Driven Ansible’s performance over time helps when diagnosing problems or when considering capacity for future growth.

System level monitoring includes the following information:

  • Disk I/O
  • RAM utilization
  • CPU utilization
  • Network traffic

Higher CPU, RAM, or Disk utilization can affect the overall performance of Event-Driven Ansible controller. For example, a high utilization of any of these system level resources indicates that either the Event-Driven Ansible controller is running too many rulebook activations, or some of the individual rulebook activations are using a high volume of resources. In this case, you must increase your system level resources to support your workload.

Chapter 12. Event filter plugins

Events sometimes have extra data that is unnecessary and might overwhelm the rule engine. Use event filters to remove that extra data so you can focus on what matters to your rules. Event filters might also change the format of the data so that the rule conditions can better match the data.

Events are defined as python code and distributed as collections. The default eda collection has the following filters:

Expand
NameDescription

json_filter

This filter includes and excludes keys from the event object

dashes_to_underscores

This filter changes the dashes in all keys in the payload to be underscore

ansible.eda.insert_hosts_to_meta

This filter is used to add host information into the event so that ansible-rulebook can locate it and use it

ansible.eda.normalize_keys

This filter is used if you want to change non alpha numeric keys to underscore

You can chain event filters one after the other, and the updated data is sent from one filter to the next. Event filters are defined in the rulebook after a source is defined. When the rulebook starts the source plugin it associates the correct filters and transforms the data before putting it into the queue.

sources:
  - name: azure_service_bus
    ansible.eda.azure_service_bus:
      conn_str: "{{connection_str}}"
      queue_name: "{{queue_name}}"
    filters:
      - json_filter:
          include_keys: ['clone_url']
          exclude_keys: ['*_url', '_links', 'base', 'sender', 'owner', 'user']
      - dashes_to_underscores:
Copy to Clipboard Toggle word wrap

In this example the data is first passed through the json_filter and then through the dashes_to_underscores filter. In the event payload, keys can only contain letters, numbers, and underscores. The period (.) is used to access nested keys.

Since every event should record the origin of the event the filter eda.builtin.insert_meta_info is added automatically by ansible-rulebook to add the source name, type, and received_at. The received_at stores a date time in UTC ISO8601 format and includes the microseconds. The uuid stores the unique id for the event. The meta key is used to store metadata about the event and its needed to correctly report about the events in the aap-server.

12.1. Author event filters

Event filters are functions in a python module that perform transformations on the event data. They can remove, add, change, or move any data in the event data structure. Event filters take the event as the first argument and additional keyword arguments are provided by the configuration in the rulebook.

The basic structure follows:

   # my_namespace.my_collection/extensions/eda/plugins/event_filter/my_filter.py
    def main(event: dict, arg1, arg2):
        # Process event data here
        return event
Copy to Clipboard Toggle word wrap

You can use this filter in a rulebook by adding it to the filters list in an event source:

  sources:
    - name: azure_service_bus
      ansible.eda.azure_service_bus:
        conn_str: "{{connection_str}}"
        queue_name: "{{queue_name}}"
      filters:
        - my_namespace.my_collection.my_filter:
            arg1: hello
            arg2: world
Copy to Clipboard Toggle word wrap

Additional resources

Chapter 13. Event-Driven Ansible logging strategy

Event-Driven Ansible offers an audit logging solution over its resources. Each supported create, read, update and delete (CRUD) operation is logged against rulebook activations, event streams, decision environments, projects, and activations. Some of these resources support further operations, such as sync, enable, disable, restart, start, and stop; for these operations, logging is supported as well. These logs are only retained for the lifecycle of its associated container. See the following sample logs for each supported logging operation.

13.1. Logging samples

When the following APIs are called for each operation, you see the following audit logs:

Rulebook activation
1. Create
    1. 2024-08-15 14:13:20,384 aap_eda.api.views.activation INFO   Action: Create / ResourceType: RulebookActivation / ResourceName: quick_start_project / ResourceID: 53 / Organization: Default
2. Read
    1. 2024-08-15 14:21:26,844 aap_eda.api.views.activation INFO   Action: Read / ResourceType: RulebookActivation / ResourceName: quick_start_activation / ResourceID: 1 / Organization: Default
3. Disable
    1. 2024-08-15 14:23:57,798 aap_eda.api.views.activation INFO   Action: Disable / ResourceType: RulebookActivation / ResourceName: quick_start_activation / ResourceID: 1 / Organization: Default
4. Enable
    1. 2024-08-15 14:24:16,472 aap_eda.api.views.activation INFO   Action: Enable / ResourceType: RulebookActivation / ResourceName: quick_start_activation / ResourceID: 1 / Organization: Default
5. Delete
    1. 2024-08-15 14:24:53,847 aap_eda.api.views.activation INFO   Action: Delete / ResourceType: RulebookActivation / ResourceName: quick_start_activation / ResourceID: 1 / Organization: Default
6. Restart
    2024-08-15 14:24:34,169 aap_eda.api.views.activation INFO      Action: Restart / ResourceType: RulebookActivation / ResourceName: quick_start_activation / ResourceID: 1 / Organization: Default
Copy to Clipboard Toggle word wrap
EventStream Logs
1. Create
    1. 2024-08-15 13:46:26,903 aap_eda.api.views.webhook INFO     Action: Create / ResourceType: EventStream / ResourceName: ZackTest / ResourceID: 1 / Organization: Default
2. Update
    1. 2024-08-15 13:56:17,440 aap_eda.api.views.webhook INFO     Action: Update / ResourceType: EventStream / ResourceName: ZackTest / ResourceID: 1 / Organization: Default
3. Read
    1. 2024-08-15 13:56:56,271 aap_eda.api.views.webhook INFO     Action: Read / ResourceType: EventStream / ResourceName: ZackTest / ResourceID: 1 / Organization: Default
4. List
    1. 2024-08-15 13:56:17,492 aap_eda.api.views.webhook INFO     Action: List / ResourceType: EventStream / ResourceName: * / ResourceID: * / Organization: *
5. Delete
    1. 2024-08-15 13:57:13,124 aap_eda.api.views.webhook INFO     Action: Delete / ResourceType: EventStream / ResourceName: ZackTest / ResourceID: None / Organization: Default
Copy to Clipboard Toggle word wrap
Decision Environment
1. Create
    1. 2024-08-15 14:10:53,311 aap_eda.api.views.decision_environment INFO     Action: Create / ResourceType: DecisionEnvironment / ResourceName: quick_start_de / ResourceID: 86 / Organization: Default
2. Read
    1. 2024-08-15 14:10:53,349 aap_eda.api.views.decision_environment INFO     Action: Read / ResourceType: DecisionEnvironment / ResourceName: quick_start_de / ResourceID: 86 / Organization: Default
3. Update
    2024-08-15 14:11:20,970 aap_eda.api.views.decision_environment INFO     Action: Update / ResourceType: DecisionEnvironment / ResourceName: quick_start_de / ResourceID: 86 / Organization: Default
4. Delete
2024-08-15 14:11:42,369 aap_eda.api.views.decision_environment INFO     Action: Delete / ResourceType: DecisionEnvironment / ResourceName: quick_start_de / ResourceID: None / Organization: Default
Copy to Clipboard Toggle word wrap
Project
1. Create
    1. 2024-08-15 14:05:26,874 aap_eda.api.views.project INFO     Action: Create / ResourceType: Project / ResourceName: quick_start_project / ResourceID: 86 / Organization: Default
2. Read
    1. 2024-08-15 14:05:26,913 aap_eda.api.views.project INFO     Action: Read / ResourceType: Project / ResourceName: quick_start_project / ResourceID: 86 / Organization: Default
3. Update
    1. 2024-08-15 14:06:08,255 aap_eda.api.views.project INFO     Action: Update / ResourceType: Project / ResourceName: quick_start_project / ResourceID: 86 / Organization: Default
4. Sync
    1. 2024-08-15 14:06:30,580 aap_eda.api.views.project INFO     Action: Sync / ResourceType: Project / ResourceName: quick_start_project / ResourceID: 86 / Organization: Default
5. Delete
    1. 2024-08-15 14:06:49,481 aap_eda.api.views.project INFO     Action: Delete / ResourceType: Project / ResourceName: quick_start_project / ResourceID: 86 / Organization: Default
Copy to Clipboard Toggle word wrap
Activation Start/Stop
1. Start
    1. 2024-08-15 14:21:29,076 aap_eda.services.activation.activation_manager INFO     Requested to start activation 1, starting.
    2024-08-15 14:21:29,093 aap_eda.services.activation.activation_manager INFO     Creating a new activation instance for activation: 1
    2024-08-15 14:21:29,104 aap_eda.services.activation.activation_manager INFO     Starting container for activation instance: 1
2. Stop
    1. eda-activation-worker-1  | 2024-08-15 14:40:52,547 aap_eda.services.activation.activation_manager INFO     Stop operation requested for activation id: 2 Stopping activation.
    eda-activation-worker-1  | 2024-08-15 14:40:52,550 aap_eda.services.activation.activation_manager INFO     Activation 2 is already stopped.
    eda-activation-worker-1  | 2024-08-15 14:40:52,550 aap_eda.services.activation.activation_manager INFO     Activation manager activation id: 2 Activation restart scheduled for 1 second.
    eda-activation-worker-1  | 2024-08-15 14:40:52,562 rq.worker INFO     activation: Job OK (activation-2)
Copy to Clipboard Toggle word wrap

Legal Notice

Copyright © 2025 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.
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat