Sysdigの新しいカスタムWebhookを公開

By 清水 孝郎 - FEBRUARY 2, 2023
Topics: Sysdig機能

SHARE:

本文の内容は、2023年2月3日にMIGUEL PAISが投稿したブログ（https://sysdig.com/blog/sysdig-monitor-custom-webhook)を元に日本語に翻訳・再構成した内容となっております。

はじめに

Sysdig Monitor は、以前から様々な通知チャネルと統合されており、ユーザーは多数のサードパーティサービスにアラートを転送することができます。現在、ユーザーは Sysdig Monitor の監視イベントを PagerDuty、Slack、電子メール、Microsoft Teams などの外部サービスに転送することを選択することができます。

Sysdigでは、サードパーティーのサービスとの統合はシームレスな体験であるべきだと考えています。しかし、統合する通知チャネルの数が増えているため、どんなサードパーティサービスプロバイダーにも適した、柔軟で汎用的な統合を開発する必要がありました。

この目的のために、Webhooksは常にサービスとアプリケーションの間のユビキタスな統合メカニズムとなっています。リモートサーバー上の HTTP API にすぎない Webhook は、クライアントがサードパーティが提供するサービスにアクセスすることを可能にします。

Sysdig Monitor は、製品が存在する限り、ほとんど Webhook 通知チャネルを含んでいます。しかし、いくつかの制限に悩まされていました。

このような背景から、私たちはより強力で柔軟な Webhook 通知チャネルをリリースしました。本日は、カスタムWebhook通知チャネルを紹介します。

問題点

Webhook が統合のためのユビキタスな方法であり、Sysdig Monitor が常に Webhook 通知チャネルを含んでいるならば、なぜ新しいバージョンをリリースする必要があると判断したのでしょうか？

Webhook を呼び出すことは、外部 API に対して単純な  HTTP リクエストを実行することであることを覚えておいてください。 HTTP リクエストとして、それは指定された外部アドレスを必要とし、ペイロードは明確に定義された数のヘッダーと整形されたボディを含んで送信されます。ボディはプレーンテキストですが、 JSON、 YAML などのフォーマットも可能です。

Custom webhook new channel
Sysdig Monitor 内の現在の Webhook 統合

Sysdig Monitor 内で、以前の Webhook 通知チャネルは、いくつかの関連する機能を提供していましたが、いくつかの点で制限もありました。それは、ユーザーがリクエストのすべてのヘッダを指定することを許可していました。また、 HTTPSでTLSの検証をスキップすることができました。最後に、お客様によって定義されるいくつかのカスタムペイロードデータを 許可しました。これらすべてのピースが設定されると、ユーザーは最終的なリクエストが、提供された外部アドレス、指定されたヘッダー、および定義されたペイロードの組み合わせで構成されることを期待できるようになります。しかし、どの HTTP メソッドが使用されるかは不明なままでした。

ペイロードの例

アラート通知によって配信されたペイロードをさらに調べると、レスポンスに驚くほど多くの前提条件があることがわかりました：

Custom webhook payload details
現在のWebhook統合を使用して標準的なテスト通知を受信した結果

  1. まず、リクエストは自動的に HTTP POSTとして送信されるものと仮定しています。これはほとんどの統合に当てはまりますが、一般的な  REST APIはリソースを完全にまたは部分的に変更する場合は  PUT  または  PATCH を使用し、リソースを削除する場合は  DELETE を使用するので、決して保証されるものではありません。
  2. 次に、実際にユーザー定義のヘッダが送信されますが、3つのヘッダが自動的に設定されました： Content-type はapplication/json、 Acceptも application/json 、 User-agent は Mozilla/5.0に設定されています。
  3. 第３に、アラート通知のHTTPボディコンテンツはSysdigによって定義され、ユーザーが調整する余地はほとんどありません。さらに、前述したカスタム データ フィールドによってお客様に提供されるカスタマイズ機能は、より大きな JSON オブジェクト構造の末尾にのみ存在します（画像2）。

この方法は、これまでお客様のニーズに応えてきましたが、サードパーティによる統合は、前述の3つの要素に非常に厳しい場合があるため、カスタム統合の可能性を真に開くものではありません： HTTP Method、 Headers,と Body。

そのため、統合が要求する形式に厳密に合致しないリクエストは、 HTTP ステータス400 Bad Requestというレスポンスで拒否されることが多いのです。これは Slack や Google Chat、その他多くの統合に当てはまります。明らかに、現在の Webhook は私たちの要件に完全に対応していませんでした。

ニーズ

そのため、Sysdig Monitor では、ユーザーがペイロードの内容を正確に指定でき、どのサードパーティ  API にも対応できる柔軟性を持った、真にカスタマイズ可能な Webhook が必要となっていました。その結果、ユーザーが望むあらゆるものと統合できる可能性を秘めた、1つの通知チャネルができあがります。

当初、これはそれほど難しいことではないと考えられていました。例えば、お客様が Webhook の HTTP メソッドをカスタマイズできるようにし、送信されるボディがお客様の定義と正確に一致するようにすることは、数日で導入できる変更でした。

