26. 通知¶

26.1. 通知の階層¶

特定のレベルで割り当てられた通知テンプレートは、以下のように親オブジェクトで定義されたテンプレートを継承します。

• ジョブテンプレートはそれに定義されている通知テンプレートを使用し、ジョブテンプレートで使用されるプロジェクトおよびその下に一覧表示される組織から通知テンプレートを (プロジェクト経由で) 継承します。

• プロジェクト更新は、プロジェクトで定義される通知テンプレートを使用し、それに関連付けられる組織から通知テンプレートを継承します。

• インベントリー更新は、その下に一覧表示される組織で定義される通知テンプレートを使用します。

• アドホックコマンドは、インベントリーが関連付けられる組織に定義された通知テンプレートを使用します。

26.2. ワークフロー¶

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

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

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

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

1. 左のナビゲーションバーから 通知 をクリックします。

2. Click the Add button.

3. 通知の名前と説明をそれぞれのフィールドに入力し、通知が属する組織を指定します (必要な場合)。

4. タイプ ドロップダウンメニューから、通知のタイプを選択します。詳細は、その後のセクションを参照してください。

5. すべての必須情報を入力したら、保存 をクリックして通知を追加します。

26.4. 通知タイプ¶

automation controller でサポートされる通知タイプ:

それぞれの通知タイプには、独自の設定と、動作に関するセマンティクスがあり、それらに対するテストは異なる方法で実行する必要があります。また、通知の各タイプの具体的な詳細をカスタマイズしたり、通知をトリガーする条件を設定したりできます。カスタム通知の設定については、「カスタム通知の作成」を参照してください。以下のセクションでは、通知の各タイプについて、極力詳細に説明します。

26.4.1. メール¶

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

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

• ホスト

• 受信者リスト

• 送信者のメール

• ポート

• タイムアウト (秒単位): automation controller がタイムアウトになるまでメールサーバーへの接続を試行する時間。最大 120 秒まで指定できます。

26.4.2. Grafana¶

Grafana での統合は比較的簡単です。最初に Grafana system (automation controller に渡すトークン) の API キーを作成します。

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

• Grafana URL: Grafana API サービスの URL。通常は http://yourcompany.grafana.com です。

• Grafana API キー: ユーザーはまず API キー (automation controller に渡すトークン) を Grafana システムで作成する必要があります。

注意すべきその他のオプションは以下のとおりです。

• ダッシュボード ID: Grafana アカウントの API キーを作成したら、一意の ID を使用してダッシュボードを設定できます。

• パネル ID：パネルとグラフを Grafana インターフェースに追加した場合に、この ID を指定できます。

• アノテーションのタグ: 設定している通知のイベントタイプを識別しやすくするためのキーワードを入力します。

• SSL 検証の無効化: デフォルトでは SSL 検証は有効になっていますが、ターゲットの証明書の信ぴょう性を検証する機能を無効にすることもできます。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。

26.4.4. IRC¶

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

接続に関する情報はシンプルです。

• IRC サーバーパスワード (オプション): IRC サーバーではパスワードの接続が要求されます。サーバーがこれを要求しない場合には、空白のままにします。

• IRC サーバーポート: IRC サーバーポート

• IRC サーバーアドレス: IRC サーバーのホスト名またはアドレス

• IRC ニック: サーバー接続後のボットのニックネーム

• 送信先チャンネルまたはユーザー: 通知の送信先のユーザーおよび/またはチャンネルの一覧。

• SSL 接続 (オプション): ボットは接続時に SSL を使用します。

26.4.5. Mattermost¶

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

• ターゲット URL (必須): POST が実行される完全 URL

• ユーザー名

• チャネル

• アイコン URL: この通知向けに表示するアイコンを指定します。

• SSL 検証の無効化: ターゲットの証明書の信ぴょう性を検証する機能を無効にします。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。

26.4.6. PagerDuty¶

PagerDuty は単純な統合です。まず PagerDuty system で API キー (automation controller に提供されるトークン) を作成してから、automation controller に指定される「統合キー」を提供する「サービス」を作成します。他に必要なオプションは以下のとおりです。

• API トークン: ユーザーはまず API キー (automation controller に指定されるトークン) を PagerDuty システムに作成する必要があります。

• PagerDuty サブドメイン: PagerDuty アカウントのサインアップ時に、通信する固有のサブドメインを受け取ります。たとえば、「testuser」としてサインアップした場合、Web ダッシュボードは testuser.pagerduty.com になり、サブドメイン (フルドメインではない) として API testuser を指定します。

• API サービス/統合キー

