Exercise 4: Event-Driven Ansible Rulebooks

Overview

NetBox and Event-Driven Ansible Integration

Ansible Automation Platform is a powerful tool for network automation, and integrating it with NetBox enhances its capabilities. Ansible uses NetBox as a Network Source of Truth (NSoT) to ensure accuracy in managing network devices, connections, and services.

By leveraging Event-Driven Ansible (EDA), Ansible Automation Platform can react to real-time events from NetBox, such as new devices being added or configuration changes being approved. This eliminates the need for manual intervention or scheduled tasks, enabling fully automated, dynamic network management.

Lab Environment

The following services are available in your lab environment:

Service Purpose Access Port

AAP

Ansible Automation Platform Web UI

443

NetBox Web

NetBox Web Interface

8000

VS Code

Visual Studio Code Editor

80

NetBox Term

NetBox Command Line

N/A

Terminal AAP

AAP Command Line

N/A

Lab Credentials

Ansible Automation Platform Credentials:

  • Username: admin

  • Password: ansible123!

NetBox Credentials:

  • Username: admin

  • Password: netbox

Task 1: Create the EDA Project

Overview

In this exercise, we will create a Rulebook activation and a Job Template that performs remediation when a certain event occurs.

Currently, not all fields of an EDA Project can be edited after creation. If there is a mistake in the "Source control URL" for example, you will need to delete and recreate the EDA Project.

Create the Project

Step 1: Switch to the AAP tab.

Step 2: Navigate to menu:Automation Decisions[Projects].

Step 3: Click the blue Create project button.

Step 4: Fill in the form with the following details:

Field Value

Name

netbox-rulebooks-project

Organization

Default

Source Control Type

Git

Source Control URL

`https://github.com/ansible-tmm/aap-netbox-rulebooks-cisco-live.git`

Step 5: Click the blue Create project button at the bottom.

Create EDA Project

Step 6: Wait for the project to show a green tick and Completed in the Status column, then move on to the next step.

Project Status Completed

Task 2: Explore EDA Credentials

Understanding the AAP Credential

This credential allows EDA to run the desired action (Job Template) when a condition is triggered.

Step 1: Navigate to menu:Automation Decisions[Infrastructure > Credentials].

Step 2: You will notice there is an AAP credential already created.

Step 3: Click on the AAP credential to review its configuration.

We pre-loaded this credential as the URL is internal to the workshop platform. Be careful not to change the settings.

Step 4: The credential form should look like this:

AAP Credential Configuration

Step 5: Click the Cancel button to leave the Credential screen without making changes.

Task 3: Create the Rulebook Activation

Overview

Now we are going to create the Rulebook Activation, basically the service that will be listening to our rules in the Rulebook Project we created earlier.

Make sure to fill everything correctly and pick the AAP credential. EDA Rulebooks currently can’t be edited, and an error while creating it will require you to delete it and recreate it, just like with EDA Projects.

Create the Activation

Step 1: Navigate to menu:Automation Decisions[Rulebook Activations].

Step 2: Click the blue Create rulebook activation button.

Step 3: Fill in the form with the following details:

Field Value

Name

NetBox Rulebooks

Organization

Default

Project

netbox-rulebooks-project

Rulebook

netbox-webhook.yml

Credentials

AAP

Decision Environment

NetOps Decision Environment

Restart Policy

Always

Log Level

Info

Rulebook Activation Enabled?

Yes (checked)

Step 4: Leave the rest of the fields as-is.

Step 5: Click the blue Create rulebook activation button at the bottom.

Step 6: You will see the details of the Rulebook Activation with the Activation status: Starting.

Step 7: Wait a few seconds. The status will change to Activation status: Running if everything was successful.

Rulebook Activation Running

A running activation means your rulebook is now actively listening for events from NetBox and ready to respond automatically!

Task 4: Explore Our Rulebook

Rulebook Structure

Below you can check the Rulebook we imported. This rulebook contains 5 rules - those are the conditions we are going to be listening for from NetBox.

---
- name: Listen for NetBox events on a webhook
  hosts: all
  sources:
    - ansible.eda.webhook:
        host: 0.0.0.0
        port: 5001

  rules:
  - name: NTP updates
    condition: event.payload.event == "updated" and event.payload.model == "configcontext" and event.payload.data.name == "ntp_servers"
    action:
      run_job_template:
        organization: "Default"
        name: "Configure NTP Servers"

  - name: VLAN created
    condition: event.payload.event == "created" and event.payload.model == "vlan"
    action:
      run_job_template:
        organization: "Default"
        name: "Configure VLANs"

  - name: VLAN deleted
    condition: event.payload.event == "deleted" and event.payload.model == "vlan"
    action:
      run_job_template:
        organization: "Default"
        name: "Configure VLANs"

  - name: Update login banner
    condition: event.payload.event == "updated" and event.payload.model == "updated" and event.payload.data.name == "login_banner"
    action:
      run_job_template:
        organization: "Default"
        name: "Configure Login Banner"

  - name: New Device Added
    condition: event.payload.event == "created" and event.payload.model == "device"
    action:
      run_workflow_template:
        organization: "Default"
        name: "Provision New Device Workflow"

How This Rulebook Works

Event Source

This rulebook uses the ansible.eda.webhook source plugin to listen for events from the NetBox webhook. NetBox will forward the payload, which EDA will receive and classify according to the conditions in each rule.

The Five Rules

This rulebook contains five distinct rules that monitor different NetBox events:

  1. NTP Updates - Triggers when NTP server configuration context is updated

  2. VLAN Created - Triggers when a new VLAN is created in NetBox

  3. VLAN Deleted - Triggers when a VLAN is deleted from NetBox

  4. Login Banner - Triggers when the login banner configuration is updated

  5. New Device Created - Triggers when a new device is added to NetBox

Conditions and Actions

Each rule has its own set of conditions (what to listen for) and action (what playbook to run). We are checking the payload for three key matches:

  1. The event type (created, updated, deleted)

  2. The NetBox model being affected (device, vlan, configcontext)

  3. Specific data attributes (like name fields)

Once a rule is matched, the associated Job Template or Workflow Template will be launched automatically.

Key Difference: Rulebooks vs. Playbooks

Ansible Rulebooks operate differently than Ansible Playbooks:

  • A Rulebook Activation runs constantly, listening for events

  • A Job Template is executed on demand when triggered

This enables true event-driven automation!

Summary

In this exercise, you’ve accomplished the following:

  • Created an EDA Project that contains your rulebooks

  • Explored EDA credentials that enable automation execution

  • Created and activated a Rulebook Activation that listens for NetBox events

  • Learned how rulebooks use conditions and actions to respond to events

Your Event-Driven Ansible setup is now ready to automatically respond to changes in NetBox!

Next Steps

Excellent work! You’ve successfully configured Event-Driven Ansible to listen for NetBox events and automatically trigger automation.

Step 1: Press the Next button below to go to the next challenge.

Troubleshooting

NetBox Startup Issues

NetBox needs a couple of minutes to get started.

If you can’t see the NetBox login screen:

Step 1: Go to the netbox term tab.

Step 2: Run the following command to stop NetBox:

docker compose --project-directory=/tmp/netbox-docker stop

Step 3: Run the following command to restart NetBox services:

docker compose --project-directory=/tmp/netbox-docker up -d netbox netbox-worker

Step 4: Wait 2-3 minutes for the services to fully start, then try accessing NetBox again.

End of Exercise 4