23. 通知¶

23.1. 通知层次结构¶

在特定级别分配的通知模板将继承在父对象上定义的模板，如下所示

• 作业模板将使用在其上定义的通知模板，并继承来自作业模板使用的项目以及它列出的组织（通过项目）的通知模板。

• 项目更新将使用在项目上定义的通知模板，并将继承与其关联的组织的通知模板

• 库存更新将使用在其列出的组织中定义的通知模板

• 临时命令将使用与其关联的库存所在的组织中定义的通知模板

23.2. 工作流¶

当作业成功或失败时，错误或成功处理程序将使用上面定义的过程拉取相关通知模板列表。然后，它将为每个模板创建一个通知对象，其中包含有关作业的相关详细信息，然后将其发送到目标（电子邮件地址、Slack 频道、短信号码等）。这些通知对象作为相关资源在作业类型（作业、库存更新、项目更新）上可用，并且还在/api/v2/notifications上可用。您也可以通过检查其相关资源来查看从通知模板发送了哪些通知。

如果通知失败，它不会影响与其关联的作业或导致作业失败。可以在其详细信息端点 (/api/v2/notifications/<n>) 查看通知的状态。

23.3. 创建通知模板¶

要创建通知模板

1. 从左侧导航栏中单击通知 () 图标。

2. 单击按钮。

3. 在各自的字段中输入通知的名称和描述，并指定它所属的组织（必填）。

4. 从类型下拉菜单中选择通知类型。有关更多信息，请参考后续部分。

5. 完成所有必需的信息后，单击保存添加通知。

23.4. 通知类型¶

Ansible Tower 支持的通知类型

每种通知都有其自身的配置和行为语义，测试它们可能需要以不同的方式进行。此外，您可以将每种类型的通知定制到特定的细节，或一组触发通知的条件。有关配置自定义通知的更多详细信息，请参见创建自定义通知。以下部分将尽可能详细地介绍每种类型的通知。

23.4.1. 电子邮件¶

电子邮件通知类型支持各种各样的 SMTP 服务器，并支持 TLS/SSL 连接。

您必须提供以下详细信息来设置电子邮件通知

• 主机

• 收件人列表

• 发件人电子邮件

• 端口

• 超时（以秒为单位）：允许您指定最长 120 秒，Tower 在放弃连接到电子邮件服务器之前尝试连接的时间长度。

23.4.2. Grafana¶

Grafana 是一个相当直接的集成。首先，在 Grafana 系统 中创建一个 API 密钥（这是提供给 Tower 的令牌）。

您必须提供以下详细信息来设置 Grafana 通知

• Grafana URL：Grafana API 服务的 URL，通常为 http://yourcompany.grafana.com。

• Grafana API 密钥：用户必须首先在 Grafana 系统中创建一个 API 密钥（这是提供给 Tower 的令牌）。

其他值得注意的选项是

• 仪表板 ID：当您为 Grafana 帐户创建 API 密钥时，您可以设置一个仪表板，它有自己的唯一 ID。

• 面板 ID：如果您在 Grafana 界面中添加了面板和图形，您可以在此处指定其 ID。

• 注释标签：输入有助于识别您正在配置的通知事件类型的关键字。

• 禁用 SSL 验证：SSL 验证默认情况下是开启的，但您可以选择关闭 Tower 尝试验证目标证书的真实性。使用内部或私有 CA 的环境应选择此选项以禁用验证。

23.4.4. IRC¶

Tower IRC 通知采用 IRC 机器人的形式，它将连接、将消息传递到频道或单个用户，然后断开连接。Tower 通知机器人也支持 SSL 身份验证。Tower 机器人目前不支持 Nickserv 身份验证。如果频道或用户不存在或不在线，则通知不会失败；失败场景专门保留给连接性。

连接信息很简单

• IRC 服务器密码（可选）：IRC 服务器可能需要密码才能连接。如果服务器不需要密码，请留空

• IRC 服务器端口：IRC 服务器端口

• IRC 服务器地址：IRC 服务器的主机名或地址

• IRC 昵称：机器人连接到服务器后的昵称

• 目标频道或用户：要向其发送通知的用户和/或频道列表。

• SSL 连接（可选）：机器人连接时是否应使用 SSL

23.4.5. Mattermost¶

Ansible Tower 中的 Mattermost 通知类型提供了一个简单的 Mattermost 消息传递和协作工作空间界面。可以指定的参数是

• 目标 URL（必需）：将发布到的完整 URL

• 用户名

• 频道

• 图标 URL：指定此通知要显示的图标

