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 ansible.eda.range or ansible.eda.webhook.

Rule

A named condition and its action or actions. For example, event.i == 8 matches a particular event from the range source.

Action

Work performed when a condition matches: for example, debug or run_job_template. Launching a job requires a credential with access to automation controller.

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

https://<platform>/api/controller/, including the controller path. An administrator can use http://<platform>-gateway/api/controller/ for in-cluster access when appropriate for the deployment.

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; bundle_cacert_secret is not automatically mounted into the decision environment. Use a custom image with the required CA when needed.

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.