From 2f27e94da89587755d47df2ce038576bb4274a3a Mon Sep 17 00:00:00 2001 From: Angel Date: Wed, 11 Dec 2024 18:47:53 -0500 Subject: [PATCH] event hooks docs --- .../upstream/example-upstream.yml | 5 + app/_gateway_entities/event_hooks.md | 132 ++++++++++++++++++ app/_how-tos/create-a-custom-webhook.md | 27 ++++ app/_how-tos/create-a-lambda-event-hook.md | 54 +++++++ app/_how-tos/create-a-log-webhook.md | 46 ++++++ app/_how-tos/create-a-webhook.md | 78 +++++++++++ app/_landing_pages/gateway/entities.yaml | 4 + 7 files changed, 346 insertions(+) create mode 100644 app/_data/entity_examples/upstream/example-upstream.yml create mode 100644 app/_gateway_entities/event_hooks.md create mode 100644 app/_how-tos/create-a-custom-webhook.md create mode 100644 app/_how-tos/create-a-lambda-event-hook.md create mode 100644 app/_how-tos/create-a-log-webhook.md create mode 100644 app/_how-tos/create-a-webhook.md diff --git a/app/_data/entity_examples/upstream/example-upstream.yml b/app/_data/entity_examples/upstream/example-upstream.yml new file mode 100644 index 00000000..793eddea --- /dev/null +++ b/app/_data/entity_examples/upstream/example-upstream.yml @@ -0,0 +1,5 @@ +name: my-upstream +paths: + - /upstreams +service: + name: example-upstreams \ No newline at end of file diff --git a/app/_gateway_entities/event_hooks.md b/app/_gateway_entities/event_hooks.md new file mode 100644 index 00000000..e0f8cb1f --- /dev/null +++ b/app/_gateway_entities/event_hooks.md @@ -0,0 +1,132 @@ +--- +title: Event hooks +content_type: reference +entities: + - event_hooks + +description: Event hooks allow Kong Gateway to communicate with target services or resources, notifying the target resource that an event was triggered. +related_resources: + - text: Services + url: /gateway/entities/service/ + - text: Routing in {{site.base_gateway}} + url: /gateway/routing/ + +tools: + - admin-api + - kic + - terraform +schema: + api: gateway/admin-ee + path: /schemas/Event-hooks + +--- + + +## How do Event Hooks work? + +{{site.base_gateway}} Event Hooks work by configuring the following three elements: + +* Sources: The actions or operation that trigger the event hook. +* Events: The Kong entity that the event hook monitors for actions. +* Handlers: The mechanism that defines what action is performed when an event is triggered, like sending a webhook, logging, or executing custom code. + +{% mermaid %} +flowchart LR + E["Event Detected"] + F["Handler Activated"] + G["Action Executed"] + E --> F + F --> G + +{% endmermaid %} + +### Handlers + +There are four types of handlers that can be used with the Event Hooks entity: + +* **`webhook`**: Issues a `POST` request to a provided URL with the event data as a payload. +* **`log`**: Logs the event and the content of the payload as a Kong Gateway log. +* **`webhook-custom`**: Fully configurable request. Supports templating, configurable body, payload, and headers. +* **`lambda`**: This handler runs Lua code after an event is triggered. + + +### Sources + +{{site.base_gateway}} offers the [`/event-hooks/sources`](/api/admin-ee/latest/#/Event-hooks/get-event-hooks-sources) endpoint where you can see all available sources, events and fields that are available for creating event hook templates. Sources are the actions that trigger the event hook. + + + +The response body from the endpoint describes a source that can be interepreted in the following pattern: + +1. **Level 1**: The source, the action that triggers the event hook. +2. **Level 2**: The event, this is the {{site.base_gateway}} entity that the event hook listens to for events. +3. **Level 3**: The available template parameters for constructing `webhook-custom` payloads. + +This is an example response body: + + +```json +{ + "data": { + "balancer": { + "health": { + "fields": [ + "upstream_id", + "ip", + "port", + "hostname", + "health" + ] + } + } + } +} +``` + +You can apply the pattern to the response body and extract the following information: + + +* **event**: `health` +* **source**: `balancer` +* **handler**: `webhook-custom` + +The values in the `fields` array represent the availble template parameters you can use when constructing a payload. + +* `upstream_id` +* `ip` +* `port` +* `hostname` +* `health` + +These parameters can be used to issue notifications any time an upstream in your application is not reachable. + +For step-by-step guides on configuring event hooks see the following docs: + +* [How to configure a custom webhook](/how-to/create-a-custom-webhook) +* [How to create a log event hook](/how-to/create-a-log-event-hook) +* [How to create a lambda event hook](/how-to-create-a-lambda-event-hook) + + + + +## Schema + +{% entity_schema %} + + + +## Configure an event hook + + + curl --request POST \ + --url http://localhost:8001/event-hooks \ + --header 'Content-Type: application/json' \ + --header 'Kong-Admin-Token: kongAdminToken' \ + --data '{ + "source": "crud", + "event": "admins:create", + "handler": "webhook", + "config": { + "url": "http:///admin-1created" + } + }' diff --git a/app/_how-tos/create-a-custom-webhook.md b/app/_how-tos/create-a-custom-webhook.md new file mode 100644 index 00000000..b0fc124f --- /dev/null +++ b/app/_how-tos/create-a-custom-webhook.md @@ -0,0 +1,27 @@ +--- +title: Create a custom webhook to push information to Slack +content_type: how_to + +related_resources: + - text: Event hooks + url: /gateway/entities/event_hooks + +works_on: + - on-prem + +tags: + - eventhooks + - webhook + - notifications +tldr: + q: How do I create a custom webhook using eventhooks + a: Send a `POST` request to the event_hooks endpoint containing the source, event, template and URL for your webhook. + +prereqs: + entities: + upstream: + - example-upstream + routes: + - example-route +--- +ssss \ No newline at end of file diff --git a/app/_how-tos/create-a-lambda-event-hook.md b/app/_how-tos/create-a-lambda-event-hook.md new file mode 100644 index 00000000..ebe322c3 --- /dev/null +++ b/app/_how-tos/create-a-lambda-event-hook.md @@ -0,0 +1,54 @@ +--- +title: Run custom code in a event hook +content_type: how_to + +related_resources: + - text: Event hooks + url: /gateway/entities/event_hooks + +works_on: + - on-prem + +tags: + - eventhooks + - webhook + - notifications +tldr: + q: How do I write custom code in an event hook + a: Send a `POST` request to the event_hooks endpoint containing the source and event for the webhook. +--- + +## Create a lambda event hook + +1. Create a lua script to load into the lambda event hook. + + ```lua + return function (data, event, source, pid) + local user = data.entity.username + error("Event hook on consumer " .. user .. "") + end + ``` +2. Create a lambda event hook on the `consumers` event, with the `crud` source by creating a `POST` request to the Admin API. + + curl -i -X POST http://localhost:8001/event-hooks \ + -d source=crud \ + -d event=consumers:update \ + -d handler=lambda \ + -d on_change=true \ + -d config.functions='return function (data, event, source, pid) local user = data.entity.username error("Event hook on consumer " .. user .. "") end' + +## Validate the webhook + + +1. Using the Admin API create a new consumer: + + ```sh + curl -i -X POST http://localhost:8001/consumers \ + -d username="my-consumer" + ``` +2. Review the logs at `/usr/local/kong/logs/error.log` for an an update about the creation of this consumer. The log will look similar to this: + + ```sh + 2021/07/29 21:52:54 [error] 114#0: *153047 [kong] event_hooks.lua:190 [string "return function (data, event, source, pid)..."]:3: Event hook on consumer my-consumer, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 + + ``` diff --git a/app/_how-tos/create-a-log-webhook.md b/app/_how-tos/create-a-log-webhook.md new file mode 100644 index 00000000..e8945e0c --- /dev/null +++ b/app/_how-tos/create-a-log-webhook.md @@ -0,0 +1,46 @@ +--- +title: Create a log event hook to monitor consumer events +content_type: how_to + +related_resources: + - text: Event hooks + url: /gateway/entities/event_hooks + +works_on: + - on-prem + +tags: + - eventhooks + - webhook + - notifications +tldr: + q: How do I create a log webhook to monitor consumer events + a: Send a `POST` request to the event_hooks endpoint containing the source and event for the webhook. +--- + +## Create the event hook + +Create a long event hook on the `consumers` event using the `crud` source. + +```sh + curl -i -X POST http://{HOSTNAME}:8001/event-hooks \ + -d source=crud \ + -d event=consumers:update \ + -d handler=log \ + -d on_change=true +``` + +## Validate the webhook + + +1. Using the Admin API create a new consumer: + + ```sh + curl -i -X POST http://localhost:8001/consumers \ + -d username="my-consumer" + ``` +2. Review the logs at `/usr/local/kong/logs/error.log` for an an update about the creation of this consumer. The log will look similar to this: + + ```sh + 192.168.65.1 - - [11/Dec/2024:23:20:56 +0000] "POST /consumers HTTP/1.1" 201 183 "-" "-" + ``` \ No newline at end of file diff --git a/app/_how-tos/create-a-webhook.md b/app/_how-tos/create-a-webhook.md new file mode 100644 index 00000000..05d751ae --- /dev/null +++ b/app/_how-tos/create-a-webhook.md @@ -0,0 +1,78 @@ +--- +title: Create a webhook that monitors Consumer creation +content_type: how_to + +related_resources: + - text: Event hooks + url: /gateway/entities/event_hooks + +works_on: + - on-prem + +tags: + - eventhooks + - webhook + - notifications +tldr: + q: How do I create a webhook that monitors for the creation of new consumers? + a: Send a `POST` request to the event_hooks endpoint containing the source, event, template and URL for your webhook. + +prereqs: + inline: + - title: A webhook URL + content: | + * You can gnerate a URL by navigating to https://webhook.site and copying the free URL. +--- + + +## Create a webhook + +1. Using the Admin API, create an event hook on the consumers event by issuing a `POST` request to the `/event-hooks` endpoint. + + curl -i -X POST http://localhost:8001/event-hooks \ + -d source=crud \ + -d event=consumers:update \ + -d handler=webhook \ + -d on_change=true \ + -d config.url=https://webhook.site/94688621-990a-407f-b0b2-f92322d04c700" + +2. Issuing this `POST` request will send a request of type `ping` to the webhook URL verifying that the webhook is configured correctly. + + + +## Validate the webhook + + +1. Using the Admin API create a new consumer: + + ```sh + curl -i -X POST http://localhost:8001/consumers \ + -d username="my-consumer" + ``` +2. Verify on webhook.site that you received a `POST` request. It will look like this: + + ```json + { + "event_hooks": { + "id": "88a0d071-29c8-4d6a-827e-dbecf09e917c", + "event": "consumers:update", + "updated_at": 1733955343, + "config": { + "headers": { + "content-type": "application/json" + }, + "ssl_verify": false, + "url": "https://webhook.site/94688621-990a-407f-b0b2-123923ad04c700" + }, + "source": "crud", + "created_at": 1733955343, + "handler": "webhook", + "on_change": true + }, + "operation": "create", + "source": "kong:event_hooks", + "event": "ping" + } + ``` + +This response body contains the `operation`, the `source`, and the `event`, confirming that a new user was created \ No newline at end of file diff --git a/app/_landing_pages/gateway/entities.yaml b/app/_landing_pages/gateway/entities.yaml index 4d88cdf8..b992a544 100644 --- a/app/_landing_pages/gateway/entities.yaml +++ b/app/_landing_pages/gateway/entities.yaml @@ -52,3 +52,7 @@ rows: - type: entity_card config: entity: workspace + - blocks: + - type: entity_card + config: + entity: event_hooks