しかし、そのようなユーザ定義のペイロードでは、お客様のニーズに応えられないことがわかりました。お客様は自動化されたワークフローの一部としてSysdig Webhooksを使用しており、これらのWebhooksはアラートがトリガーされた動的なコンテキスト（重要度、ラベル、ホストのメタデータなど）に依存しています。

サードパーティのAPIに送信する静的なボディをお客様がカスタマイズできるだけでは、KubernetesのPodがダウンしたかどうか、Postgresのインスタンスが接続制限に達したかどうか、あるいはもっと心配な状況をこれらのサービスが理解することはできません。

どうすれば、お客様がリクエストの詳細を静的にカスタマイズでき、かつ、実行時の状況に応じたアラートやイベント情報を動的に含めることができるようになるのでしょうか。

解決策 ：Sysdig カスタムWebhookとSysdig テンプレート言語

このソリューションでは、カスタムWebhook通知チャネルを作成し、ペイロード構造を正確に定義するだけでなく、Sysdig Templating Languageという中間言語を通じて、お客様がアラートのコンテキストに特有の実行時情報を挿入できるようにしました。

Sysdig Templating Languageでは、特定のアラートやイベントの実行時変数にアクセスしながら、出力する内容を正確に定義することができます。このように：

The alert that fired was {{@alert_name}}

例えば、上記はSysdig Templating Languageの有効な文です。この文は、アラートトリガーのコンテキストにおいてのみ意味を持ちます。このような条件下で、このセンテンスを評価すると、”The alert that fired was High CPU Reached. “という出力が得られます。

Custom alerting with template language
Sysdig Templating Languageによるサンプル文の評価

Sysdig Templating Languageを利用して送信するペイロードをユーザーが定義することで、サードパーティシステムが受信したリクエストを理解するために必要な動的な実行時コンテキスト情報を受け取りながら、必要な情報のみを送信する自由を与えることができます。

コンテキストにアクセスする

Sysdig Templating Languageをサポートしたカスタム Webhookは、多くの変数をアウトオブボックスでサポートした状態で提供されています。

これらの変数はすべて、アラートとイベントという2つのカテゴリのいずれかに属しています。

  • アラート変数は、イベントをトリガーするアラートの構成にアクセスすることを可能にします。アラート変数には、アラート名、説明、スコープ、グループ化、条件などが含まれます。
  • イベント変数は、トリガーとなるイベント自体に関連します。これには、例えば、イベントの状態、トリガーとなるタイムスタンプ、インフラストラクチャー・ラベルなどが含まれます。

カスタムWebhookの完全なリファレンスを参照して、私たちが提供しているすべての機能の詳細については、お気軽にご覧ください。

より深く掘り下げる： 条件付きロジック

しかし、私たちはテンプレート変数にとどまらず、ユーザーからのいくつかのユースケースは、より複雑なロジックを必要とすることに気づきました。通知チャネルは、確かに多くの異なるアラートタイプによってトリガーされます。

もし、ユーザーがアラートの重大度（高、中、低など）、アラートのタイプ（メトリクス、Prometheus、ダウンタイムなど）、または現在のイベントが最初のアラート通知ではなくアラート解決に関連しているかどうかに基づいて、異なるペイロードを送信したいとしたらどうでしょうか。このような理由から、私たちは条件付きロジックのビルトインサポートを追加しました。

条件付きロジックは、ユーザーが問題のアラートの固有のプロパティに基づいて異なるペイロードを送信することを望むかもしれない状況において重要です。単純な使用例としては、設定されたアラートの深刻度に基づいて区別できる仕組みを提供することができます。

条件付きロジックの例

条件付きロジックを使用すると、重要度の高いアラートと重要度の低いアラートを比較して、異なるペイロードを送信することが可能です。このため、Sysdig Templating Languageでは、実行されるアクションを表現するステートメントを導入しています。

しかし、変数とは異なり、それらは文書本体を含むので、最初のタグは対応する終了タグを必要とします。そのため、センテンス文は以下のようになります：

