コンテンツにスキップ
|
Kong Gateway
3.4.x LTS
report-issue問題を報告する
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。

イベントフックの例

イベントフックは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イベントフックを作成する方法は次のとおりです。

  1. ウェブブラウザでhttps://webhook.siteに移動してURLを生成します。

  2. 一意の URL の横にある クリップボードにコピー を選択します。

  3. 次の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}

  4. 手順2のURLに移動します。pingタイプのPOSTリクエストが表示され、このwebhookの作成について webhookエンドポイントに通知されます。

  5. Kong Manager または Kong Admin API で、任意のワークスペースからコンシューマを追加します。

    1. ワークスペースを選択します。
    2. 左のナビゲーションで コンシューマ を選択します。
    3. 新しいコンシューマ ボタンを選択します。
    4. ユーザー名 を入力します。
    5. （オプション） カスタム ID と 任意のタグ を入力します。
    6. 作成 ボタンを選択します。

    Kong Admin API のインスタンスに次の HTTP リクエストを送信して、コンシューマ Ada Lovelace を作成します。

    curl -i -X POST http://{HOSTNAME}:8001/consumers \
  -d username="Ada Lovelace"

  6. 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 イベントフックを作成するには以下のようにします。

  1. Slackでアプリを作成します。

  2. 新しいアプリの設定で受信ウェブフックを有効にします。

  3. ワークスペースに新しいWebhookを追加 を選択し、通知を受け取るチャネルを選択して、 許可 を選択します。

  4. Webhook URL （例： https://hooks.slack.com/services/foo/bar/baz）をコピーします。

  5. 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 }}\`"

  6. RBACを有効にします。

    RBAC を有効にするには、 Kong Gateway最初にインストールして移行を実行したときに使用した初期の KONG_PASSWORD が必要になります。これはスーパー管理者のデフォルトのパスワードでもあり、RBAC がオンになると必要になります。

    1. kong.confファイルの以下の構成設定を変更します。/etc/kong/kong.confファイルに移動します。

      cd /etc/kong/

    2. フォールバックできる作業コピーがあることを確認するために、 kong.conf.defaultファイルをコピーします。

      cp kong.conf.default kong.conf

    3. 次に、 kong.confで次の設定を編集します。

      echo >> “enforce_rbac = on” >> /etc/kong/kong.conf
echo >> “admin_gui_auth = basic-auth” >> /etc/kong.conf
echo >> “admin_gui_session_conf = {"secret":"secret","storage":"kong","cookie_secure":false}”

      これによりRBACがオンになり、Kong Gatewayにベーシック認証（ユーザー名/パスワード）を使用するよう指示し、セッションCookieの作成方法をSessionプラグインに指示します。

      クッキーは有効期限が切れるまで、ユーザーを認証するための後続のすべてのリクエストに使用されます。セッションの有効期間は限られており、構成可能な間隔で更新されるため、セッション終了後に攻撃者が古いクッキーを取得して使用することを防ぐことができます。

    4. Kong Gatewayを再起動し、以下のように新しい設定ファイルを指定します。

      kong restart -c /etc/kong/kong.conf

    Dockerがインストールされている場合は、次のコマンドを実行して必要な環境変数を設定し、ゲートウェイ構成を再読み込みします。

    注： {KONG-CONTAINER-ID}をコンテナのIDに確実に置き換えてください。

    echo "KONG_ENFORCE_RBAC=on
KONG_ADMIN_GUI_AUTH=basic-auth
KONG_ADMIN_GUI_SESSION_CONF='{\"secret\":\"secret\",\"storage\":\"kong\",\"cookie_secure\":false}'
kong reload exit" | docker exec -i {KONG_CONTAINER_ID} /bin/sh

    これによりRBACがオンになり、Kong Gatewayにベーシック認証（ユーザー名/パスワード）を使用するよう指示し、セッションCookieの作成方法をSessionプラグインに指示します。

    クッキーは有効期限が切れるまで、ユーザーを認証するための後続のすべてのリクエストに使用されます。セッションの有効期間は限られており、設定可能な間隔で更新されるため、セッション終了後に攻撃者が古いクッキーを取得して使用することを防ぐことができます。

    このガイド以外では、インストールに応じてこれらの設定を異なる方法で変更する必要がある可能性があります。これらの設定の詳細については、Kong ManagerのBasic Authを参照してください。

  7. Kong Manager または Kong Admin API を使用して管理者を招待します。

    1. Kong Managerにアクセスするか、すでに開いている場合はページを再読み込みすると、ログイン画面が表示されます。
    2. 組み込みのスーパー管理者アカウントkong_adminとそのパスワードでKong Managerにログインします。これは、インストール中に移行を実行したときに使用した初期KONG_PASSWORDです。
    3. チーム（Teams）> 管理者（Admins） タブから、 管理者を招待（Invite Admin） をクリックします。
    4. 新しい管理者の メールアドレス と ユーザー名 を入力します。
    5. 招待を送信するには、 管理者を招待 をクリックします。入門ガイドのこの時点では、SMTPがまだ設定されていない可能性が高いため、Eメールは送信されません。

    Kong Admin APIのインスタンスに次のHTTPリクエストを送信して、管理者Arya Starkを作成します。

    注意: {KONG_ADMIN_PASSWORD} をkong_adminパスワードに置き換えてください。これは インストール中に移行を実行したときに使用した最初のKONG_PASSWORDです。

    curl -i -X POST http://{HOSTNAME}:8001/admins \
-d username="Arya Stark" \
-d email=arya@gameofthrones.com \
-H Kong-Admin-Token:{KONG_ADMIN_PASSWORD}

その後、お客様がconfig.payload.textを含むメッセージを選択したSlackチャンネル内で、 メッセージを受信します。

ログ

ログイベントフックは、指定されたイベントとペイロードの内容をKong Gatewayログに記録します。

ログイベントフックを作成するには:

  1. consumersイベント (イベントフックがイベントをリッスンする Kong エンティティ)と、 crudソース (ログ記録をトリガーするアクション) に、以下の HTTP リクエストを使用してログイベントフックを作成します。

    curl -i -X POST http://{HOSTNAME}:8001/event-hooks \
  -d source=crud \
  -d event=consumers \
  -d handler=log

  2. Kong Manager または Kong Admin API で、任意のワークスペースからコンシューマを追加します。

    1. ワークスペースを選択します。
    2. 左のナビゲーションで コンシューマ を選択します。
    3. 新しいコンシューマ ボタンを選択します。
    4. ユーザー名 を入力します。
    5. （オプション） カスタム ID と 任意のタグ を入力します。
    6. 作成 ボタンを選択します。

    Kong Admin APIのインスタンスに次のHTTPリクエストを送信して、コンシューマであるElizabeth Bennetを作成します。

    curl -i -X POST http://{HOSTNAME}:8001/consumers \
-d username="Elizabeth Bennet"

  3. 通常は、/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 イベントフックを作成するには以下のようにします。

  1. Luaスクリプトを作成してラムダイベントフックに読み込み、ホームディレクトリのlambda.luaという名前のファイルに保存します。

    return function (data, event, source, pid)
  local user = data.entity.username
  error("Event hook on consumer " .. user .. "")
end

  2. 次の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'

  3. Kong ManagerまたはKong Admin APIで、任意のワークスペースにコンシューマを追加します。

    1. ワークスペースを選択します。
    2. 左のナビゲーションで コンシューマ を選択します。
    3. 新しいコンシューマ ボタンを選択します。
    4. ユーザー名 を入力します。
    5. （オプション） カスタム ID と 任意のタグ を入力します。
    6. 作成 ボタンを選択します。

    Kong Admin APIのインスタンスに次のHTTPリクエストを送信して、コンシューマLois Lane を作成します。

    curl -i -X POST http://{HOSTNAME}:8001/consumers \
  -d username="Lois Lane"

  4. 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