23. 通知¶
Notification Template は、名前、説明および定義された設定が含まれる、Notification タイプ (メール、Slack、Webhook など) のことを指します。
例:
メールの通知テンプレートには、ユーザー名、パスワード、サーバー、および受信者が必要です。
Slack 通知テンプレートには、トークンとチャンネルの一覧が必要です。
Webhook 通知テンプレートには、URL とヘッダーが必要です。
通知は、通知テンプレートによる表示です。たとえば、ジョブが失敗すると、通知テンプレートが定義する設定を使用して通知が送信されます。
概要としては、通知システムの通常のフローは以下のようになります。
ユーザーは、
/api/v2/notification_templatesエンドポイントに Tower REST API の通知テンプレートを作成します (API または Tower UI 経由)。ユーザーはサポートする各種オブジェクトのいずれか (すべての種類のジョブテンプレート、組織およびプロジェクト) に対し、通知の必要なトリガーレベル (開始済み、成功、エラーなど) で通知テンプレートを割り当てます。たとえば、ジョブテンプレート 1 の失敗時にトリガーする特定の通知テンプレートを割り当てる場合には、通知テンプレートは
/api/v2/job_templates/n/notification_templates_errorAPI エンドポイントでジョブテンプレートに関連付けられます。Ansible Tower 3.6 以降、ジョブの終了時だけでなく、開始時にも通知を設定できるようになりました。ユーザーおよびチームも、独自の通知を定義して任意のジョブに割り当てることができます。
23.1. 通知の階層¶
特定のレベルで割り当てられた通知テンプレートは、以下のように親オブジェクトで定義されたテンプレートを継承します。
ジョブテンプレートはそれに定義されている通知テンプレートを使用し、ジョブテンプレートで使用されるプロジェクトおよびその下に一覧表示される組織から通知テンプレートを (プロジェクト経由で) 継承します。
プロジェクト更新は、プロジェクトで定義される通知テンプレートを使用し、それに関連付けられる組織から通知テンプレートを継承します。
インベントリー更新は、その下に一覧表示される組織で定義される通知テンプレートを使用します。
アドホックコマンドは、インベントリーが関連付けられる組織に定義された通知テンプレートを使用します。
23.2. ワークフロー¶
ジョブが成功または失敗したら、エラーまたは成功ハンドラーは上記で定義した手順で、関連する通知テンプレートの一覧をプルします。次に、ジョブの関連情報を含めてそれぞれの通知オブジェクトを作成し、このオブジェクトを宛先 (メールアドレス、slack チャンネル、sms 番号など) に送信します。これらの通知オブジェクトはジョブタイプ (ジョブ、インベントリー更新、プロジェクト更新) の関連リソースとして利用でき、/api/v2/notifications からも入手できます。また、この関連リソースを調査して、通知テンプレートから送信される通知を確認することもできます。
通知が失敗する場合、それに関連するジョブに影響を与えたり、これにより失敗することはありません。通知のステータスはその詳細エンドポイント (/api/v2/notifications/<n>) で確認できます。
23.3. 通知テンプレートの作成¶
通知テンプレートを作成するには、以下を実行します。
左側のナビゲーションバーから通知 (
) アイコンをクリックします。
ボタンをクリックします。
通知の名前と説明をそれぞれのフィールドに入力し、通知が属する組織を指定します (必要な場合)。
タイプ ドロップダウンメニューから、通知のタイプを選択します。詳細は、その後のセクションを参照してください。
すべての必須情報を入力したら、保存 をクリックして通知を追加します。
23.4. 通知タイプ¶
Ansible Tower でサポートされる通知タイプ:
それぞれの通知タイプには、独自の設定と、動作に関するセマンティクスがあり、それらに対するテストは異なる方法で実行する必要があります。また、通知の各タイプの具体的な詳細をカスタマイズしたり、通知をトリガーする条件を設定したりできます。カスタム通知の設定については、「カスタム通知の作成」を参照してください。以下のセクションでは、通知の各タイプについて、極力詳細に説明します。
23.4.1. メール¶
メール通知タイプは各種の SMTP サーバーをサポートし、TLS/SSL 接続のサポートがあります。
メール通知を設定するには以下の情報を指定する必要があります。
ホスト
受信者リスト
送信者のメール
ポート
タイムアウト (秒単位): 最大 120 秒まで指定できます。Tower がタイムアウトするまでメールサーバーへの接続を試行する時間。
23.4.2. Grafana¶
Grafana での統合は比較的簡単です。最初に Grafana system (Tower に渡すトークン) の API キーを作成します。
Grafana の通知を設定するには以下の情報を指定する必要があります。
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 を使用する環境では、このオプションで検証を無効にするようにしてください。
23.4.3. HipChat¶
HipChat への統合にはいくつかの方法があります。Tower の実装は HipChat の「Integrations」を使用します。現在、これはメイン 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 でサポートされない色に設定されている場合、通知は指定の色でエラーを生成します。
通知チャンネル (オプション): これを選択すると、ボットからチャンネルのメンバーに「通知」が送られます。通常、これはいずれのユーザーの通知をトリガーせずにチャットチャンネルのメッセージとして送信されます。このオプションにより、既存の通知設定 (ブラウザー通知、電子メールのフォールバックなど) をベースとしてチャンネルのユーザーに通知が送られます。
23.4.4. IRC¶
Tower の IRC 通知は、メッセージをチャンネルまたは個別ユーザーに接続し、配信してから接続を解除する IRC ボットの形式を取ります。Tower の通知ボットは SSL 認証もサポートします。Tower のボットは現在 Nickserv ID をサポートしていません。チャンネルまたはユーザーが存在しないか、オンラインにない場合には通知は失敗しません。失敗シナリオは接続に関する場合に適用されます。
接続に関する情報はシンプルです。
IRC サーバーパスワード (オプション): IRC サーバーではパスワードの接続が要求されます。サーバーがこれを要求しない場合には、空白のままにします。
IRC サーバーポート: IRC サーバーポート
IRC サーバーアドレス: IRC サーバーのホスト名またはアドレス
IRC ニック: サーバー接続後のボットのニックネーム
送信先チャンネルまたはユーザー: 通知の送信先のユーザーおよび/またはチャンネルの一覧。
SSL 接続 (オプション): ボットは接続時に SSL を使用します。
23.4.5. Mattermost¶
Ansible Tower の Mattermost 通知は、Mattermost のメッセージおよびコラボレーションワークスペースに対する簡単なインターフェースを提供します。指定可能なパラメーターは以下のとおりです。
ターゲット URL (必須): POST が実行される完全 URL
ユーザー名
チャネル
アイコン URL: この通知向けに表示するアイコンを指定します。
SSL 検証の無効化: Tower がターゲットの証明書の信ぴょう性を検証する機能をオフにします。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。
23.4.6. PagerDuty¶
PagerDuty は単純な統合です。まず PagerDuty system で API キー (Tower に提供されるトークン) を作成してから、Tower に指定される「統合キー」を提供する「サービス」を作成します。他に必要なオプションは以下のとおりです。
API トークン: ユーザーはまず API キー (Tower に指定されるトークン) を PagerDuty システムに作成する必要があります。
PagerDuty サブドメイン: PagerDuty アカウントのサインアップ時に、通信する固有のサブドメインを受信します。たとえば、「towertest」としてサインアップした場合、web ダッシュボードは
towertest.pagerduty.comになり、サブドメイン (フルドメインではない) として Tower APItowertestを指定します。API サービス/統合キー
クライアント ID: これはアラートコンテンツと共に pagerduty サービスに送信され、api キー/サービスを使用しているサービスの識別に使用されます。これは、複数の統合が同じ API キーおよびサービスを使用している場合に役立ちます。
23.4.7. Rocket.Chat¶
Ansible Tower の Rocket.Chat 通知は、Rocket.Chat のメッセージおよびコラボレーションワークスペースに対するインターフェースを提供します。指定可能なパラメーターは以下のとおりです。
ターゲット URL (必須): POST が実行される完全 URL
ユーザー名
アイコン URL: この通知向けに表示するアイコンを指定します。
SSL 検証の無効化: Tower がターゲットの証明書の信ぴょう性を検証する機能をオフにします。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。
23.4.8. Slack¶
Slack というコラボレーション用のチームのコミュニケーションおよびメッセージングツールは非常に設定しやすいツールです。
以下を指定して Slack 通知を設定する必要があります。
Slack アプリケーション (作成方法は Slack ドキュメントの Basic App Setup ページを参照)
トークン (Enabling Interactions with Bots および Token Types ドキュメントページのボットトークンに関する詳細を参照)
ボット/アプリケーションの設定が完了したら、「Your Apps」に移動し、新たに作成したアプリケーションをクリックし、Add features and functionality に移動します。これにより、着信 Webhook、ボット、およびパーミッションを設定できるようになります。また、アプリケーションをワークスペース にインストールすることもできます。
また、通知ボットが Tower で該当するチャンネル参加できるように招待する必要があります。プライベートメッセージはサポートされていないことに注意してください。
23.4.9. Twilio¶
Twilio サービスは、音声および SMS 自動化サービスです。サインインしたら、メッセージ送信元の電話番号を作成する必要があります。次に、プログラミング可能な SMS で「メッセージングサービス」を定義してから、先ほど作成した番号をこのサービスに関連付けてください。
この番号を使用して任意の番号に送信する前に、その番号や他の情報を確認する必要があります。メッセージングサービスにはステータスコールバック URL も、インバウンドメッセージを処理する機能も不要です。
個別 (またはサブ) アカウントの設定では、API 認証情報を設定します。Twilio は 2 つの認証情報を使用して API 要求の出所を判別します。「アカウント SID」はユーザー名として機能し、「認証トークン」はパスワードとして機能します。
Twilio を設定するには、以下の詳細を指定します。
アカウントトークン
送信元の電話番号 (これは上記のメッセージングサービスに関連付けられた番号であり、「+15556667777」の形式で指定する必要があります)
着信先の SMS 番号 (これは SMS を受信するための番号の一覧であり、10 桁の電話番号である必要があります)
アカウント SID
23.4.10. Webhook¶
Ansible Tower の Webhook 通知タイプは、事前定義された Web サービスに POST を送信するためのシンプルなインターフェースを実現します。Tower は、JSON 形式で関連情報がすべて含まれるデータペイロードと、アプリケーション/JSON のコンテンツタイプを使用して、このアドレスに POST 要求を送信します。Web サービス API によっては、HTTP 要求が特定のフィールド及び特定の形式でないといけない場合があります。以下の方法で、これまでよりも多くの Webhook 通知を設定できます。
HTTP メソッドの設定 (POST または PUT を使用)
送信要求の本文
認証の設定 (基本認証を使用)
Webhook を設定するためのパラメーターは以下のとおりです。
ユーザー名
Basic 認証パスワード
ターゲット URL (必須): Webhook の通知が PUT または POST 要求として送信される完全なURL。
SSL 検証の無効化: デフォルトでは SSL 検証はオンになっていますが、Tower がターゲットの証明書の信ぴょう性を検証する機能をオフにすることもできます。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。
HTTP ヘッダー (必須): キーと値が文字列である JSON 形式のヘッダー。以下は例になります。
{"Authentication": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "MessageType": "Test"}HTTPメソッド (必須): 以下の Webhook のメソッドを選択します。
POST: 新しいリソースを作成します。他のカテゴリーに当てはまらない操作の汎用メソッドとしても機能します。Webhook サービスが PUT を要求していることがわかっていない限り、POST の実行が必要である可能性があります。
PUT: (識別子によって) 特定のリソースまたはリソースのコレクションを更新します。リソースの識別子が事前にわかっている場合、PUT は特定のリソースの作成にも使用できます。
23.5. カスタム通知の作成¶
通知フォームの最下部にある メッセージのカスタマイズ を有効にすると、各 通知タイプ の customize the text content を行うことができます。
各種のジョブイベントに対して以下のカスタムメッセージを提供できます。
開始
成功
エラー
ワークフローの承認
ワークフローの拒否
ワークフローの実行中
ワークフローのタイムアウト
メッセージの形式は、設定している通知の種類によって異なります。たとえば、メールおよび PagerDuty 通知のメッセージは、件名と本文を含む一般的なメール形式で、その場合には、Tower は メッセージ および メッセージボディー というフィールドを表示します。他の通知タイプでは、各イベントのタイプの メッセージ のみになります。
メッセージ フィールドにはトップレベルの変数を含むテンプレートが事前設定されており、job は id または name などの属性と組み合わせられます。テンプレートは中括弧で囲まれ、事前設定された メッセージ フィールドに示されるように、Tower によって指定される固定のフィールドセットから作成されます。
この事前設定されたフィールドでは、イベントの通知を受けた受信者に共通して表示されるメッセージが提案されています。ただし、ジョブに関連した独自の属性を必要に応じて追加することにより、これらのメッセージを異なる条件でカスタマイズできます。カスタムの通知メッセージは、Ansible Playbook で使用されるテンプレート作成エンジンと同じ Jinja を使用してレンダリングされます。
メッセージとメッセージ本文には、以下のような各種タイプのコンテンツがあります。
メッセージは常に文字列のみになります (1 行のみ。改行は使用できません)
メッセージ本文は、以下のような辞書またはテキストブロックのいずれかになります。
Webhook および PagerDuty では、辞書定義が使用されます。これらのデフォルトのメッセージ本文は
{{ job_metadata }}で、そのまま使用することも、独自の辞書を指定することもできます。メールのメッセージ本文では、テキストブロックまたは複数行の文字列が使用されます。デフォルトのメッセージ本文は次のようになります。
{{ job_friendly_name }} #{{ job.id }} had status {{ job.status }}, view details at {{ url }} {{ job_metadata }}このテキストは微調整できます (
{{ job_metadata }}をそのままにするか、{{ job_metadata }}を完全に削除します)。本文はテキストブロックであるため、実際には任意の文字列を使用できます。{{ job_metadata }}は実行中のジョブを説明するフィールドを含む辞書としてレンダリングされます。いずれの場合にも、{{ job_metadata }}には以下のフィールドが含まれます。idnameurlcreated_bystartedfinishedstatustraceback
作成された辞書は次のようになります。
{"id": 18, "name": "Project - Space Procedures", "url": "https://towerhost/#/jobs/project/18", "created_by": "admin", "started": "2019-10-26T00:20:45.139356+00:00", "finished": "2019-10-26T00:20:55.769713+00:00", "status": "successful", "traceback": "" }
{{ job_metadata }}がジョブでレンダリングされる場合は、以下の追加フィールドが含まれます。inventoryprojectplaybookcredentiallimitextra_varshosts
作成された辞書は次のようになります。
{"id": 12, "name": "JobTemplate - Launch Rockets", "url": "https://towerhost/#/jobs/playbook/12", "created_by": "admin", "started": "2019-10-26T00:02:07.943774+00:00", "finished": null, "status": "running", "traceback": "", "inventory": "Inventory - Fleet", "project": "Project - Space Procedures", "playbook": "launch.yml", "credential": "Credential - Mission Control", "limit": "", "extra_vars": "{}", "hosts": {} }
{{ job_metadata }}がワークフロージョブでレンダリングされる場合、以下の追加フィールドが含まれます。body(これにより、ワークフロージョブ内のすべてのノードが列挙され、各ノードに関連付けられたジョブの説明が含まれます)
作成された辞書は次のようになります。
{"id": 14, "name": "Workflow Job Template - Launch Mars Mission", "url": "https://towerhost/#/workflows/14", "created_by": "admin", "started": "2019-10-26T00:11:04.554468+00:00", "finished": "2019-10-26T00:11:24.249899+00:00", "status": "successful", "traceback": "", "body": "Workflow job summary: node #1 spawns job #15, \"Assemble Fleet JT\", which finished with status successful. node #2 spawns job #16, \"Mission Start approval node\", which finished with status successful.\n node #3 spawns job #17, \"Deploy Fleet\", which finished with status successful." }
詳細については、「Using variables with Jinja2」を参照してください。
正しいデータを取得してメッセージを表示するためには、有効な構文が必要です。サポートされている属性と適切な構文構成のリストについては、『Ansible Tower Installation and Reference Guide』の「Supported Attributes for Custom Notifications」を参照してください。
無効な構文や使用できないフィールドの参照を使用する通知テンプレートを作成すると、エラーの内容を示すエラーメッセージが表示されます。通知のカスタムメッセージを削除すると、この場所にはデフォルトのメッセージが表示されます。
23.6. 通知の有効化と無効化¶
特定のジョブ実行の終了時に成功か失敗かを通知することに加えて、そのジョブの開始時に通知する内容を選択できます。以下は留意が必要な動作です。
ワークフローテンプレート (WFJT) でも、ワークフロー内のジョブテンプレート (JT) でも開始時の通知が有効化されている場合には、両方のメッセージが受信される
WFJT 内の多くの JT で通知の実行を有効化できる
スライスされたジョブテンプレート (SJT) で実行される通知を有効化でき、各スライスが通知を生成するようになる
ジョブ開始時の通知の実行が有効化されている場合に、その通知が削除されると、JT は引き続き実行されるが、エラーメッセージが表示される
ジョブの開始、ジョブの成功、ジョブの失敗、またはこれらの任意の組み合わせの通知を、以下のリソースの 通知 タブから有効化できます。
ジョブテンプレート
ワークフローテンプレート
プロジェクト (以下の例を参照)
インベントリーソース
組織
承認ノードがあるワークフローテンプレートの場合は、開始、成功、および エラー に加えて、以下のように特定の承認関連のイベントを有効または無効にできます。
これらのタイプのノードの操作の詳細については、「承認ノード」を参照してください。
23.7. towerhost ホスト名の構成¶
/etc/tower/conf.d/custom.py で、TOWER_URL_BASE='https://tower.example.com' を設定して通知のホスト名を変更します。https://tower.example.com は任意のホスト名に置き換えてください。ansible-tower-service restart で変更を保存した後に、Tower サービスを再起動する必要があります。
Tower のライセンスを更新すると、通知ホスト名も変更されます。
23.7.1. TOWER_URL_BASE のリセット¶
Tower でベース URL (TOWER_URL_BASE) の定義方法を判別する主な方法は、受信要求を確認し、受信要求に基づいてサーバーアドレスを設定する方法です。
まず Tower はデータベースから設定値を取ります。設定の値が見つからない場合、Tower はフォールバックし、設定ファイルの値を使用します。ユーザーが Tower ホストの IP アドレスに移動してライセンスを掲載する場合、掲載されるライセンスはデータベースの設定エントリーに書き込まれます。
誤ったアドレスが選択された場合に TOWER_URL_BASE を変更するには、通知に表示する DNS エントリーを使用して Tower 設定 (
) メニューの ライセンス タブに表示されるライセンスに移動し、ライセンスを再度追加します。
23.8. 通知 API¶
Ansible Tower 3.6 では、*_any が付く以下の通知 API が廃止されました。
/api/v2/organizations/N/notification_templates_any/
/api/v2/job_templates/N/notification_templates_any/
/api/v2/projects/N/notification_templates_any/
/api/v2/inventory_sources/N/notification_templates_any/
/api/v2/system_job_templates/N/notification_templates_any/
v3.7.0 では、代わりに started、success、または error エンドポイントを使用する必要があります。
変更前
/api/v2/organizations/N/notification_templates_any/
変更後
/api/v2/organizations/N/notification_templates_started/
/api/v2/organizations/N/notification_templates_success/
/api/v2/organizations/N/notification_templates_error/
../../../N/notification_templates_started エンドポイントでは、以下に対する GET および POST アクションも使用されます。
組織
プロジェクト
インベントリーソース
ジョブテンプレート
システムジョブテンプレート
ワークフロージョブテンプレート