• クライアント ID: これはアラートコンテンツと共に pagerduty サービスに送信され、api キー/サービスを使用しているサービスの識別に使用されます。これは、複数の統合が同じ API キーおよびサービスを使用している場合に役立ちます。

26.4.7. Rocket.Chat¶

Rocket.Chat の通知は、Rocket.Chat のコラボレーションおよびコミュニケーションプラットフォームへのインターフェースを提供します。指定できるパラメーターは次のとおりです。

• ターゲット URL (必須): POST が実行される完全 URL

• ユーザー名

• アイコン URL: この通知向けに表示するアイコンを指定します。

• SSL 検証の無効化: ターゲットの証明書の信ぴょう性を検証する機能を無効にします。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。

26.4.8. Slack¶

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

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

• Slack アプリケーション (作成方法は Slack ドキュメントの Basic App Setup ページを参照)

• トークン (Enabling Interactions with Bots および Token Types ドキュメントページのボットトークンに関する詳細を参照)

ボット/アプリケーションの設定が完了したら、「Your Apps」に移動し、新たに作成したアプリケーションをクリックし、Add features and functionality に移動します。これにより、着信 Webhook、ボット、およびパーミッションを設定できるようになります。また、アプリケーションをワークスペース にインストールすることもできます。

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

26.4.9. Twilio¶

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

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

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

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

• アカウントトークン

• 送信元の電話番号 (これは上記のメッセージングサービスに関連付けられた番号であり、「+15556667777」の形式で指定する必要があります)

• 着信先の SMS 番号 (これは SMS を受信するための番号の一覧であり、10 桁の電話番号である必要があります)

• アカウント SID

26.4.10. Webhook¶

Webhook 通知タイプは、事前定義された Web サービスに POST を送信するためのシンプルなインターフェースを実現します。automation controller は、JSON 形式で関連情報がすべて含まれるデータペイロードと、アプリケーション/JSON のコンテンツタイプを使用して、このアドレスに POST 要求を送信します。Web サービス API によっては、HTTP 要求が特定のフィールドおよび特定の形式でないといけない場合があります。以下の方法で、これまでよりも多くの Webhook 通知を設定できます。

• HTTP メソッドの設定 (POST または PUT を使用)

• 送信要求の本文

• 認証の設定 (基本認証を使用)

Webhook を設定するためのパラメーターは以下のとおりです。

• ユーザー名

• Basic 認証パスワード

• ターゲット URL (必須): Webhook の通知が PUT または POST 要求として送信される完全なURL。

• SSL 検証の無効化: デフォルトでは SSL 検証はオンになっていますが、ターゲットの証明書の信ぴょう性を検証する機能を無効にすることもできます。内部またはプライベートの CA を使用する環境では、このオプションで検証を無効にするようにしてください。

• HTTP ヘッダー (必須): キーと値が文字列である JSON 形式のヘッダー。以下は例になります。{"Authentication": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "MessageType": "Test"}

• HTTPメソッド (必須): 以下の Webhook のメソッドを選択します。

  • POST: 新しいリソースを作成します。他のカテゴリーに当てはまらない操作の汎用メソッドとしても機能します。Webhook サービスが PUT を要求していることがわかっていない限り、POST の実行が必要である可能性があります。

  • PUT: (識別子によって) 特定のリソースまたはリソースのコレクションを更新します。リソースの識別子が事前にわかっている場合、PUT は特定のリソースの作成にも使用できます。

26.4.10.1. Webhook ペイロード¶

Automation controller は、デフォルトで Webhook エンドポイントで次のデータを送信します。

job id
name
url
created_by
started
finished
status
traceback
inventory
project
playbook
credential
limit
extra_vars
hosts
http method

automation controller から返される Webhook メッセージによる started 通知の例:

{"id": 38, "name": "Demo Job Template", "url": "https://host/#/jobs/playbook/38", "created_by": "bianca", "started":
"2020-07-28T19:57:07.888193+00:00", "finished": null, "status": "running", "traceback": "", "inventory": "Demo Inventory",
"project": "Demo Project", "playbook": "hello_world.yml", "credential": "Demo Credential", "limit": "", "extra_vars": "{}",
"hosts": {}}POST / HTTP/1.1

Automation controller は、デフォルトで success/fail 状態の Webhook エンドポイントで次のデータを返します。

job id
name
url
created_by
started
finished
status
traceback
inventory
project
playbook
credential
limit
extra_vars
hosts

automation controller から返される Webhook メッセージによる success/fail 通知の例:

{"id": 46, "name": "AWX-Collection-tests-awx_job_wait-long_running-XVFBGRSAvUUIrYKn", "url": "https://host/#/jobs/playbook/46",
"created_by": "bianca", "started": "2020-07-28T20:43:36.966686+00:00", "finished": "2020-07-28T20:43:44.936072+00:00", "status": "failed",
"traceback": "", "inventory": "Demo Inventory", "project": "AWX-Collection-tests-awx_job_wait-long_running-JJSlglnwtsRJyQmw", "playbook":
"fail.yml", "credential": null, "limit": "", "extra_vars": "{\"sleep_interval\": 300}", "hosts": {"localhost": {"failed": true, "changed": 0,
"dark": 0, "failures": 1, "ok": 1, "processed": 1, "skipped": 0, "rescued": 0, "ignored": 0}}}

26.5. カスタム通知の作成¶

You can customize the text content of each of the 通知タイプ by enabling the Customize Messages portion at the bottom of the notifications form.

各種のジョブイベントに対して以下のカスタムメッセージを提供できます。

• 開始

• 成功

• エラー

• ワークフローの承認

• ワークフローの拒否

• ワークフローの実行中

• ワークフローのタイムアウト

メッセージの形式は、設定している通知の種類によって異なります。たとえば、メールおよび PagerDuty 通知のメッセージは、件名と本文を含む一般的なメール形式で、その場合、automation controller は メッセージ および メッセージボディー というフィールドを表示します。他の通知タイプでは、各イベントのタイプの メッセージ のみになります。

メッセージ フィールドにはトップレベルの変数を含むテンプレートが事前設定されており、job は id または name などの属性と組み合わせられます。テンプレートは中括弧で囲まれ、事前設定された メッセージ フィールドに示されるように、automation controller によって指定される固定のフィールドセットから作成されます。

この事前設定されたフィールドでは、イベントの通知を受けた受信者に共通して表示されるメッセージが提案されています。ただし、ジョブに関連した独自の属性を必要に応じて追加することにより、これらのメッセージを異なる条件でカスタマイズできます。カスタムの通知メッセージは、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 }} には以下のフィールドが含まれます。

  • id

  • name

  • url

  • created_by

  • started

  • finished

  • status

  • traceback

  
  

  作成された辞書は次のようになります。

  {"id": 18,
   "name": "Project - Space Procedures",
   "url": "https://host/#/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 }} がジョブでレンダリングされる場合は、以下の追加フィールドが含まれます。

  • inventory

  • project

  • playbook

  • credential

  • limit

  • extra_vars

  • hosts

  
  

  作成された辞書は次のようになります。

  {"id": 12,
   "name": "JobTemplate - Launch Rockets",
   "url": "https://host/#/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://host/#/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」を参照してください。

Automation controller requires valid syntax in order to retrieve the correct data to display the messages. For a list of supported attributes and the proper syntax construction, refer to the Supported Attributes for Custom Notifications section of this guide.

無効な構文や使用できないフィールドの参照を使用する通知テンプレートを作成すると、エラーの内容を示すエラーメッセージが表示されます。通知のカスタムメッセージを削除すると、この場所にはデフォルトのメッセージが表示されます。

26.6. 通知の有効化と無効化¶

特定のジョブ実行の終了時に成功か失敗かを通知することに加えて、そのジョブの開始時に通知する内容を選択できます。以下は留意が必要な動作です。

• ワークフローテンプレート (WFJT) でも、ワークフロー内のジョブテンプレート (JT) でも開始時の通知が有効化されている場合には、両方のメッセージが受信される

• WFJT 内の多くの JT で通知の実行を有効化できる

• スライスされたジョブテンプレート (SJT) で実行される通知を有効化でき、各スライスが通知を生成するようになる

• ジョブ開始時の通知の実行が有効化されている場合に、その通知が削除されると、JT は引き続き実行されるが、エラーメッセージが表示される

ジョブの開始、ジョブの成功、ジョブの失敗、またはこれらの任意の組み合わせの通知を、以下のリソースの 通知 タブから有効化できます。

• ジョブテンプレート

• ワークフローテンプレート

• プロジェクト (以下の例を参照)

• インベントリーソース

• 組織

承認ノードがあるワークフローテンプレートの場合は、開始、成功、および エラー に加えて、以下のように特定の承認関連のイベントを有効または無効にできます。

これらのタイプのノードの操作の詳細については、「承認ノード」を参照してください。

26.7. 通知用の host のホスト名設定¶

System Settings で、Service のベース URL フィールドの https://server.example.com を、希望のホスト名に置き換えることで、通知ホスト名を変更できます。

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

26.8. 通知 API¶

エンドポイントの started 、success、または error を使用します。

/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 アクションも使用されます。

• 組織

• プロジェクト

• インベントリーソース

• ジョブテンプレート

• システムジョブテンプレート

• ワークフロージョブテンプレート