Documentation

19. 工作流任务模板

:term:`workflow job template`将一个由不同资源组成的序列链接在一起,完成的任务是将属于发布过程一部分的完整作业集合作为一个单元来跟踪。这些资源可能包括:

  • 作业模板

  • 工作流模板

  • 项目同步

  • 清单源同步

(templates-icon) 菜单会打开当前可用的工作流和作业模板列表。默认视图为折叠状态 (Compact),显示模板名称、模板类型和使用该模板运行的作业的状态,但您可以点击 Expanded 查看更多信息。该列表按名称字母顺序排序,但您可以按照其他条件排序,或者根据模板的不同字段和属性进行搜索。在此屏幕中,您可以启动 (launch)、复制 ( copy ) 和删除 ( delete ) 作业模板。删除作业模板前,请确保它不在工作流作业模板中使用。

只有工作流模板具有工作流可视化工具图标 (wf-viz-icon) 作为访问工作流编辑器的快捷方式。

Wf templates - home with example wf template

注解

工作流模板可以用作另一个工作流模板的构建块。工作流模板中的许多参数允许您启用 Prompt on Launch,这些参数可在工作流作业模板级别进行修改,且不会影响在单独工作流模板级别分配的值。如需了解相关说明,请参阅 工作流可视化工具 部分。

19.1. 创建工作流模板

要创建新工作流作业模板,请执行以下操作:

  1. 点击 add options template 按钮,然后从菜单列表中选择 Workflow Template

Wf templates - create new wf template

  1. 在以下字段中输入相关信息:

  • Name:输入工作流模板的名称。

  • Description:根据需要输入任意描述(可选)。

  • **Organization**(可选):输入或搜索要关联工作流的机构。

  • **Inventory**(可选):输入或从当前登录的 Tower 用户可用的清单中搜索要用于此工作流模板的清单。

  • Prompt on Launch:如果选择此项,则可在启动此工作流模板时,或在其他工作流模板中使用此工作流模板时提供清单。

  • **Limit**(可选):为您的工作流将要运行的服务器子集指定限制。这个值是用于进一步限制受 playbook 管理或影响的主机列表的主机模式。可以用冒号(“:”)来分隔多个模式。与核心 Ansible 一样,“a:b”表示“在组 a 或 b 中”,“a:b:&c”表示“在 a 或 b 中但必须在 c 中”,“a:!b”表示“在 a 中且一定不在 b 中”。

  • Prompt on Launch:如果选择此选项,即使提供了默认值,也会在启动时提示您选择一个限制。

  • **SCM Branch**(可选):指定分支来覆盖提示分支的所有作业模板节点。

    • Prompt on Launch:如果选择此选项,即使提供了默认值,也会在启动时提示您选择一个 SCM 分支。

  • Labels:提供描述此工作流模板的可选标签,如“dev”或“test”。标签可用于对 Tower 显示中的工作流模板和完成的作业进行分组和过滤。

    • 在将标签添加到工作流模板时会创建标签。标签使用工作流模板中提供的项目关联到单个机构。如果机构成员具有编辑权限(如 admin 角色),则他们可在工作流模板中创建标签。

    • 保存工作流模板后,标签会显示在模板概述中。

    • 点击标签旁边的“x”可删除它。标签被删除后,便不再与工作流或工作流模板关联,该标签会从机构标签列表中永久删除。

    • 在启动时,作业会继承工作流模板中的标签。如果从工作流模板中删除某个标签,它也会从作业中删除。

_images/job-template-create-labels.png _images/job-template-saved-labels.png
  • Options

  • 选中 Enable Concurrent Jobs 以允许同时运行此工作流。如需了解更多信息,请参阅 决定 Ansible Tower 容量和作业的影响

  • 选中 Enable Webhook 以打开与用于启动作业模板的预定义 SCM 系统 Web 服务进行接口的功能。当前支持的 SCM 系统为 GitHub 和 GitLab。

如果您启用 Webhook,会显示其他字段,提示输入更多信息:

  • Webhook Service:从中选择侦听 Webhook 的服务

  • **Webhook Credential**(可选):提供 GitHub 或 GitLab 个人访问令牌 (PAT) 作为凭证,用来向 Webhook 服务发回状态更新。在可以选择之前,凭证必须存在。请参阅 凭证类型 以创建一个凭证。

