Event-Driven Ansible
Event-Driven Ansible runs rulebooks: they listen to events from sources such as webhooks,
message queues and monitoring tools, evaluate rules, and perform actions when conditions match.
An action can launch an automation controller job template or handle an event in the decision
environment. In Koios Automation Platform, open Automation Decisions in the navigation menu.
Its API is under /api/eda/v1/ through the platform gateway (API reference).
Event-Driven Ansible is deployed unless eda.disabled: true
(Configure). Organizations, teams and users are managed in
Access Management and synchronized with Event-Driven Ansible. Permission to manage an activation
does not by itself grant permission to launch its target controller job template.
Concepts
Concept |
Purpose |
|---|---|
Rulebook |
YAML that defines one or more rulesets: event sources, conditions and actions. It is imported from a project. |
Source |
A plugin that supplies events to a ruleset, such as |
Rule |
A named condition and its action or actions. For example, |
Action |
Work performed when a condition matches: for example, |
Decision environment |
A container image with ansible-rulebook, source plugins, action dependencies and their runtime. |
Project |
A Git repository whose rulebooks are imported for selection in activations. |
Rulebook activation |
A configuration that runs an imported rulebook with a decision environment, credentials, variables, source mappings and a restart policy. Its History records individual instances of that execution. |
Event stream |
An authenticated HTTP entry point through the platform gateway. A mapping delivers its events to an activation in place of a rulebook source. |
Rule audit |
Records of rules that fired, their triggering events and actions. It helps connect an event to the work performed; it is not a substitute for checking the result of a controller job. |
Decision environments
A decision environment runs the rulebook, while an execution environment runs an automation controller job. They are separate images and resources. The platform does not create a decision environment automatically: create one in Automation Decisions > Decision Environments.
Use the release image ghcr.io/koiosplatform/koios-de@sha256:<digest> (the de image in
Releases) or a suitable custom image. The release images are currently
private; obtain project-granted read access as described in
Registry access.
Activation pods run in the platform namespace with its default ServiceAccount. With the
installer’s registry setup, that account has the release image pull secret, so the decision
environment can leave Credential empty. For another private registry, select an Event-Driven
Ansible Container Registry credential on the decision environment. See
image pull failures.
Projects
Create a Git project in Automation Decisions > Projects, providing a Source control credential if the repository is private. A successful import makes its rulebooks available to activations. A project here is separate from an automation controller project, even when both point at the same repository.
Your first rulebook activation uses the public
https://github.com/ansible/eda-sample-project repository. Importing a public repository still
requires network access from the platform.
Credentials
Event-Driven Ansible credentials are separate from automation controller credentials. Open Automation Decisions > Infrastructure > Credentials to create them.
To launch a controller job, use a credential of type Red Hat Ansible Automation Platform. This is the actual type label in the UI; it can connect to the controller of this Koios Automation Platform deployment. Select the credential in the activation’s Credential field.
Field |
Value for this platform |
|---|---|
Red Hat Ansible Automation Platform |
|
Username and Password, or OAuth Token |
A platform user or its token with permission to launch the target job template. Use one authentication method; see Tokens. |
Verify SSL |
Enabled for the public HTTPS address. The decision environment must trust the certificate issuer; |
The platform credential authenticates the action that launches a job. A Basic Event Stream credential instead authenticates an event sender, and a Container Registry credential pulls an image. These credentials serve different purposes.
Rulebook activations
Create an activation in Automation Decisions > Rulebook Activations after the project import has completed. Select its Project, Rulebook, Decision environment, Credential when needed, Restart policy and Variables. Keep Rulebook activation enabled? on to start it.
The first activation tutorial runs a finite source, fires Run JT at 8, and checks a successful Demo Job Template job in Automation Execution > Jobs. Use Automation Decisions > Rule Audit to inspect the event and action that fired the rule. For a listener, Running means it is waiting for events, not that a rule has already fired.
Event streams
An event stream receives HTTP events through the platform address under /eda-event-streams/.
The sender authenticates with the stream’s credential. It does not use a platform user’s login
session to send events to that endpoint.
In the activation’s Event streams field, map the rulebook source to the stream. The mapping changes that activation, not the rulebook in Git; the activation receives stream events instead of opening the original source’s listener port. See Receive events with event streams for a Basic-authenticated example and the available credential types.
Note
The mTLS Event Stream credential type exists, but client-certificate event stream ingress is not available through the current Koios Automation Platform gateway route. See the mTLS limitation before choosing that type.
Backup and restore
Backups include Event-Driven Ansible’s database, encryption key and administrator. A restored copy can still contain credentials that point to the original platform. Update those connections before enabling activations and schedules in the copy.