• 禁用 SSL 验证：关闭 Tower 尝试验证目标证书真实性的操作。使用内部或私有 CA 的环境应选择此选项以禁用验证。

23.4.6. PagerDuty¶

PagerDuty 是一个相当直接的集成。首先，在 PagerDuty 系统 中创建一个 API 密钥（这是提供给 Tower 的令牌），然后创建一个“服务”，该服务提供一个“集成密钥”，该密钥也将提供给 Tower。其他必需的选项是

• API 令牌：用户必须首先在 PagerDuty 系统中创建一个 API 密钥（这是提供给 Tower 的令牌）。

• PagerDuty 子域名：当您注册 PagerDuty 帐户时，您将收到一个唯一的子域名来与之通信。例如，如果您以“towertest”的身份注册，则 Web 仪表板将在 towertest.pagerduty.com，并且您将向 Tower API 提供 towertest 作为子域名（而不是完整域名）。

• API 服务/集成密钥

• 客户端标识符：这将与警报内容一起发送到 pagerduty 服务，以帮助识别使用 API 密钥/服务的服务。如果多个集成使用相同的 API 密钥和服务，这将非常有用。

23.4.7. Rocket.Chat¶

Ansible Tower 中的 Rocket.Chat 通知类型提供了一个 Rocket.Chat 协作和通信平台的界面。可以指定的参数是

• 目标 URL（必需）：将发布到的完整 URL

• 用户名

• 图标 URL：指定此通知要显示的图标

• 禁用 SSL 验证：关闭 Tower 尝试验证目标证书真实性的操作。使用内部或私有 CA 的环境应选择此选项以禁用验证。

23.4.8. Slack¶

Slack 是一款协作团队通信和消息传递工具，配置起来非常容易。

您必须提供以下内容来设置 Slack 通知

• 一个 Slack 应用（有关如何创建 Slack 应用的信息，请参阅 Slack 文档的 基本应用设置 页面）

• 一个令牌（请参阅 启用与机器人的交互，以及 令牌类型 文档页面上的机器人令牌的具体详细信息）

设置完机器人/应用后，您必须导航到“您的应用”，单击新创建的应用，然后转到 **添加功能和功能性**，这允许您配置传入 Webhook、机器人和权限；以及 **将您的应用安装到您的工作区**。

您还必须邀请通知机器人加入 Tower 中相关的频道。请注意，不支持私人消息。

23.4.9. Twilio¶

Twilio 服务是一个语音和 SMS 自动化服务。登录后，您必须创建一个电话号码，从中发送消息。然后，您可以在可编程 SMS 下定义一个“消息服务”，并将您之前创建的号码与它关联。

请注意，您可能需要验证此号码或其他一些信息，然后才能使用它向任何号码发送信息。消息服务不需要状态回调 URL，也不需要处理传入消息的能力。

在您的个人（或子）帐户设置下，您将拥有 API 凭据。Twilio 使用两个凭据来确定 API 请求来自哪个帐户。“帐户 SID”充当用户名，“身份验证令牌”充当密码。

要设置 Twilio，请提供以下详细信息

• 帐户令牌

• 源电话号码（这是与上述消息服务关联的号码，必须以“+15556667777”的形式给出）

• 目标 SMS 号码（这将是接收 SMS 的号码列表，应为 10 位电话号码）

• 帐户 SID

23.4.10. Webhook¶

Ansible Tower 中的 webhook 通知类型提供了一个简单的界面来将 POST 发送到预定义的 Web 服务。Tower 将使用 application/json 内容类型将 POST 发送到此地址，数据有效负载包含所有相关详细信息，以 json 格式。某些 Web 服务 API 期望 HTTP 请求以特定格式和特定字段的形式出现。您可以通过以下方式配置更多 webhook 通知

• 配置 HTTP 方法（使用 **POST** 或 **PUT**）

• 传出请求的主体

• 配置身份验证（使用基本身份验证）

配置 webhook 的参数是

• 用户名

• 基本身份验证密码

• 目标 URL（必需）：webhook 通知将发布或 PUT 到的完整 URL。

• 禁用 SSL 验证：SSL 验证默认情况下是开启的，但您可以选择关闭 Tower 尝试验证目标证书的真实性。使用内部或私有 CA 的环境应选择此选项以禁用验证。

• HTTP 标头（必需）：JSON 格式的标头，其中键和值是字符串。例如，{"Authentication": "988881adc9fc3655077dc2d4d757d480b5ea0e11", "MessageType": "Test"}