Save 后,会填充其他字段并自动打开工作流可视化工具。

  • Webhook URL:自动填充将 POST 请求发送到的 Webhook 服务的 URL。

  • Webhook Key:生成的共享 secret,供 Webhook 服务用来签署发送到 Tower 的有效负载。必须在 Webhook 服务上的设置中对此进行配置,以使 Tower 接受来自该服务的 Webhook。

有关设置 Webhook 的更多信息,请参阅 使用 Webhook

  • Extra Variables

    • 向 playbook 传递额外的命令行变量。这是 ansible-playbook 的“-e”或“--extra-vars”命令行参数,记录在 Ansible 文档中,请参阅 Passing Variables on the Command Line

    • 使用 YAML 或 JSON 提供键/值对。这些变量具有最大优先级值并且会覆盖在其他位置指定的其他变量。示例值可能为:

      git_branch: production
      release_version: 1.5
      

    有关额外变量的更多信息,请参阅 额外变量

    • Prompt on Launch:如果选择此选项,即使提供了默认值,也会在启动时提示您选择一个命令行变量。

注解

如果您希望能够在计划中指定 extra_vars,您必须在工作流模板中为 EXTRA VARIABLES 选择 Prompt on Launch,或者在工作流模板中启用问卷调查,然后那些回答的问卷调查问题将成为 extra_vars

  1. 当您完成工作流模板配置后,请点击 Save

保存模板后会退出工作流模板页面,并打开工作流可视化工具,以便您构建工作流。如需进一步说明,请参阅 工作流可视化工具 部分。或者,您可以关闭工作流可视化工具来返回到新保存模板的 Details 标签,以便查看、编辑、添加权限、通知、计划和问卷调查,或查看完成的作业,并在以后构建工作流模板。或者,您可以点击 Launch 来启动工作流,但在启动之前,您必须先保存模板,否则 Launch 按钮将一直灰显。此外请注意,只有在保存了模板后,Notifications 标签页才会显示。

_images/wf-templates-wf-template-saved.png

当新创建的工作流模板出现在屏幕底部的模板列表中时,您可以确认模板已保存。

Wf templates - newly added wf template

注解

如果在工作流模板上指定了清单,则该清单会显示在模板列表视图中。

_images/wf-templates-list-default-inventory.png

19.2. 使用权限

点击 Permissions 让您可以查看、授予、编辑和删除用户以及团队成员的相关权限。

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

点击 add 按钮为这个工作流模板创建新权限。

在这个示例中,选择了两个用户和一个团队,并为他们各自了授予这个工作流模板的权限。

_images/wf-template-assign-permissions-view.png

请注意,您不必在团队或用户之间选择,而且您可以同时为这两者分配权限。

19.3. 使用通知

点击 Notifications 可以查看您设置的任何通知集成。只有在保存了模板后,Notifications 标签页才会显示。

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

请使用切换按钮启用或禁用要与特定模板搭配使用的通知。更多详情请参阅 启用和禁用通知

如果没有设置通知,请点击灰色框内的 NOTIFICATIONS 链接来创建新通知。

_images/wf-template-no-notifications-blank.png

有关配置各种通知类型的其他详情,请参阅 通知类型

19.4. 查看完成的作业

Completed Jobs 标签页提供了已运行的工作流模板列表。点击 Expanded 查看每个作业的各种详情。

_images/wf-template-completed-jobs-list.png

注解

如果在运行时指定了工作流级别清单,则该清单名称会显示在作业列表的工作流作业中:

_images/wf-template-completed-jobs-list-with-inventory.png

从此视图中,您可以点击作业 ID - 工作流作业的名称并查看其图形表示。以下示例显示了 141 - WF using JT 工作流作业的作业详情。

_images/wf-template-jobID-detail-example.png

如果工作流模板在另一个工作流中使用,作业详情会指示父工作流。

_images/wf-template-job-detail-with-parent.png

在上例中,点击父工作流模板 Overall 查看其 Job Details 页面以及节点和每个节点启动时的状态的图形详情。

_images/wf-template-jobs-detail-example.png

