Documentation

27. 通知

Notification TemplateNotification 类型的实例(电子邮件、Slack、Webhook 等),带有名称、描述和定义的配置。

例如:

  • 电子邮件通知模板需要用户名、密码、服务器和收件人

  • Slack 通知模板需要令牌和频道列表

  • Webhook 通知模板需要 URL 和标头

通知是一个通知模板的清单;例如,作业失败时使用通知模板定义的配置发送通知。

在高级别上,通知系统的典型流程按如下方式运作:

  • 用户在 /api/v2/notification_templates 端点创建 REST API 的通知模板(通过 API 或 UI)。

  • 用户在需要通知(已启动、成功或错误)的适当触发器级别将通知模板分配给支持它(作业模板的所有变体,以及机构和项目)的各种对象。例如,用户可能希望分配特定的通知模板以在作业模板 1 失败时触发。在这种情况下,用户会在 /api/v2/job_templates/n/notification_templates_error API 端点中将通知模板与作业模板相关联。

  • 您可以在作业启动时设置通知,而不只是在作业结束时。用户和团队也可以定义他们自己的通知,这些通知可以附加到任意作业。

27.1. 通知层次结构

在某些级别分配的通知模板将继承在父对象上定义的模板,如下所述:

  • 作业模板将使用在其上定义的通知模板,以及从作业模板使用的项目中和列出了该作业模板的机构中继承通知模板(通过项目)。

  • 项目更新将使用项目上定义的通知模板,并将继承与其关联的机构中的通知模板

  • 清单更新将使用列出了该清单的机构上定义的通知模板

  • 临时命令将使用与清单关联的机构上定义的通知模板

27.2. 工作流

当作业成功或失败时,错误或成功处理程序将按照以上定义的流程拉取相关的通知模板列表。然后,它会为每个包含作业相关详情的通知模板创建一个通知对象,然后将其发送到目的地(电子邮件地址、slack 频道、sms 号码等)。这些通知对象可作为作业类型(作业、库存更新、项目更新)的相关资源提供,也位于 /api/v2/notifications。您还可以通过检查通知模板的相关资源来查看由其发送的通知。

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

27.3. 创建通知模板

要创建通知模板,请执行以下操作:

  1. 从左侧导航栏中点击 Notifications

  2. Add 按钮。

_images/notifications-template-add-new.png
  1. 在相应字段中输入通知名称和描述,并指定其所属机构(必需)。

  2. Type 下拉菜单中选择一种通知类型。如需了解更多信息,请参阅后续部分。

  3. 完成所有所需信息后,点击 Save 添加通知。

27.4. 通知类型

automation controller 支持的通知类型:

以上每一种通知都有自己的配置和行为性语义,并需要以不同的方式对其进行测试。此外,您可以自定义每种通知类型的具体细节,或一组触发通知的条件。如需了解更多有关配置自定义通知的详情,请参阅 创建自定义通知。以下几个部分将尽量详细介绍每种通知类型。

27.4.1. 电子邮件

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

您必须提供以下详情来设置电子邮件通知:

  • 主机

  • 接收者列表

  • 发件人电子邮件

  • 端口

  • Timeout(以秒为单位):允许您指定 automation controller 在放弃前可以尝试连接电子邮件服务器的时间限度,最多 120 秒。

_images/notification-template-email.png

27.4.2. Grafana

Grafana 是一个简单直接的集成。首先,在 Grafana system 中创建一个 API 密钥(这是提供给 automation controller 的令牌)。

您必须提供以下详情来设置 Grafana 通知:

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

  • Grafana API Key:用户必须首先在 Grafana 系统中创建一个 API 密钥(这是提供给 automation controller 的令牌)。

其他值得注意的选项有:

  • ID of the Dashboard:当您为 Grafana 帐户创建 API 密钥时,您可以设置具有其自身唯一 ID 的仪表板。

  • ID of the Panel:如果您在 Grafana 界面中添加了面板和图形,您可以在这里指定其 ID。

  • Annotation:输入关键字,以帮助识别您要配置的事件的类型。

  • Disable SSL Verification:默认情况下 SSL 验证是开启的,但您可以选择关闭验证目标证书真实性的功能。使用内部或私有 CA 的环境应该选择此选项来禁用验证。

_images/notification-template-grafana.png

27.4.3. IRC

IRC 通知采用 IRC bot 的形式,它将进行连接,将消息传送到频道或单独的用户,然后断开连接。通知 bot 还支持 SSL 身份验证。bot 目前不支持 Nickserv 身份识别。如果某个频道或用户不存在或者没有在线,则通知不会失败。通知失败仅用于代表连接失败。

