Develop an Event Driven Ansible Controller Rulebook with Webhook

This topic explains how a rulebook gets triggered in the Event Driven Ansible Controller (EDA) when it receives a Webhook request.

It also describes how to activate a rulebook in EDA and set up a Webhook in GitHub.


Webhook

Enabling Webhook in GitHub

Before proceeding with the Webhook setup, ensure you have the appropriate (admin or owner) role for the repository. Select the repository from which you want to receive the Webhook. This setup uses a repository named ibm-eda-webhook:

  1. Select the Settings. EDA Webhook Setting

  2. Select Code and automation -> Hooks. Click Add webhook. EDA Add Webhook

  3. Now provide the Payload URL, for example, https://eda.example.com:5001, to which you want to receive the payload. Select the application/json as content type and select the events to which you want to trigger the Webhook and click Add webhook.

Note: Make sure eda.example.com is resolvable from GitHub. You might need to change the DNS server setting in your network.
EDA Webhook Setting

Simulating Webhook with curl

For quick testing you can also use the curl command to create a Webhook request on EDA.

curl -H 'Content-Type: application/json' -d "{\"message\": \"This is an example message\"}" 127.0.0.1:5001/endpoint

Creating firewall rules in EDA

To allow the Webhook to reach the EDA machine, open port 5001. Run the following command in EDA:

firewall-cmd --permanent --add-port 5001/tcp
firewall-cmd --reload

Creating the rulebook and connecting with EDA

  1. The rulebook in the following sample launches the job template -> ansible KVM guest installation in AAC when it receives a Webhook request from the repository ibm-eda-webhook.Sample rulebook:

    - name: Webhook Events
  hosts: localhost
  sources:
    - ansible.eda.webhook:
        host: 0.0.0.0
        port: 5001
  rules:
    - name: Trigger Example Playbook on demand
      condition:
        all:
          - event.payload.repository.name == "ibm-eda-webhook"
      action:
        run_job_template:
          name: ansible kvm guest installation
          organization: Default
Note: Check this link to learn about the ruleset properties.
  1. Create a new repository called eda-rulebooks and place the rulebook from step 1 in this repository in the folder rulebooks. EDA Webhook setting
    Note: All the rulebooks created should be placed in a directory called rulebooks in their repository for the EDA to detect.

  2. Go to EDA to add your GitHub personal access token under Resources -> Credentials for the EDA to access your rulebook git repository, by selecting Create Credential.

    • Provide your Username and Token.

    • select GitHub personal access token from Credential typeand then click Create credential. EDA Webhook Token

  3. Add your rulebook git repository under Resources -> Projects, by selecting Create Project.

    • Provide the Name and SCM URL .

    • Select your git personal access token from the previous step under Credential, then click Create project. EDA Webhook Setting

  4. For the Event Driven Ansible Controller (EDA) to launch a job template in the Ansible Automation Controller (AAC), you need to connect the AAC with the EDA from the controller token generated from AAC.

    • Log in to AAC, select the Access -> Users. From the Users list select the admin. AAC User token

    • Select Tokens -> Add. AAC User token

    • Provide the Description and select the Scope has Write. Click Save. AAC User token

    • Copy the Token, it is used in the next step. AAC User token

    • Log in to EDA, select User Access -> Users. From the Users list, select admin. AAC User token

    • Select the Controller tokens. Now provide the Name and paste the copied token in Token.

    • Click Create controller token. AAC User token

  5. Activate the "eda-rulebook.yml" rulebook by selecting Create rulebook activation under Views -> Rulebook Activations.

    • Provide the Name.

    • Select your Project from the previous step from the drop-down.

    • Select the Rulebook and Decision Environment.

    • Activate your rulebook by clicking Create rulebook activation EDA Webhook Setting

    • Make sure the rulebook is in a Running state after it is created. EDA Webhook Setting

The Webhook in action

  1. Assume that the Webhook gets triggered from the ibm-eda-webhook repository.

  2. GitHub sends the payload to https://eda.example.com:5001.

  3. After the payload reaches https://eda.example.com:5001, it triggers the rulebook in the EDA and the Fire count changes from 0 to 1. EDA Webhook Setting

  4. Fire count with a value of 1 triggers the job template -> ansible KVM guest installation in the AAC as described in the rulebook under action. EDA Webhook Action

  5. Go to AAC Views -> Jobs. The Ansible KVM guest installation is successful. Launch job template