节点通过标签进行标记,可帮助您一眼就识别出它们。如需了解更多信息,请参阅 工作流可视化工具 部分中的图例

19.5. 使用计划

您可以点击 Schedules 来查看为此模板设置的所有计划。

Workflow Template - schedule

19.5.1. 调度工作流模板

要调度作业模板运行,请点击 Schedules 标签页。

  • 如果已经设置了调度,请检查、编辑或启用/禁用您的调度首选项。

  • 如果还没有设置调度,请参阅 调度 了解更多信息。

如果嵌套工作流中使用的工作流模板有问卷调查,或者为清单选项选择了 Prompt on Launch,则 PROMPT 按钮会显示在计划表单上的 SAVECANCEL 按钮旁边。点击 PROMPT 按钮会显示可选的 INVENTORY 步骤,您可以在此处提供或删除清单,或者在不做任何更改的情况下跳过该步骤。

19.6. 调查

在工作流作业模板创建或编辑屏幕中,包含运行或检查作业类型的工作流将提供一种设置问卷调查的方法。问卷调查为 playbook 设置额外变量,类似于“Prompt for Extra Variables”,但是以用户友好的问答方式进行。问卷调查还可允许验证用户输入。点击 survey 按钮可以创建问卷调查。

问卷调查的用例有很多。例如,运营人员可能希望向开发人员提供一个无需高级 Ansible 知识即可运行的“推送到阶段”按钮。启动时,该任务可能会提示输入问题的回答,例如:“我们应该发布什么标签?”

可以询问很多类型的问题,包括多项选择题。

19.6.1. 创建问卷调查

要创建问卷调查,请执行以下操作:

  1. 点击 survey 按钮来调出 Add Survey 窗口。

Workflow Job Template - create survey

使用屏幕顶部的 ON/OFF 切换按钮来快速激活或取消激活本次调查提示。

  1. 问卷调查可由任何数量的问题组成。对每个问题,请输入以下信息:

  • Name:询问用户的问题。

  • **Description**(可选):向用户询问的问题描述。

  • Answer Variable Name:将用户回答存储在其中的 Ansible 变量名称。这是供 playbook 使用的变量。变量名称不能包含空格。

  • Answer Type:从以下问题类型中选择。

    • Text:单行文本。您可以为该回答设置最小和最大长度(字符数)。

    • Textarea:多行文本字段。您可以为该回答设置最小和最大长度(字符数)。

    • Password:回答被视为敏感信息,和实际密码的处理方式很像。您可以为该回答设置最小和最大长度(字符)。

    • Multiple Choice (single select):选项列表,每次只能选择其中一个选项。请在 Multiple Choice Options 框中输入选项,每行一个。

    • Multiple Choice (multiple select):列表选项,每次可选择其中任意数量的选项。在 Multiple Choice Options 框中输入选项,每行一个。

    • Integer:整数。您可以为该回答设置最小和最大长度(字符数)。

    • Float:小数。您可以为该答案设置最小和最大长度(字符数)。

  • Default Answer:根据所选的类型,您可以问题的默认回答。这个值在界面中预先填充,并在用户未提供回答时使用。

  • Required:用户是否需要回答这个问题。

  1. 输入问题信息后,点击 add 按钮添加问题。

调查的样式化版本显示在 Preview 窗格中。对于任何问题,您可以点击 Edit 按钮编辑问题,Delete 按钮删除问题,然后点击并拖动网格图标来重新安排问题的顺序。

  1. 返回左窗格以添加其他问题。

  2. 完成后,点击 Save 保存问卷调查。

Workflow-template-completed-survey

19.6.2. 可选的问卷调查问题

问卷调查问题的 Required 设置决定了对于与之交互的用户,回答是不是可选的。

在后台,可选的问卷调查变量可在 extra_vars 中传递给 playbook,即使没有填写也一样。

  • 如果非文本变量(输入类型)标记为可选,且未填写,则不会将任何问卷调查 extra_var 传递给 playbook。

  • 如果文本输入或文本区域输入标记为可选,未填充,且最小 length > 0,则不会将任何问卷调查 extra_var 传递给 playbook。

  • 如果文本输入或文本区域输入标记为可选,未填写,且最小 length === 0,则会将该问卷调查 extra_var 传递给 playbook,并将值设为空字符串 ( "" )。