{{#if_metric_alert}}
some text
{{/if}}

メトリクスアラートをトリガーするコンテキストで評価された場合、出力としてレンダリングされます：

“some text”

しかし、Prometheusのアラートをトリガーするコンテキストでは、何も出力されないレンダリングとなります。

Conditional logic in custom webhooks
Sysdig Templating Languageを使った条件付きロジックの評価結果

この機能の最初のリリースでは、すべてのアラートタイプ、すべてのアラート重大度、およびトリガーするアラートと解決するアラートを区別する機能で条件文を提供しています。

else-if付き条件付きロジックの例

さらに、条件文はelse-ifロジックで次のように拡張することができます：

{{#if_metric_alert}}
do this
{{#else if_downtime_alert}}
do that
{{#else}}
nothing matched
{{/if}}

このように、条件文は主条件、それに続く0個以上の代替ブランチ、それに続くオプションのデフォルトブランチで構成することができます。

新しいカスタムWebhookのエディターウィンドウで入力を始めるとすぐに、書かれている文書の文法的な健全性に関する即時のフィードバックと、各変数とステートメントの意味に関するインラインドキュメント付きのオートコンプリート機能を利用することができます。

Custom webhook autocomplete and feedback
構文検証、オートコンプリート、入力中のドキュメントを特徴とする新しいカスタムウェブフックエディター

まとめ

新しいカスタム Webhook 通知チャネルは、以前の Webhook の実装では閉ざされていたかもしれない統合の可能性の扉を開きます。それは、以下のギャップを埋めることによって実現されます。

  • 外部アドレス
  • HTTP  メソッド
  • HTTP  ヘッダー
  • コンテキストを参照する機能を持つHTTP ボディのペイロード
  • オプションの証明書検証

ヘッダー、ペイロード、アラートコンテキストを完全にコントロールしながら、あらゆるHTTP リクエストをサードパーティサービスに対して行うことが可能です。

Custom webhook recap
Sysdig Monitor内の新しいカスタムWebhook通知チャネルの現在の様子です

近い将来、異なるペイロード形式を簡単に定義できるようになり、この機能がさらに改善されることが期待できます。

全体として、この新しい通知チャネルは、お客様のワークフローに真の革命をもたらすことができると信じています。

ユースケース： 新しいカスタムWebhookを使用したアラートイベントのSMS送信

アラートと統合するための一般的なユースケースは、 SMSを送信することです。世界中で携帯電話接続が可能なため、SMSはスマートフォンやデータプランが不要で、便利なソリューションです。

カスタムWebhookが登場するまでは、Sysdig Monitor内でサードパーティのSMSサービスと統合する方法はありませんでした。

この使用例では、サードパーティのPlinoを使用します。トライアルアカウントは、基本的な SMS 配信機能を提供しますが、 JSON ベースの  REST API にアクセスすることができます。

ステップ1 – アカウントを作成し、APIキーを取得する

Plivo.comでトライアルアカウントを作成します。

登録後、メインダッシュボードで、認証IDと認証トークンを確認できます。これは後で使用するために保存してください。

Plivo sign up
Plivo.comのアカウント詳細には、メインダッシュボードからアクセスできます。

注：メッセージングセクションにアクセスし、次にSettings > Geo Permissions にアクセスし、SMS送信を有効にしたい国を有効にしていることを確認します。

ステップ2 – Sysdigに新しいカスタムWebhookチャンネルを作成します

Sysdig Monitorにアクセスします。左下にあるプロフィール名にカーソルを合わせ、右上の Settings をクリックします。

Custom webhook step 2
Sysdig Monitorの設定にアクセスします。

開いたウィンドウで、Notification Channels にアクセスします。

Custom webhook notification channels
通知チャネルセクションにアクセスする

新しく開いたページで、右上のプラス記号をクリックして新しい通知チャネルを追加し、”Custom Webhook”を選択します。

Custom webhook notification channels 2
作成する新しい通知チャネルを選択する

ステップ 3 – 通知チャネルの詳細を入力する

  • 1. “SMS delivery“などのチャンネルの名前を入力します。
  • 2. 以下のPlivo アドレスを挿入します：

https://api.plivo.com/v1/Account/{accountId}/Message/

accountIdには、手順1で取得した値を代入してください。

  • 3. ”MethodとHeaders” ボックスでは、デフォルトのHTTP メソッドを POSTのままにしておくとよいでしょう。
  • 4. 同じボックスで新しいカスタムヘッダーを追加し、ヘッダー名として ”Authorization” を挿入する必要があります。その値は、”Basic <base64Token>”という文字列である必要があります。Base64トークンは、手順1で取得した2つの値である”<accountId>:<accountToken>”という文字列をbase64エンコードしたものでなければなりません。オンラインツールを使って、base64エンコードを取得することができます。
  • 5. エディターウィンドウで、次のペイロードを入力します：

{
    "src": "Sysdig",
    "dst": "+<phone_number_with_country_code>",
    "text": "{{@event_title}}",
    "type": "sms",
    "url": "https://foo.com/sms status",
    "method": "POST",
    "log": "true",
    "trackable": false
}

このように、PlinoのAPIで要求されるフォーマットでコンタクトを取ろうとしています。その中で、連絡先の電話番号を定義し、SMSのテキストはトリガーされたアラートのイベントタイトルと全く同じにしています。これは、どのような状況が発生しているのか、ユーザーに十分なコンテキストを与えるべき小さな文です。

  • 6. これで、Configure Test Notification ボックスを使用して、このチャネルでトリガーされたアラートをシミュレートすることができます。適切なアラートの重要度とアラートタイプを選択し、”Send Test Notification”（テスト通知を送信）をクリックします。
  • 7.  SMS を受信したはずです。save をクリックします。

Sysdig Monitor で新しいアラートを設定し、新しい “SMS delivery” チャネルに接続するとすぐに、指定した電話番号に、インフラストラクチャーで発生する可能性のあるすべてのインシデントについてアラートが表示されます。

Sysdigの機能を大幅に向上させ、導入された新しい通知チャネルの威力を示す、十分に興味深いユースケースを提供できたのではないかと思っています。