ansible-rulebook

An Ansible Rulebook is a YAML-based file used to codify operational logic for Event-Driven Ansible (EDA). Unlike traditional Ansible Playbooks which follow a linear sequence of tasks, Rulebooks use an "if-this-then-that" approach to respond to events.

Rulebooks are processed by a rules engine (built using Drools) and are comprised of three main components:

1. Sources: Define the event listening source. Examples include webhooks, Kafka, Azure service bus, file changes, and alertmanager.
2. Rules: Define the conditional logic used to match incoming events from a source. If a condition is met, an action is triggered.
3. Actions: The tasks executed when a rule matches. Common actions include:
   • run_playbook: Executes an Ansible Playbook.
   • run_module: Executes an Ansible module directly.
   • set_fact: Sets facts within the rulebook context.
   • post_event: Posts a new event back to the event handler.
   • debug: Provides debugging information.

Because the eda_feedback_queue is shared per source plugin instance, if your plugin processes messages concurrently, you cannot simply wait for the next item in the queue. You must correlate the feedback with the specific event.

Option 1: Serialized Processing (Simplest) Process one message at a time. Wait for the feedback of the current message before moving to the next one in the loop. This is the safest and easiest pattern to implement.

Option 2: Tracking In-Flight Events (High Performance) If you must process messages concurrently, maintain a local mapping (e.g., a dictionary) of uuid -> (message, commit_future).

1. Start a background task to continuously consume from eda_feedback_queue.
2. When feedback arrives, look up the uuid in your mapping.
3. Signal the specific message's Future that it is safe to commit.
4. The main loop awaits the Future for that specific message before calling consumer.commit().

# Option 2: Tracking in-flight events snippet
import asyncio

pending_events = {}  # uuid -> (message, commit_future)

async def process_feedback(eda_feedback_queue):
    while True:
        feedback = await eda_feedback_queue.get()
        uuid = feedback.get("meta", {}).get("uuid")

        if uuid in pending_events:
            message, future = pending_events.pop(uuid)
            future.set_result(message)  # Signal ready to commit
        else:
            logger.warning("Received feedback for unknown UUID: %s", uuid)

Event filters allow you to preprocess, modify, enrich, or transform event data before it reaches the rule engine. This is useful for removing unnecessary information or reshaping data so it matches your rule conditions.

Key Concepts

• Chaining: Filters can be chained together. The output of one filter becomes the input for the next.
• Placement: Filters are defined in the rulebook under a sources section, immediately following the source definition.
• Execution: When the rulebook starts a source plugin, it associates the defined filters and transforms the data before placing it into the event queue.
• Data Access: You can access nested keys in the event payload using dot (.) notation.
• Key Constraints: Event payload keys should ideally contain only letters, numbers, and underscores.

Custom Filters

When developing your own filters, you can use the -F flag to specify a local directory containing them. Note that if you are using a Decision Environment, filters must be distributed via an Ansible collection.

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:

The any keyword triggers a rule as soon as any one of the provided conditions matches a distinct incoming event.

Critical Rules for any conditions:

1. Use events (plural): Even though only one event triggers the rule, you must use the events prefix to access the matching event (e.g., events.m_0).
2. Custom Naming: Use the << operator to assign the matching event to a custom name like events.match for easier access in actions.
3. Difference from or: any evaluates different incoming events. To check multiple attributes on a single event, use the or operator.

Warning: Using any to check different values for the same attribute (e.g., event.os == 'linux' or event.os == 'windows') will wait for two different events to arrive, which is usually not the intended behavior for a single event check.

# Using custom assignment for readability
name: Monitor different event types with custom name
condition:
  any:
    - events.match << event.temperature == 85
    - events.match << event.user == "alice"
    - events.match << event.inventory == 42
action:
  debug:
    msg: "Found a match: {{ events.match }}"