-
Notifications
You must be signed in to change notification settings - Fork 1
10. webhooks
Push approach: HTTP POST to push data to StackStorm API from a script or software when an event you are interested in occurs.
The ST2 rule engine monitor triggers on the message bus (RabbitMQ).
In ST2, a trigger refers to the internal representation in ST2 of an external event.
With ST2 you can create your own sensors which allow you to define the trigger structure.
We are going to use custom webhook which has already a built-in trigger, so there is no need to define this trigger yourself in that case.
What's the diff between a regular rest call (toward ansible tower as example) and a custom webhook in ST2?
ST2 webhook is a characterization of an (no ST2) event. You are just transmitting to ST2 some sort of information. Then ST2 rule engine will decide what to do with these details. Because there is a rule engine between events and potential actions, one event can fire off many actions.
Using a regular rest call to a system (ansible tower ...) is a more imperative approach where you are requesting an very tool-related thing. Also there is one to one_only relationship between the rest call and the its outcome.
You need to use an ST2 rule in a yaml file.
You can write a new rule yourself or use an existing one
How to get the list of existing rules from a pack:
$ sudo st2 rule list -p napalm
+--------------------------------------+--------+----------------------------------------------+---------+
| ref | pack | description | enabled |
+--------------------------------------+--------+----------------------------------------------+---------+
| napalm.bgp_prefix_exceeded | napalm | Webhook which handles a BGP neighbor | True |
| | | exceeding it's prefix limit | |
| napalm.configuration_change | napalm | Webhook which handles when a device has been | True |
| | | configured and changes commited | |
| napalm.interface_down | napalm | Webhook which handles an interface going | True |
| | | down on a network device. | |
+--------------------------------------+--------+----------------------------------------------+---------+
Let's create a rule that fire off the get_bgp_neighbors_detail action from the Napalm pack. get help with the action get_bgp_neighbors_detail from Napalm pack:
$ sudo st2 run napalm.get_bgp_neighbors_detail -h
Get a detailed BGP neighbor from a device using NAPALM.
Required Parameters:
hostname
The hostname of the device to connect to. Driver must be specified if
hostname is not in configuration. Hostname without FQDN can be given
if device is in configuration.
Type: string
neighbor
The BGP neighbor to get details of.
Type: string
Optional Parameters:
driver
Device driver name for connecting to device, see
https://napalm.readthedocs.io/en/latest/support/index.html for list.
Type: string
port
port for accessing device
Type: string
credentials
The credentials group which contains the username and password to log
in
Type: string
htmlout
In addition to the normal output also includes html output.
Type: boolean
env
Environment variables which will be available to the script.
Type: object
timeout
Action timeout in seconds. Action will get killed if it doesn't finish
in timeout seconds.
Type: integer
Default: 600
$ pwd
/opt/stackstorm/packs/napalm/rules
lets create this new rule
$ more rule_get_bgp_neighbors_details.yaml
---
# once the rule is created (using the "st2 rule create" command, this rule reference will be generated napalm.rule_get_bgp_neighbors_detail)
name: "rule_get_bgp_neighbors_detail"
pack: "napalm"
enabled: true
description: "Webhook which get and display the BGP neighbors detail"
# this is required
# the rule engine watches triggers in Rabbit MQ.
# this rule has core.st2.webhook trigger type.
# which means, this rule get fired when an HTTP POST toward the url http://ST2:9101/v1/webhooks/napalm_get_bgp_neighbors_detail is received.
# when the POST is received, nginx generates a trigger_instance that has core.st2.webhook type with the details from the POST.
# Then the rule engine can use this trigger_instance to fire off the action
trigger:
type: "core.st2.webhook"
parameters:
url: "napalm_get_bgp_neighbors_details"
# this is optionnal. you can use this section to introduce additionnal matching conditions (using http headers or http body).
criteria: {}
# first select the action ref you want to use
# define how to pass action parameters, i.e define how trigger_instance data (which come initially from HTTP POST headers and body) are passed as action´s paramters.
# the a
action:
ref: napalm.get_bgp_neighbors_detail
parameters:
hostname: "{{trigger.body.hostname}}"
neighbor: "{{trigger.body.neighbor}}"
we also need to register the rule:
$ sudo st2 rule create rule_get_bgp_neighbors_details.yaml
+-------------+----------------------------------------------------------+
| Property | Value |
+-------------+----------------------------------------------------------+
| id | 5937bfa3a374d84239058e10 |
| name | rule_get_bgp_neighbors_detail |
| pack | napalm |
| description | Webhook which get and display the BGP neighbors detail |
| action | { |
| | "ref": "napalm.get_bgp_neighbors_detail", |
| | "parameters": { |
| | "hostname": "{{trigger.body.hostname}}", |
| | "neighbor": "{{trigger.body.neighbor}}" |
| | } |
| | } |
| criteria | |
| enabled | True |
| ref | napalm.rule_get_bgp_neighbors_detail |
| tags | |
| trigger | { |
| | "type": "core.st2.webhook", |
| | "ref": "core.a3951df7-edf3-4019-ac7e-51811465aa1f", |
| | "parameters": { |
| | "url": "napalm_get_bgp_neighbors_details" |
| | } |
| | } |
| type | { |
| | "ref": "standard", |
| | "parameters": {} |
| | } |
| uid | rule:napalm:rule_get_bgp_neighbors_detail |
+-------------+----------------------------------------------------------+
$ sudo st2 rule get napalm.rule_get_bgp_neighbors_detail
+-------------+----------------------------------------------------------+
| Property | Value |
+-------------+----------------------------------------------------------+
| id | 5937bfa3a374d84239058e10 |
| uid | rule:napalm:rule_get_bgp_neighbors_detail |
| ref | napalm.rule_get_bgp_neighbors_detail |
| pack | napalm |
| name | rule_get_bgp_neighbors_detail |
| description | Webhook which get and display the BGP neighbors detail |
| enabled | True |
| action | { |
| | "ref": "napalm.get_bgp_neighbors_detail", |
| | "parameters": { |
| | "hostname": "{{trigger.body.hostname}}", |
| | "neighbor": "{{trigger.body.neighbor}}" |
| | } |
| | } |
| criteria | |
| tags | |
| trigger | { |
| | "type": "core.st2.webhook", |
| | "ref": "core.a3951df7-edf3-4019-ac7e-51811465aa1f", |
| | "parameters": { |
| | "url": "napalm_get_bgp_neighbors_details" |
| | } |
| | } |
| type | { |
| | "ref": "standard", |
| | "parameters": {} |
| | } |
+-------------+----------------------------------------------------------+