连接信息很简单:

  • IRC Server Password(可选):IRC 服务器可以要求提供密码才能连接。如果服务器不需要密码,请保留空白

  • IRC Server Port:IRC 服务器端口

  • IRC Server Address:IRC 服务器的主机名或地址

  • IRC Nick:bot 连接到服务器显示的昵称

  • Destination Channels or Users:要将通知发送到的用户和/或频道列表。

  • SSL Connection(可选):bot 是否应使用 SSL 进行连接

_images/notification-template-irc.png

27.4.4. Mattermost

Mattermost 通知类型为 Mattermost 的消息和协作工作区提供了一个简单的接口。可以指定的参数有:

  • Target URL(必需):将 POST 到的完整 URL

  • 用户名

  • 频道

  • Icon URL:指定要为此通知显示的图标

  • Disable SSL Verification:关闭验证目标证书真实性的功能。使用内部或私有 CA 的环境应该选择此选项来禁用验证。

_images/notification-template-mattermost.png

27.4.5. PagerDuty

PagerDuty 是一个简单直接的集成。首先,在 PagerDuty system 中创建一个 API 密钥(这是提供给 automation controller 的令牌),然后创建一个“Service”,它提供的“Integration Key”也会提供给 automation controller。其他必需的选项为:

  • API Token:用户必须首先在 PagerDuty 系统中创建一个 API 密钥(这是提供给 automation controller 的令牌)。

  • PagerDuty Subdomain:当您注册 PagerDuty 帐户时,您会收到一个用来进行通信的唯一子域。例如,如果您以“testuser”身份注册,Web 仪表板将位于 testuser.pagerduty.com,并且您将提供 API testuser 作为子域(而非完整的域)。

  • API 服务/集成密钥

  • Client Identifier:这将与警报内容一同发送到 pagerduty 服务,以帮助识别使用 api 密钥/服务的服务。这在多个集成使用相同的 API 密钥和服务时很有用。

_images/notification-template-pagerduty.png

27.4.6. Rocket.Chat

Rocket.Chat 通知类型为 Rocket.Chat 的协作和通信平台提供了一个接口。可以指定的参数有:

  • Target URL(必需):将 POST 到的完整 URL

  • 用户名

  • Icon URL:指定要为此通知显示的图标

  • Disable SSL Verification:关闭验证目标证书真实性的功能。使用内部或私有 CA 的环境应该选择此选项来禁用验证。

_images/notification-template-rocketchat.png

27.4.7. Slack

Slack 是一个协作团队通讯和消息传输工具,可以轻松进行配置。

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

在设置了 bot/app 后,导航到"Your Apps",点新创建的应用,进入 Add features and functionality 来配置传入的 webhook、bot 和权限,并 在工作空间中按照应用

您还必须邀请通知 bot 加入与 Slack 相关的频道。请注意,不支持私人消息。

_images/notification-template-slack.png

27.4.8. Twilio

Twilio 服务是一个语音和 SMS 自动化服务。在您登录后,必须创建一个用来发送消息的电话号码。然后您以在 Programmable SMS 下定义一个“Messaging Service”并将您之前创建的号码与之关联。

请注意,在被允许使用此号码发送到任意号码前,您可能需要先验证它或一些其他信息。消息服务不需要状态回调 URL,它也不需要具备处理入站消息的功能。

在您的单独(或子)帐户设置中,您将有 API 凭证。Twilio 使用两个凭证来确定 API 请求来自哪个帐户:用作用户名的“Account SID”,以及用作密码的“Auth Token”。

要设置 Twilio,请提供以下详情:

  • 帐户令牌

  • Source Phone Number(这是与上述消息服务关联的号码,必须采用“+15556667777”的格式)

  • Destination SMS number(这是接收 SMS 的号码列表,应该是 10 位电话号码)

  • 帐户 SID

_images/notification-template-twilio.png

27.4.9. Webhook

webhook 通知类型提供了一个用于将 POST 发送到预定义的 Web 服务的简单接口。automation controller 将使用应用程序/json 内容类型向这个地址 POST 数据有效负载,其中包含 json 格式的所有相关详情。一些 Web 服务 API 预期 HTTP 请求采用特定格式并包含特定字段。您可以使用以下方法配置更多 webhook 通知设置:

  • 配置 HTTP 方法(使用 POSTPUT

  • 传出请求的正文

  • 配置身份验证(使用基本身份验证)

用于配置 Webhook 的参数有:

  • 用户名

  • 基本验证密码

  • Target URL(必需):Webhook 通知将 PUT 或 POST 到的完整 URL。

  • Disable SSL Verification:默认情况下 SSL 验证是开启的,但您可以选择关闭验证目标证书真实性的功能。使用内部或私有 CA 的环境应该选择此选项来禁用验证。

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

  • HTTP Method(必需)。选择 Webhook 的方法:

    • POST:创建新资源。也用作不适合于其他类别的操作的总括。除非您知道 Webhook 服务需要 PUT,否则很可能需要 POST。

    • PUT:更新特定资源(按标识符)或资源集合。如果事先知道资源标识符,PUT 也可以用于创建特定资源。

_images/notification-template-webhook.png

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

默认情况下,对于 success/fail 状态的 Webhook 端点,Automation controller 返回以下数据:

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}}}

