Documentation

17. 通知

Notifier (通知機能) は、名前、説明および定義された設定を持つ Notification (通知) タイプ (メール、Slack、Webhook など) のことを指します。

例:

  • ユーザー名、パスワード、サーバー、および受信者はメールの通知機能に必要です。
  • トークンとチャンネルの一覧が Slack 通知機能に必要です。
  • URL およびヘッダーが Webhook 通知機能に必要です。

通知は、Notifier (通知機能) による表示です。たとえば、ジョブが失敗すると、通知が Notifier (通知機能) が定義する設定を使用して送信されます。

大まかにみると、通知システムの通常のフローは以下のようになります。

  • ユーザーは、/api/v2/notifiers エンドポイントに Tower REST API の通知機能を作成します (API または Tower UI 経由)。
  • ユーザーはサポートする各種オブジェクトのいずれか (すべての種類のジョブテンプレート、組織およびプロジェクト) に対し、通知 (エラー、成功など) の必要なトリガーレベルで通知機能を割り当てます。たとえば、ユーザーは特定の通知機能を割り当て、ジョブテンプレート 1 の失敗時にトリガーする特定の通知機能を割り当てる必要があるかもしれません。その場合、通知機能は /api/v2/job_templates/n/notifiers_error API エンドポイントでジョブテンプレートに関連付けられます。

17.1. Notifier (通知機能) の階層

特定のレベルで割り当てられる通知機能は、以下のような親オブジェクトで定義される通知機能を継承します。

  • ジョブテンプレートはそれに定義されている通知機能を使用し、ジョブテンプレートで使用されるプロジェクトおよびその下に一覧表示される組織から通知機能を (プロジェクト経由で) 継承します。
  • プロジェクト更新は、プロジェクトで定義される通知機能を使用し、それに関連付けられる組織から通知機能を継承します。
  • インベントリー更新は、その下に一覧表示される組織で定義される通知機能を使用します。
  • アドホックコマンドは、インベントリーが関連付けられる組織に定義された通知機能を使用します。

17.2. ワークフロー

ジョブが成功または失敗する場合、エラーまたは成功ハンドラーは上記で定義される手順で関連する通知機能の一覧をプルします。次に、ジョブについての関連する詳細を含むそれぞれの通知オブジェクトを作成し、これを宛先 (メールアドレス、slack チャンネル、sms 番号など) に送信します。これらの通知オブジェクトはジョブタイプ (ジョブ、インベントリー更新、プロジェクト更新) の関連リソースとして利用でき、/api/v2/notifications から利用できます。また、関連リソースを調査し、通知機能から送信される通知を確認することもできます。

通知が失敗する場合、それに関連するジョブに影響を与えたり、これにより失敗することはありません。通知のステータスはその詳細エンドポイント (/api/v2/notifications/<n>) で確認できます。

17.3. 通知テンプレートの作成

通知テンプレートを作成するには、以下を実行します。

  1. settings ボタンをクリックし、通知 を選択します。
_images/notifications-template-empty.png
  1. add ボタンをクリックします。
_images/notifications-template-add-new.png
  1. それぞれのフィールドに、通知、説明、およびそれが属する組織の名前を入力します。
  2. タイプ ドロップダウンメニューから、通知のタイプを選択します。詳細は、その後のセクションを参照してください。
  3. すべての必須情報を入力したら、保存 をクリックして通知を追加します。

17.4. 通知タイプ

それぞれには独自の設定および動作のセマンティクスがあり、それらのテストは異なる方法で実行する必要がある場合があります。以下のセクションでは詳細を説明します。

17.4.1. メール

メール通知タイプは各種の SMTP サーバーをサポートし、TLS/SSL 接続のサポートがあります。

ユーザー名 - ホスト - 送信者のメール - Recepient list (受信者一覧) - パスワード - ポートなどの詳細を指定してメール通知を設定する必要があります。

_images/notification-template-email.png

ご用心

TLS および SSL 接続は相互に排他的であり、同時に選択することはできません。1 つのみを選択するようにしてください。両方を選択すると警告なしに失敗します。

17.4.2. Slack

Slack というコラボレーション用のチームのコミュニケーションおよびメッセージングツールは非常に設定しやすいツールです。

以下を指定して Slack 通知を設定する必要があります。

通知ボットが該当するチャンネルに参加できるように詳細する必要もあります。プライベートメッセージはサポートされないことに注意してください。

_images/notification-template-slack.png

17.4.3. Twilio

Twilio サービスは、音声および SMS 自動化サービスです。いったんサインインしたら、メッセージが送信される電話番号を作成する必要があります。プログラミング可能な SMS で「メッセージングサービス」を定義してから、作成した番号をそれに関連付けることができます。

この番号を使用して任意の番号に送信する前に、その番号や他の情報を確認する必要があります。メッセージングサービスにはステータスコールバック URL も、インバウンドメッセージを処理する機能も不要です。

個別 (またはサブ) アカウントの設定では、API 認証情報を設定します。Twilio は 2 つの認証情報を使用して API 要求の出所を判別します。「アカウント SID」はユーザー名として機能し、「認証トークン」はパスワードとして機能します。

Twilio を設定するには、以下の詳細を指定します。

  • アカウントトークン
  • 送信元の電話番号 (これは上記のメッセージングサービスに関連付けられた番号であり、「+15556667777」の形式で指定する必要があります)
  • 着信先の電話番号 (これは SMS を受信するための番号の一覧であり、10 桁の電話番号である必要があります)
  • アカウント SID
_images/notification-template-twilio.png

17.4.4. PagerDuty

