イベントフックの例
イベントフックはKong Gatewayからのアウトバウンドコールです。イベントフックを使用すると、Kong Gateway は ターゲットのサービスやリソースと通信して、イベントがトリガーされたことをターゲットに 知らせます。Kongでイベントがトリガーされると、そのイベントに関する情報を含むURLが呼び出されます。 イベントフックは、管理インターフェースを使用してワーカーイベントをサブスクライブするための構成レイヤーを 追加します。ワーカーイベントは、ゲートウェイコンテキスト内で通信するためにKong Gatewayに統合されます。 たとえば、エンティティが作成されると、 Kong Gatewayはエンティティに関する情報を含むイベントを発生させます。Kong Gateway コードベースの一部はこれらのイベントをサブスクライブし、コールバックを使用してイベントを処理できます。
Kong Gatewayでは、これらのコールバックは以下のいずれかの「ハンドラ」を使用して定義できます。
-
webhook: イベントデータをペイロードとして、指定されたURLにJSON POSTリクエストを行います。中間層の統合(Kongフックを受信する独自のwebhook)を構築する場合に役立ちます。リクエストに対して特定のヘッダーを構成できます。
-
webhook-custom: 完全に設定可能なリクエスト。サービス(Slack webhook など)があり、 直接統合の構築に便利です。完全に構成可能であるため、 設定がより複雑です。構成可能な本文、構成可能な形式のペイロード、およびヘッダーを サポートしています。
-
ログ: このハンドラは構成が不要で、イベントとペイロードの内容を Kong Gateway ログに記録します。ハイブリッドモードを使用している場合、
crud
およびdao:crud
のソースのログはコントロールプレーン(CP)のログに出力され、balancer
およびrate-limiting-advanced
のソースのログはデータプレーンのログに出力されます。 -
lambda: このハンドラは、イベントのトリガー後に、指定されたLuaコードを実行します。
Webフック
webhookイベントフックは、イベントデータをペイロードとして、指定されたURLにJSON POSTリクエストを送信します。この例では、webhookのテストに役立つサイトhttps://webhook.siteを使用します。
webhookイベントフックを作成する方法は次のとおりです。
-
ウェブブラウザでhttps://webhook.siteに移動してURLを生成します。
-
一意の URL の横にある クリップボードにコピー を選択します。
-
次のHTTPリクエストを使用して、
consumers
イベント(イベントのためにイベントフックがリッスンするKongエンティティ)上、crud
ソース上(ログをトリガーするアクション)、および 手順2でコピーしたURLにwebhookイベントフックを作成します。curl -i -X POST http://{HOSTNAME}:8001/event-hooks \ -d source=crud \ -d event=consumers \ -d handler=webhook \ -d config.url={WEBHOOK_URL}
-
手順2のURLに移動します。
ping
タイプのPOSTリクエストが表示され、このwebhookの作成について webhookエンドポイントに通知されます。 -
Kong Manager または Kong Admin API で、任意のワークスペースからコンシューマを追加します。
-
https://webhook.site ページから URL を確認します。 ペイロードに新しいコンシューマのデータを含むエントリが表示されます。
{ "source": "crud", "entity": { "created_at": 1627581878, "type": 0, "username": "Ada Lovelace", "id": "0fd2319f-13ea-4582-a448-8d11893026a8" }, "event": "consumers", "operation": "create", "schema": "consumers" }
カスタムwebhook
カスタム webhook イベントフックは完全にカスタマイズ可能なリクエストです。カスタムWebhookは、 サービスとの直接統合を構築するのに便利です。カスタム Webhook は完全に構成可能であるため、より複雑な構成になります。 カスタム Webhook は、構成可能な本文、フォームペイロード、およびヘッダーでの Lua テンプレートをサポートします。テンプレートに使用できるフィールドの リストについては、ソースエンドポイントを参照してください。
次の例では、新しい管理者がKong Gatewayに招待されるたびにSlackにメッセージが送信されます。Slackでは着信ウェブフックが許可されており、これを使用して、Kongのイベントフック機能との統合を構築できます。
カスタム webhook イベントフックを作成するには以下のようにします。
-
新しいアプリの設定で受信ウェブフックを有効にします。
-
ワークスペースに新しいWebhookを追加 を選択し、通知を受け取るチャネルを選択して、 許可 を選択します。
-
Webhook URL (例:
https://hooks.slack.com/services/foo/bar/baz
)をコピーします。 -
admins
イベント(event hookがイベントをリッスンするKongエンティティ)とcrud
ソース(ロギングをトリガーするアクション)にwebhook event hookを作成します。次の HTTP 要求を使用して、ペイロードを「
"Admin account \
{{ entity.username }}` {{ operation }}d; e-mail address set to `{{ entity.email }}`”`」のようにフォーマットします。curl -i -X POST http://{HOSTNAME}:8001/event-hooks \ -d source=crud \ -d event=admins \ -d handler=webhook-custom \ -d config.method=POST \ -d config.url={WEBHOOK_URL} \ -d config.headers.content-type="application/json" \ -d config.payload.text="Admin account \`{{ entity.username }}\` {{ operation}}d; email address set to \`{{ entity.email }}\`"
-
RBACを有効にします。
RBAC を有効にするには、 Kong Gateway最初にインストールして移行を実行したときに使用した初期の KONG_PASSWORD が必要になります。これはスーパー管理者のデフォルトのパスワードでもあり、RBAC がオンになると必要になります。
このガイド以外では、インストールに応じてこれらの設定を異なる方法で変更する必要がある可能性があります。これらの設定の詳細については、Kong ManagerのBasic Authを参照してください。
-
Kong Manager または Kong Admin API を使用して管理者を招待します。
その後、お客様がconfig.payload.text
を含むメッセージを選択したSlackチャンネル内で、
メッセージを受信します。
ログ
ログイベントフックは、指定されたイベントとペイロードの内容をKong Gatewayログに記録します。
ログイベントフックを作成するには:
-
consumers
イベント (イベントフックがイベントをリッスンする Kong エンティティ)と、crud
ソース (ログ記録をトリガーするアクション) に、以下の HTTP リクエストを使用してログイベントフックを作成します。curl -i -X POST http://{HOSTNAME}:8001/event-hooks \ -d source=crud \ -d event=consumers \ -d handler=log
-
Kong Manager または Kong Admin API で、任意のワークスペースからコンシューマを追加します。
-
通常は、
/usr/local/kong/logs/error.log
からアクセスできるKongのエラーログのペイロードに、新しいコンシューマのデータが入ったエントリが表示されます。172.19.0.1 - - [29/Jul/2021:15:57:15 +0000] "POST /consumers HTTP/1.1" 409 147 "-" "HTTPie/2.4.0" 2021/07/29 15:57:26 [notice] 68854#0: *819021 +--------------------------------------------------+, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 |[kong] event_hooks.lua:?:452 "log callback: " { "consumers", "crud", {|, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | entity = { |, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | created_at = 1627574246, |, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | id = "4757bd6b-8d54-4b08-bf24-01e346a9323e",|, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | type = 0, |, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | username = "Elizabeth Bennet" |, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | }, |, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | operation = "create", |, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | schema = "consumers" |, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 | }, 68854 } |, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001 2021/07/29 15:57:26 [notice] 68854#0: *819021 +--------------------------------------------------+, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001
Lambda
ラムダイベントフックを使用すると、Luaコードで完全にカスタムロジックを記述でき、さまざまなKongイベントに組み込むことができます。次の例では、コンシューマが変更になるたびに、条件付きでカスタムフォーマットを使用してログエントリを書き込みます。
ラムダのイベントフックタイプは非常に強力です。完全にカスタムのロジックを書いて、どんなユースケースにも対応できます。 ただし、デフォルトではサンドボックスによって制限されています。この サンドボックスはユーザーの安全を守るために設置されています。誤って安全でないライブラリやオブジェクトを誤ってサンドボックスに追加し、 Kong Gatewayをセキュリティの脆弱性にさらしてしまうのは簡単だからです。サンドボックス設定を変更する際は注意してください。
Lambda イベントフックを作成するには以下のようにします。
-
Luaスクリプトを作成してラムダイベントフックに読み込み、ホームディレクトリの
lambda.lua
という名前のファイルに保存します。return function (data, event, source, pid) local user = data.entity.username error("Event hook on consumer " .. user .. "") end
-
次のHTTPリクエストを使用して、
consumers
イベント(イベントフックがイベントをリッスンするKongエンティティ)とcrud
ソース(ログ記録をトリガーするアクション)にラムダイベントフックを作成します。curl -i -X POST http://{HOSTNAME}:8001/event-hooks \ -d source=crud \ -d event=consumers \ -d handler=lambda \ -F config.functions='return function (data, event, source, pid) local user = data.entity.username error("Event hook on consumer " .. user .. "")end'
-
Kong ManagerまたはKong Admin APIで、任意のワークスペースにコンシューマを追加します。
-
Kongのエラーログに「コンシューマLois Laneのevent hook」というエントリが表示され、通常、
/usr/local/kong/logs/error.log
からアクセスできます。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 Lois Lane, context: ngx.timer, client: 172.19.0.1, server: 0.0.0.0:8001