Chapter 6. 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.
6.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 7 different event stream types.
Type | Description | Vendors |
---|---|---|
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 |
Mutual TLS | Needs the vendor’s CA certificate to be present in our servers at startup. This supports non-repudiation. | PagerDuty |
Event-Driven Ansible controller also supports 4 other specialized event streams that are based on the 7 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.
6.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
- Log in to the Ansible Automation Platform Dashboard.
-
From the navigation panel, select
. - Click .
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.
NoteWhen 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.
- Click .
The Details page is displayed. From there or the Credentials list view, you can edit or delete it.
6.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
- Log in to Ansible Automation Platform.
-
From the navigation panel, select
. - Click .
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.
NoteThis 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.
NoteThe 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.
- Click .
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.
- Your new event stream generates a URL that is necessary when you configure the webhook on the remote system that sends events.
After an event stream is created, the associated credential cannot be deleted until the event stream it is attached to is deleted.
6.4. Configuring your remote system to send 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.
- Log in to your GitHub repository.
-
Click Your profile name
Your repositories.
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.
- Navigate to Settings (tool bar).
- In the General navigation pane, select Webhooks.
- Click Add webhook.
- In the Payload URL field, paste the URL you saved when you created your event stream.
- Select application/json in the Content type list.
- Enter your Secret.
- Click Add webhook.
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.
6.5. Verifying your event streams work
Verify that you can use your event stream to connect to a remote system and receive data.
- Log in to Ansible Automation Platform.
-
From the navigation panel, select
. - Select the event stream that you created to validate connectivity and ensure that the event stream sends data to the rulebook activation.
Verify that the events were received.You can see in the Events received field that the event was received. You can also see the header for the event stream that contains details about the event.
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. For example:
Toggle the Forward events to rulebook activation option to enable you to push your events to a rulebook activation. 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.
6.6. Replacing sources and attaching event streams to activations
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:
- 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.
- The source mapping happens only in the current rulebook activation. You must repeat this process for any other activations using the same rulebook.
- 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.
- If the rulebook is modified after the source mapping has been created and a Restart happens, the rulebook activation fails.
Procedure
- Log in to Ansible Automation Platform.
-
From the navigation panel, select
. - Click .
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.
NoteAlthough 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.
NoteAfter 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.
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
.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.
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.
NoteThe 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.
NoteIn 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
.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.
6.7. Resending webhook data from your event stream type
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
- Go back to the GitHub Webhook / Manage webhook page.
- Click the Recent Deliveries tab.
- Click the .
- Click Redeliver payload? window is displayed with a delivery message. . A
- Click Yes, redeliver this payload.
- Return to the Ansible Automation Platform to check your rule audit.
6.8. Check the Rule Audit for events on your new event stream
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
- Log in to Ansible Automation Platform.
From the navigation panel, select
. If your rulebook activation received the event data from the event stream type you selected, the Rule Audit page displays the results similar to this image.