• HTTP 方法（必需）。选择您的 webhook 的方法

  • POST：创建新的资源。它也充当不适合其他类别操作的万能方法。除非您知道您的 webhook 服务期望 PUT，否则您可能需要 POST。

  • PUT：更新特定资源（通过标识符）或资源集合。如果事先知道资源标识符，PUT 也可以用来创建特定资源。

23.4.10.1. Webhook 有效负载¶

Tower 默认情况下会将以下数据发送到 webhook 端点

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

通过 webhook 消息发送的 started 通知示例，因为它是 Tower 返回的

{"id": 38, "name": "Demo Job Template", "url": "https://towerhost/#/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

Tower 默认情况下会将以下数据返回到 webhook 端点，用于 success/fail 状态

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

通过 webhook 消息发送的 success/fail 通知示例，因为它是 Tower 返回的

{"id": 46, "name": "AWX-Collection-tests-tower_job_wait-long_running-XVFBGRSAvUUIrYKn", "url": "https://towerhost/#/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-tower_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}}}

23.5. 创建自定义通知¶

您可以 自定义每种通知类型的文本内容，方法是在通知表单底部启用 **自定义消息** 部分。

您可以为各种作业事件提供自定义消息

• 开始

• 成功

• 错误

• 工作流已批准

• 工作流被拒绝

• 工作流正在运行

• 工作流超时

消息表单因您正在配置的通知类型而异。例如，电子邮件和 PagerDuty 通知的消息具有典型的电子邮件表单外观，带有主题和正文，在这种情况下，Tower 将字段显示为 **消息** 和 **消息正文**。其他通知类型仅期望每种类型的事件都有一个 **消息**

**消息** 字段预先填充了一个模板，该模板包含一个顶级变量 job，以及一个属性，如 id 或 name，例如。模板用花括号括起来，可以从 Tower 提供的固定字段集中提取，如预先填充的 **消息** 字段所示。

此预填充字段建议向收到事件通知的收件人显示常见的通知信息。但是，您可以根据需要为作业添加自己的属性来自定义这些信息，并使用不同的条件。自定义通知信息使用 Jinja 渲染，Jinja 是 Ansible playbook 使用的相同模板引擎。

消息和消息正文具有不同类型的內容

• 消息始终只是字符串（仅限单行；不允许换行）

• 消息正文将是字典或文本块

  • Webhooks 和 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://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 }}，它将包含以下附加字段

  • inventory

  • project

  • playbook

  • credential

  • limit

  • extra_vars

  • hosts

  
  

  生成的字典将类似于

  {"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."
  }
  

有关更多详细信息，请参阅 使用 Jinja2 的变量。

Tower 需要有效的语法才能检索正确的数据以显示消息。有关支持的属性和正确的语法结构的列表，请参阅 自定义通知支持的属性 在Ansible 自动化平台安装和参考指南中。

如果您创建使用无效语法或引用不可用字段的通知模板，则会显示一条错误消息，指示错误的性质。如果您删除通知的自定义消息，则会显示默认消息。

23.6. 启用和禁用通知¶

除了在作业运行结束时通知您成功或失败之外，您还可以选择在特定作业开始时通知您哪些通知。一些需要注意的行为

• 如果工作流模板 (WFJT) 启用了开始时的通知，并且该工作流中的作业模板 (JT) 也启用了开始时的通知，您将收到两者的通知

• 您可以启用通知以在 WFJT 中的许多 JT 上运行

• 您可以启用通知以在切片作业模板 (SJT) 开始时运行，并且每个切片将生成一条通知

• 当您启用通知以在作业开始时运行，并且该通知被删除时，JT 会继续运行，但会导致错误消息

您可以从以下资源的通知选项卡启用作业开始、作业成功和作业失败的通知，或启用这些通知的任何组合

• 作业模板

• 工作流模板

• 项目（如以下示例所示）

• 清单源

• 组织

对于具有审批节点的工作流模板，除了开始、成功和失败之外，您还可以启用或禁用某些与审批相关的事件

有关使用这些类型节点的更多详细信息，请参阅 审批节点。

23.7. 配置 towerhost 主机名以进行通知¶

在 系统设置 中，您可以使用首选主机名替换Tower 主机基本 URL字段中的 https://tower.example.com，以更改通知主机名。

刷新 Tower 许可证也会更改通知主机名。Ansible Tower 的新安装应该不需要设置通知的主机名。

23.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 操作

• 组织

• 项目

• 清单源

• 作业模板

• 系统作业模板

• 工作流作业模板