19.7. 工作流可视化工具

工作流可视化(Workflow Visualizer)是以图形化的方式将作业模板、工作流模板、项目同步和清单同步链接在一起以构建工作流模板的工具。在构建工作流模板之前,请参考 工作流 部分,以了解与父节点、子节点和同级节点的不同场景相关的注意事项。

19.7.1. 构建工作流

您可以设置以下两个或更多节点类型的任意组合来构建工作流:模板(作业模板或工作流作业模板)、项目同步、清单同步或批准。每个节点都以矩形表示,而关系及其关联的边缘类型由连接它们的直线(或链接)表示。

  1. 在工作流模板的详情/编辑视图中,点击 workflow editor 按钮或从模板列表中点击 (wf-viz-icon) 图标来启动工作流可视化工具。

_images/wf-editor-create-new.png
  1. 点击 start 按钮显示要添加到工作流中的节点列表。

_images/wf-editor-create-new-add-template-list.png
  1. 在右侧的窗格中,从下拉菜单中选择您要添加的节点类型:

_images/wf-add-node-selections.png

如果选择一个 Approval 节点,请参阅 批准节点 了解更多详情。

选择一个节点会提供与其关联的可用有效选项。通过点击节点旁的工具提示来访问该节点的详情。

_images/wf-node-selection-tooltip.png

注解

如果在填充工作流图形时选择了没有默认清单的作业模板,则会使用父工作流的清单。虽然作业模板中不需要凭证,但如果作业模板具有需要密码的凭证,则您无法为工作流选择该作业模板,除非将凭证替换为提示的凭证。

  1. 选择节点后,工作流即开始构建,且您必须指定要为所选节点执行的操作类型。此操作也称为*边缘类型*。

  2. 如果是根节点,边缘类型默认为 Always,且不可编辑。

_images/wf-editor-create-new-add-template-type.png

对于后续节点,您可以选择以下场景(类型)之一以应用到每个节点:

  • Always:无论成功还是失败都继续执行。

  • On Success:成功完成后执行下一个模板。

  • On Failure:失败后执行不同的模板。

  1. 如果是来自 Convergence 字段中的一个聚合节点,请选择其行为:

  • Any 是默认行为,它允许在触发下一个聚合节点前,只要*任何*节点如指定一般完成就可以。当一个父对象的状态满足其中一个运行状况,就会运行一个 ANY 子节点。换句话说,一个 ANY 节点需要**所有** 节点完成,但只有一个节点必须按预期完成。

  • 选择 All 来确保在聚合并触发下一个节点前,*所有*节点都如指定一般完成。使用 ALL 节点的目的是为了确保每个父节点都满足其预期结果后才运行子节点。工作流检查确保每个父节点都按预期执行,以便运行子节点。否则,它不会运行子节点。

如果选择,在视图中会将节点标记为 ALL

_images/wf-editor-convergent-node-all.png

注解

如果某个节点是根节点,或者没有与其聚合的节点,设置 Convergence 规则并不会其作用,它的行为是由触发节点的操作决定的。

  1. 如果工作流中使用的作业模板为其任何参数选择了 Prompt on Launch,则会出现 Prompt 按钮,供您在节点级别更改这些值。使用向导更改每个标签页中的只值,在 Preview 标签页中点 Confirm

_images/wf-editor-prompt-button-wizard.png

同样,如果工作流中使用的工作流模板为清单选项选择了 Prompt on Launch,则使用向导在提示符处提供清单。如果父工作流有自己的清单,它将覆盖在此提供的任何清单。

_images/wf-editor-prompt-button-inventory-wizard.png

注解

如果作业模板具有必填的可提示字段但没有默认字段,则创建节点时必须提供这些值,然后 Select 按钮才会变为启用状态。在通过 Prompt 按钮提供值之前,有两种情况会禁用 Select 按钮:1) 您在作业模板中选择了 Prompt on Launch 复选框,但没有提供默认值,或 2) 创建了必须回答的问卷调查问题,但没有提供默认回答。但是,凭证的情况**并非**如此。创建工作流节点时,“不允许”使用在启动时要求密码的凭证,因为在创建节点时必须提供启动该节点所需的一切。因此,如果作业模板提示输入凭证,Tower 会让您无法选择需要密码的凭证。