PagerDutyは単純な統合です。ユーザーはまず pagerduty システムで API キー (Tower に提供されるトークン) を作成してから、Tower に指定される「統合キー」として提供する「サービス」を作成します。注意するべき他のオプションは以下のとおりです。

  • API トークン: ユーザーはまず API キー (Tower に指定されるトークン) を PagerDuty システムに作成する必要があります。
  • PagerDuty サブドメイン: PagerDuty アカウントのサインアップ時に、通信する固有のサブドメインを受信します。たとえば、「towertest」としてサインアップした場合、web ダッシュボードは towertest.pagerduty.com になり、サブドメイン (フルドメインではない) として Tower API towertest を指定します。
  • API サービス/統合キー
  • クライアント ID: これはアラートコンテンツと共に pagerduty サービスに送信され、api キー/サービスを使用しているサービスの識別に使用されます。これは、複数の統合が同じ API キーおよびサービスを使用している場合に役立ちます。
_images/notification-template-pagerduty.png

17.4.5. HipChat

HipChat に統合する方法はいくつかの方法があります。Tower の実装は HipChat の「統合」を使用します。現在、これはメイン HipChat web ビューの右下にあります。そこから「Build your own Integration」を選択します。その作成後に、Tower に指定する必要のある auth_token を一覧表示します。HipChat 通知タイプに Tower が許可するフィールドにする他の詳細には以下が含まれます。

  • 送信先チャンネル: 通知を受信する必要のあるチャンネル (「engineering」または「#support」など)。
  • トークン: 独自の HipChat 統合のビルド後に一覧表示されるトークン。
  • 通知と共に表示されるラベル: 統合名自体と共に、これは通知に別のラベルを配置します (複数のサービスが同じ統合を使用して相互を区別する場合に役立つ可能性があります)。
  • API URL: Hipchat API サービスの URL。それらでホストされるチームを作成する場合、https://team.hipchat.com のような形式になります。セルフホスト型の統合の場合は、https://hipchat.yourcompany.com/ に類するベース URL を使用し、それらの先頭に # を付けずに該当する送信先チャンネルに追加します (“#engineering” ではなく “engineering”)。
  • 通知の色: メッセージが指定の色で強調表示されます。HipChat でサポートされない色に設定されている場合、通知は指定の色でエラーを生成します。
  • 通知チャンネル: これを選択すると、ボットからチャンネルのメンバーに「通知」が送られます。通常、これはいずれのユーザーの通知をトリガーせずにチャットチャンネルのメッセージとして送信されます。このオプションにより、既存の通知設定 (ブラウザー通知、電子メールのフォールバックなど) をベースとしてチャンネルのユーザーに通知が送られます。
_images/notification-template-hipchat.png

17.4.6. Webhook

Ansible Tower の webhook 通知タイプは、POST を事前定義された web サービスに送信するための単純なインターフェースを提供します。Tower はアプリケーション/json コンテンツタイプを使用し、json 形式のすべての関連する詳細を含むデータペイロードでこのアドレスに POST を実行します。

パラメーターは非常に簡単です。

  • ターゲット URL: POST が実行される完全 URL。

  • HTTP ヘッダー: キーと値が文字列が含まれる JSON 形式のヘッダー。以下は例になります。

    {"Authentication": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "MessageType": "Test"}
    
_images/notification-template-webhook.png

17.4.7. IRC

Tower の IRC 通知は、メッセージをチャンネルまたは個別ユーザーに接続し、配信してから接続を解除する IRC ボットの形式を取ります。Tower の通知ボットは SSL 認証もサポートします。Tower のボットは現在 Nickserv ID をサポートしていません。チャンネルまたはユーザーが存在しないか、オンラインにない場合には通知は失敗しません。失敗シナリオは接続に関する場合に適用されます。

接続に関する情報は、以下のような分かりやすい情報になります。

  • IRC サーバーパスワード: IRC サーバーではパスワードの接続が要求されます。サーバーがこれを要求しない場合には、空白のままにします。
  • IRC サーバーポート: IRC サーバーポート
  • IRC サーバーアドレス: IRC サーバーのホスト名またはアドレス
  • IRC ニック: サーバー接続後のボットのニックネーム
  • 送信先チャンネルまたはユーザー: 通知の送信先のユーザーおよび/またはチャンネルの一覧。
  • SSL 接続: ボットは接続時に SSL を使用します。
_images/notification-template-irc.png

17.5. towerhost ホスト名の設定

/etc/tower/settings.py で、TOWER_URL_BASE='https://tower.example.com' を編集して、通知のホスト名を変更します。https://tower.example.com は任意のホスト名に置き換えてください。変更を保存してから ansible-tower-service restart で Tower サービスを再起動する必要があります。

Tower ライセンスを更新すると、通知のホスト名も更新されます。Ansible Tower 3.0 の新規インストールでは、通知用にホストを設定する必要はありません。

17.5.1. TOWER_URL_BASE の再設定

Tower でベース URL (TOWER_URL_BASE) の定義方法を判別する主な方法は、受信要求を確認し、受信要求に基づいてサーバーアドレスを設定する方法です。

まず Tower はデータベースから設定値を取ります。設定の値が見つからない場合、Tower はフォールバックし、設定ファイルの値を使用します。ユーザーが Tower ホストの IP アドレスに移動してライセンスを掲載する場合、掲載されるライセンスはデータベースの設定エントリーに書き込まれます。

正しくないアドレスが選択された場合に TOWER_URL_BASE を変更するには、通知に表示する DNS エントリーを使用して Tower 設定 (settings) メニューの「ライセンスの表示」リンクにあるライセンスに移動し、ライセンスを再度追加します。