Documentation

21. 通知

Notifier`は、名前、説明および定義された設定が含まれる、:term:`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 エンドポイントでジョブテンプレートに関連付けられます。

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

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

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

21.2. ワークフロー

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

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

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

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

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

21.4. 通知タイプ

Ansible Tower 3.5.1 でサポートされる通知タイプ:

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

21.4.1. メール

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

メール通知を設定するには以下の情報を指定する必要があります。

  • ホスト
  • 受信者リスト
  • 送信者のメール
  • ポート
  • タイムアウト (秒単位): 最大 120 秒まで指定できます。Tower がタイムアウトするまでメールサーバーへの接続を試行する時間。
_images/notification-template-email.png

21.4.2. Slack

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

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

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

_images/notification-template-slack.png

21.4.3. Twilio

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

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

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

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

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

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

21.4.5. Grafana

Grafana での統合は比較的簡単です。最初に Grafana system (これは Tower に渡すトークンです) の API キーを作成する必要があります。特記すべき他のオプションは以下のとおりです。

  • Grafana URL (必須): Grafana API サービスの URL。通常は http://yourcompany.grafana.com です。
  • Grafana API トークン: ユーザーはまず API キー (Tower に指定されるトークン) を Grafana システムに作成する必要があります。
  • ダッシュボード ID: Grafana アカウントの API キーを作成したら、一意の ID を使用してダッシュボードを設定できます。
  • パネル ID:パネルとグラフを Grafana インターフェースに追加した場合に、この ID を指定できます。
  • アノテーションのタグ: 設定している通知のイベントタイプを識別しやすくするためのキーワードを入力します。
  • SSL 検証の無効化: デフォルトでは SSL 検証はオンになっていますが、Tower がターゲットの証明書の信ぴょう性を検証する機能をオフにすることもできます。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。
_images/notification-template-grafana.png

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

21.4.7. Webhook

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

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

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

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

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

21.4.8. Mattermost

Ansible Tower の Mattermost 通知は、Mattermost のメッセージおよびコラボレーションワークスペースに対する簡単なインターフェースを提供します。指定可能なパラメーターは以下のとおりです。

  • ターゲット URL (必須): POST が実行される完全 URL
  • ユーザー名
  • チャネル
  • アイコン URL: この通知機能向けに表示するアイコンを指定します。
  • SSL 検証の無効化: Tower がターゲットの証明書の信ぴょう性を検証する機能をオフにします。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。
_images/notification-template-mattermost.png

21.4.9. Rocket.Chat

Ansible Tower の Rocket.Chat 通知は、Rocket.Chat のメッセージおよびコラボレーションワークスペースに対するインターフェースを提供します。指定可能なパラメーターは以下のとおりです。

  • ターゲット URL (必須): POST が実行される完全 URL
  • ユーザー名:
  • アイコン URL: この通知機能向けに表示するアイコンを指定します。
  • SSL 検証の無効化: Tower がターゲットの証明書の信ぴょう性を検証する機能をオフにします。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。
_images/notification-template-rocketchat.png

21.4.10. IRC

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

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

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

21.5. towerhost のホスト名の設定

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

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

21.5.1. TOWER_URL_BASE のリセット

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

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

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