27.5. 创建自定义通知

您可以通过使用切换按钮在通知表单的底部启用 Customize Messages 部分来为每个 通知类型 customize the text content

_images/notification-template-customize.png

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

  • 开始

  • 成功

  • 错误

  • 工作流已批准

  • 工作流已拒绝

  • 工作流正在运行

  • 工作流超时

消息表单会根据您所配置的通知类型而有所不同。例如,电子邮件和 PagerDuty 通知的消息会显示一个带有主题和正文的典型电子邮件表单,在这种情况下,automation controller 会将这些字段显示为 MessageMessage Body。其他通知类型对每种事件类型只预期 Message

_images/notification-template-customize-simple.png

Message 字段已预先填充一个模板,其中包含顶层变量 job 以及一个属性,如 idname。模板用大括号括起,且可以从 automation controller 提供的固定字段集合中提取,如预填充的 Messages 字段所示。

_images/notification-template-customize-simple-syntax.png

这个预先填充的字段会建议通常向事件通知的接收者显示的消息。但是,您可以根据需要为作业添加您自己的属性,以使用不同的条件自定义这些消息。自定义通知消息使用 Jinja 呈现,这是 Ansible playbook 使用的同一模板引擎。

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

  • 信息总是字符串(只能是一行;不允许使用新行)

  • 消息正文可以是字典或者是文本块:

    • WebhooksPagerDuty 的消息正文使用字典定义。它们的默认消息正文为 {{ 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

    注解

    目前,您无法查询 {{ job_metadata }} 中的各个字段。在通知模板中使用 {{ job_metadata }} 时,所有数据都会被返回。

    生成的字典将类似如下:

    {"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 需要有效的语法来检索用于显示消息的正确数据。对于支持的属性列表和正确的语法构建,请参阅本指南的 支持的自定义通知属性 部分。

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

注解

如果您在没有编辑自定义消息(或编辑过且从没有恢复到默认值)的情况下保存通知模板,Details 屏幕会假定默认值,且不会显示自定义消息表。如果您编辑并保存任何值,则整个表会显示在 Details 屏幕中。

_images/notifications-with-without-messages.png

27.6. 启用和禁用通知

除了在作业运行结束时通知您成功或失败以外,您可以选择在某个特定作业启动时要通知的通知。需要记住以下一些行为:

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

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

  • 您可以启用在分片作业模板 (SJT) 启动时运行通知,并且每个分片都会生成通知

  • 如果您启用在作业启动时运行通知,且该通知被删除,则 JT 会继续运行,但会生成错误消息

您可以从以下资源中的 Notifications 标签页中启用作业启动、作业成功和作业失败时通知,或者它们中的任何组合:

  • 任务模板

  • 工作流模板

  • 项目(如下例所示)

  • 清单源

  • 机构

_images/projects-notifications-example-list.png

对于具有批准节点的工作流模板,除了 StartSuccessFailure 以外,您还可启用或禁用某些与批准相关的事件:

_images/wf-template-completed-notifications-view.png

有关使用这些节点类型的详情,请参阅 批准节点

27.7. 为通知配置 host 主机名

System Settings 中,您可以将 Base URL of The Service 字段中的默认值替换为您首选的主机名,以更改通知主机名。

_images/configure-tower-system-misc-baseurl.png

刷新您的许可证也会更改通知主机名。automation controller 的新安装不必设置通知主机名。

27.7.1. 重置 TOWER_URL_BASE

automation controller 用来确定如何定义基本 URL(TOWER_URL_BASE)的主要方法是通过查看传入请求并根据该传入请求设置服务器地址。

Automation controller 会首先从数据库中获取设置值。如果没有找到任何设置值,Tower 会返回使用设置文件中的值。如果用户通过导航到 automation controller 主机的 IP 地址来发布许可证,则会将发布的许可证写入数据库中的设置条目。

如果选择了错误的地址,要更改 TOWER_URL_BASE,使用您想要在通知中出现的 DNS 条目从 Settings 菜单中进入到 Miscellaneous System settings,并重新添加您的许可证。

27.8. 通知 API

使用 startedsuccesserror 端点:

/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 端点具有适用于以下各项的 GETPOST 操作:

  • 机构

  • 项目

  • 清单源

  • 作业模板

  • 系统作业模板

  • 工作流任务模板