当提示向导关闭时,您还必须点击 Select 以将更改应用到该节点。否则,您所做的任何更改都将恢复到实际作业模板中设置的值。

_images/wf-editor-wizard-buttons.png

当节点被创建后,它会使用它的作业类型标记。与每个工作流节点关联的模板将根据进行过程中所选的运行场景运行。点击指南针 (compass) 图标可显示每个运行场景及其作业类型的图例。

_images/wf-editor-key-dropdown-list.png
  1. 将鼠标悬停在节点上可以添加 add node 另一个节点,编辑现有链接 edit link 或删除 delete node 所选节点。

_images/wf-editor-create-new-add-template.png
  1. 完成节点添加/编辑后,请点击 Select 以保存任何修改并将其呈现在图形视图中。有关构建工作流的可用方式,请参阅 节点构建场景

  2. 完成工作流模板构建后,请点击 Save 以保存整个工作流模板并返回到新的工作流模板详情页面。

重要

在此窗格上点击 Close 不会保存您的工作,而是会关闭整个工作流可视化工具,您必须重新开始。

19.7.1.1. 批准节点

选择 Approval 节点需要用户干预来推进工作流。此操作可用于在 playbook 间暂停工作流,以便用户批准继续到工作流中的下一个 playbook ,给用户指定的时间进行干预,此外,用户也可以尽快继续操作,而不需要等待某个其他触发器。

_images/wf-node-approval-form.png

超时的默认设置是 none,但您可以指定请求到期并自动被拒绝前的时间限度。选择并提供批准节点的信息后,它会显示在图形视图中,旁边带有一个暂停 (pause) 图标。

_images/wf-node-approval-node.png

批准者是可以执行包含批准节点的工作流作业模板、具有机构管理员或以上权限(针对与该工作流作业模板关联的机构)的任何人,或在该特定工作流作业模板中被明确分配了 Approve 权限的任何用户。

_images/wf-node-approval-notifications.png

如果待批准的节点没有在指定的时间限制内获得批准(如果分配了过期时间),或者被拒绝,则会分别被标记为“timed out”或“failed”,并移动到下一个“on fail 节点”。如果获得批准,则会采用“on success”路径。如果您尝试在 API 中 POST 到已经批准、拒绝或超时的节点,则会出现错误消息,通知您此操作是多余的,且不会再执行任何步骤。

以下显示了在批准工作流中允许的各种权限级别:

_images/wf-node-approval-rbac.png

19.7.1.2. 节点构建场景

您可以点击父节点上的 add node 按钮添加同级节点:

_images/wf-editor-create-sibling-node.png

您可以在节点间插入另一个节点,方法是将鼠标悬停在连接这两个节点的直线上,直到 add node 出现。点击 add node 在两个节点间自动插入节点。

_images/wf-editor-insert-node-template.png

要添加一个根节点来描述分割场景,请再次点击 start 按钮:

_images/wf-editor-create-new-add-template-split.png

在您要创建分割场景的任意节点处,将鼠标悬停在分割场景的起始节点上并点击 add node。这实质上会从同一父节点添加多个节点,创建同级节点:

_images/wf-editor-create-siblings.png

注解

添加新节点时,PROMPT 按钮也会应用于工作流模板。工作流模板将提示设置清单和问卷调查。

如果您要撤消最后一个插入的节点,请点击另一个节点,而无需从右窗格中进行选择。或者,点击右窗格中的 Cancel

下面是一个工作流示例,它包含由一个作业模板启动的所有三种类型的作业,如果运行失败,继续执行项目同步作业,而无论该作业是失败还是成功,都继续执行清单同步作业。

_images/wf-editor-create-new-add-template-example.png

请参考窗口顶部的图例来识别与图形描述相关的符号和颜色的含义。

注解

在带有一组具有不同边缘类型的同级节点的工作流中,如果您删除了附加有后续节点的节点,则附加节点会自动加入同级节点组,并保留其边缘类型:

_images/wf-node-delete-scenario.png

您可以通过以下方法修改节点:

  • 如果您要编辑节点,请点击相关节点。右窗格显示当前的选择。进行更改并点击 Select 将它们应用到图形视图。

  • 要编辑现有链接的边缘类型(success/failure/always),请点击相关链接。右窗格显示当前选择。进行更改并点击 Save 将它们应用到图形视图。

_images/wf-editor-wizard-edit-link.png
  • 要将新链接从一个节点添加到另外一个节点,请点击每个节点上出现的链接 edit link 图标。此操作会突出显示可以链接到的节点。这些可用的选项由虚线表示。无效的选项由灰显框(节点)表示,否则会产生无效的链接。以下示例显示了 Demo Project 作为 e2e-ec20de52-project 可能链接的选项,如箭头所示:

_images/wf-node-link-scenario.png
  • 要删除链接,点击链接并点击 Unlink 按钮。

_images/wf-editor-wizard-unlink.png

只有当目标节点或子节点有多个父节点时,此按钮才会出现在右侧面板中。所有节点始终都必须链接到至少一个其他节点,因此您必须在删除旧链接前创建一个新链接。

点击设置按钮 (settings) 对视图进行缩放、平移或位置调整。或者,您可以拖动工作流图来调整它在屏幕上的位置,或使用鼠标滚轮来缩放。

19.8. 启动工作流模板

通过以下任一方法启动工作流模板:

  • templates-icon 导航链接或在工作流模板详情视图中访问工作流模板列表,滚动到底部以从模板列表中访问 launch 按钮。

_images/wf-templates-wf-template-launch.png
  • 在要启动的作业模板的作业模板视图中,点击 Launch

除了作业模板和问卷调查中设置的额外变量之外,Tower 还会在启动时自动添加为作业模板添加的相同变量。此外,Tower 会自动将 Web 浏览器重定向到此作业的 Jobs Details 页面,显示进度和结果。

_images/wf-launch-details-page-example.png

与工作流上的批准相关的事件显示在活动流 (activity-stream) 中,包含有关批准请求的详细信息。

_images/wf-activity-stream-events.png

19.9. 复制工作流模板

Ansible Tower 提供了复制工作流模板的功能。选择复制工作流模板时,**不会**复制任何关联的计划、通知或权限。计划和通知必须由创建工作流模板副本的用户或管理员重新创建。将为复制工作流模板的用户授予管理员权限,但不会将任何权限分配(复制)到工作流模板。

  1. Templates 导航链接 (templates-icon) 或在工作流作业模板详情视图中访问您要复制的工作流模板,滚动到底部以从模板列表中访问它。

Wf templates - newly added wf template

  1. 点击 copy 按钮。

此时会打开一个新模板,带有作为复制来源的模板的名称和一个时间戳。

_images/wf-list-view-copy-example.png

选择复制的模板,然后将 Name 字段的内容替换为新名称,并提供或者修改其他字段中的条目以完成此模板。

  1. 完成后请点击 Save

注解

如果资源具有您没有正确权限级别的相关资源,则您无法复制该资源,比如项目使用了当前用户仅具有 Read 访问权限的凭证。但是,对于工作流模板,如果其任何节点使用了未经授权的作业模板、清单或凭证,则仍可复制工作流模板。但是,在复制的工作流模板中,工作流模板节点中的相应字段将缺失。

19.10. 额外变量

注解

只有在以下条件之一被满足时,传递给作业启动 API 的 extra_vars 才有效:

  • 它们与启用的问卷调查(survey)中的变量对应

  • ask_variables_on_launch 被设为 True

当您传递问卷调查变量时,它们作为 Tower 中的额外变量 (extra_vars) 传递。这可能很棘手,因为将额外变量传递给工作流模板(就像对问卷调查的操作一样)可能会覆盖从清单和项目传递的其他变量。

例如,假设您为清单定义了一个变量 debug = true。在工作流模板问卷调查中完全有可能覆盖 debug = true 这个变量。

为确保不覆盖您需要传递的变量,请通过在问卷调查中重新定义变量来确保将其包括在内。请记住,可以在清单、组和主机级别定义额外的变量。

下表记录了 Ansible Tower 中的变量优先级的行为(层次结构)与 Ansible 中的变量优先级比较情况。

Ansible Tower 变量优先级层次结构(最后列出的优先)

_images/Architecture-Tower_Variable_Precedence_Hierarchy-Workflows.png