20. 作业模板

一个作业模板是运行 Ansible 作业的定义和参数集。作业模板可用于多次执行相同的作业。作业模板还有助于重用 Ansible 剧本内容以及团队之间的协作。

**模板** 菜单打开一个当前可用作业模板的列表。默认视图处于折叠（紧凑）状态，显示模板名称、模板类型以及使用该模板运行的最后一个作业的时间戳。您可以单击**展开**（每个条目旁边的箭头）以展开以查看更多信息。此列表按名称按字母顺序排序，但您可以按其他条件排序，或按模板的各种字段和属性进行搜索。

Job templates - home with example job template

在此屏幕上，您可以启动（）、编辑（）和复制（）作业模板。要删除作业模板，您必须选择一个或多个模板，然后单击**删除**按钮。在删除作业模板之前，请确保它未在工作流作业模板中使用。

注意

如果删除其他工作项使用的项目，则会打开一条消息，列出受删除影响的项目，并提示您确认删除。某些屏幕将包含无效或先前已删除的项目，因此它们将无法运行。以下是一个此类消息的示例

注意

作业模板可用于构建工作流模板。对于在它们旁边显示工作流可视化器（）图标的模板，是工作流模板。单击它允许您以图形方式构建工作流。作业模板中的许多参数允许您启用**启动时提示**，可以在工作流级别修改，并且不会影响在作业模板级别分配的值。有关说明，请参阅工作流可视化器部分。

20.1. 创建作业模板

要创建一个新的作业模板

单击**添加**按钮，然后从菜单列表中选择**作业模板**。
将适当的详细信息输入以下字段

注意

如果某个字段已选中**启动时提示**复选框，则启动作业将在启动时提示您输入该字段的值。大多数提示值将覆盖作业模板中设置的任何值；例外情况如下所述。

字段	选项	启动时提示
名称	输入作业的名称。	N/A
描述	根据需要输入任意描述（可选）。	N/A
作业类型	选择作业类型运行：启动时执行剧本，在选定的主机上运行 Ansible 任务。检查：对剧本执行“试运行”，并报告将在不实际执行更改的情况下进行的更改。不支持检查模式的任务将被跳过，并且不会报告潜在的更改。有关作业类型的更多信息，请参阅 Ansible 文档的剧本执行部分。	是
清单	从当前登录用户可用的清单中选择要与此作业模板一起使用的清单。系统管理员必须授予您或您的团队权限才能在作业模板中使用某些清单。	是。清单提示将显示为后续提示窗口中的一个单独步骤。
项目	从当前登录用户可用的项目中选择要与此作业模板一起使用的项目。	N/A
SCM 分支	仅当您选择允许分支覆盖的项目时，此字段才会出现。指定要用于作业运行的覆盖分支。如果留空，则使用项目中指定的 SCM 分支（或提交哈希或标签）。有关更多详细信息，请参阅作业分支覆盖。	是
执行环境	选择要用于运行此作业的容器镜像。必须先选择一个项目，然后才能选择执行环境。	是。执行环境提示将显示为后续提示窗口中的一个单独步骤。
剧本	从可用的剧本中选择要与此作业模板一起启动的剧本。此字段会自动填充选定项目项目基本路径中找到的剧本的名称。或者，如果您未列出剧本名称，则可以输入剧本名称，例如您要用于运行该剧本的文件的名称（如 `foo.yml`）。如果输入的文件名无效，则模板将显示错误或导致作业失败。	N/A
凭据	单击按钮以打开一个单独的窗口。从可用选项中选择要与此作业模板一起使用的凭据。如果列表很长，请使用下拉菜单列表按凭据类型进行筛选。某些凭据类型未列出，因为它们不适用于某些作业模板。	如果选中，则在启动具有默认凭据的作业模板并提供另一个凭据时，如果类型相同，则将替换默认凭据。此类消息的示例 Job Template default credentials must be replaced with one of the same type. Please select a credential for the following types in order to proceed: Machine. 或者，您可以根据需要添加更多凭据。凭据提示将显示为后续提示窗口中的一个单独步骤。
标签	可选地提供描述此作业模板的标签，例如“dev”或“test”。标签可用于对作业模板和已完成的作业进行分组和筛选显示。标签在添加到作业模板时创建。标签使用作业模板中提供的项目关联到单个组织。如果组织成员具有编辑权限（例如管理员角色），则可以在作业模板上创建标签。保存作业模板后，标签将显示在“展开”视图中的作业模板概述中。单击标签旁边的（）以将其删除。删除标签后，它将不再与此特定作业或作业模板关联，但它将保留与引用它的任何其他作业的关联。作业在启动时从作业模板继承标签。如果从作业模板中删除标签，它也会从作业中删除。	如果选中，即使提供了默认值，在启动时也需要提示您根据需要提供其他标签。您将无法删除现有标签 - 单击（）仅删除新添加的标签，而不是现有的默认标签。
变量	将额外的命令行变量传递给剧本。这是 ansible-playbook 的“-e”或“–extra-vars”命令行参数，在 Ansible 文档的运行时定义变量中有说明。使用 YAML 或 JSON 提供键/值对。这些变量具有最高优先级，并覆盖在其他地方指定的其他变量。一个示例值可能是 git_branch: production release_version: 1.5	是的。如果您希望能够在计划中指定`extra_vars`，则必须在作业模板的变量上选择启动时提示，或在作业模板上启用调查，然后这些已回答的调查问题将变为`extra_vars`。
并行进程数	在执行剧本时要使用的并行或同时进程数。值为零使用 Ansible 默认设置，即 5 个并行进程，除非在`/etc/ansible/ansible.cfg`中被覆盖。	是
限制	一个主机模式，用于进一步限制由剧本管理或影响的主机列表。多个模式可以用冒号 (`:`) 分隔。与核心 Ansible 一样，`a:b` 表示“在组 a 或 b 中”，`a:b:&c` 表示“在 a 或 b 中，但必须在 c 中”，`a:!b` 表示“在 a 中，并且绝对不在 b 中”。有关更多信息和示例，请参阅 Ansible 文档中的模式。	是
详细程度	控制 Ansible 在剧本执行期间产生的输出级别。从普通到各种详细或调试设置中选择详细程度。这仅出现在“详细信息”报告视图中。详细日志记录包括所有命令的输出。调试日志记录非常详细，包括有关 SSH 操作的信息，这些信息在某些支持实例中可能很有用。大多数用户不需要查看调试模式输出。警告详细程度 5 会导致 AWX 在作业运行时严重阻塞，这可能会延迟报告作业已完成（即使已完成）并可能导致浏览器选项卡锁定。	是
作业切片	指定您希望此作业模板运行的切片数。每个切片将对清单的一部分运行相同的任务。有关作业切片的更多信息，请参阅作业切片。	是
超时	允许您指定作业在取消之前可以运行的时间长度（以秒为单位）。设置超时值的一些注意事项在设置中定义了一个全局超时，默认为 0，表示没有超时。作业模板上的负超时 (<0) 是作业的真正“无超时”。作业模板上的 0 超时将作业默认为全局超时（默认情况下为无超时）。正超时为该作业模板设置超时。	是
显示更改	允许您查看 Ansible 任务所做的更改。	是
实例组	选择实例组与该作业模板关联。如果列表很长，请使用缩小选项范围。请注意，作业模板实例组有助于作业调度标准，请参阅作业运行时行为和控制作业运行的位置以获取规则。系统管理员必须授予您或您的团队权限才能在作业模板中使用实例组。使用容器组需要管理员权限。	是的。如果选中，则按优先级顺序提供作业的首选实例组。如果第一个组已满负荷，则将考虑列表中的后续组，直到找到一个有容量的组，然后选择该组来运行作业。如果您提示输入实例组，则您输入的内容将替换正常的实例组层次结构并覆盖所有组织和清单的实例组。实例组提示将在后续提示窗口中显示为其自身步骤。
作业标签	开始键入并选择创建 x下拉菜单以指定应执行剧本的哪些部分。有关更多信息和示例，请参阅 Ansible 文档中的标签。	是
跳过标签	开始键入并选择创建 x下拉菜单以指定要跳过的特定任务或剧本的一部分。有关更多信息和示例，请参阅 Ansible 文档中的标签。	是

选项：如有必要，指定启动此模板的选项。

权限提升：如果选中，则启用此剧本以管理员身份运行。这等效于将--become选项传递给ansible-playbook命令。

供应回调：如果选中，则启用主机通过 REST API 回调到 AWX 并调用从此作业模板启动作业。有关其他信息，请参阅供应回调。

启用 Webhook：打开与预定义的 SCM 系统 Web 服务交互的功能，该服务用于启动作业模板。当前支持的 SCM 系统是 GitHub 和 GitLab。

如果启用 Webhook，则会显示其他字段，提示您输入其他信息

Webhook 服务：选择要监听来自哪个服务的 Webhook。

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

Webhook 密钥：生成的共享密钥，Webhook 服务将使用该密钥对发送到 AWX 的有效负载进行签名。必须在 Webhook 服务的设置中配置此密钥，以便 AWX 接受来自此服务的 Webhook。

Webhook 凭据：可选地，提供 GitHub 或 GitLab 个人访问令牌 (PAT) 作为凭据，用于将状态更新发送回 Webhook 服务。在您选择它之前，必须存在凭据。请参阅凭据类型以创建一个。

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

并发作业：如果选中，则允许队列中的作业同时运行，前提是它们彼此不依赖。如果您想同时运行作业切片，请选中此框。有关其他信息，请参阅AWX 容量确定和作业影响。

启用事实存储：选中后，AWX 将存储与正在运行的作业相关的清单中所有主机的收集到的事实。

防止实例组回退：选中此选项以仅允许上面实例组字段中列出的实例组执行作业。如果未选中，则将根据控制作业运行的位置中描述的层次结构使用执行池中的所有可用实例。单击图标以获取更多信息。

Job templates - create new job template

完成作业模板详细信息的配置后，单击保存。

保存模板不会退出作业模板页面，而是会前进到“作业模板详细信息”选项卡以供查看。保存模板后，您可以单击启动以启动作业，或单击编辑以添加或更改模板的属性，例如权限、通知、查看已完成的作业和添加调查（如果作业类型不是扫描）。您必须先保存模板才能启动，否则启动按钮将保持灰色显示。

当新创建的模板出现在“模板”列表视图中时，您可以验证模板是否已保存。

20.2. 添加权限

在访问选项卡中，单击添加按钮。
选择要添加的用户或团队，然后单击下一步
通过单击名称旁边的复选框选择列表中的一个或多个用户或团队，将它们添加为成员，然后单击下一步。

../_images/organizations-add-users-for-example-organization.png

在此示例中，已选择两个用户进行添加。

选择您希望所选用户或团队具有的角色。请务必向下滚动以获取完整的角色列表。不同的资源有不同的可用选项。

单击保存按钮以将角色应用于所选用户或团队，并将它们添加为成员。

“添加用户/团队”窗口关闭，以显示为每个用户和团队分配的更新后的角色。

要删除特定用户的角色，请单击其资源旁边的取消关联 (x) 按钮。

这将启动一个确认对话框，要求您确认取消关联。

../_images/permissions-disassociate-confirm.png

20.3. 使用通知

单击通知选项卡，您可以查看您已设置的任何通知集成及其状态（如果它们已运行）。

Job templates - completed notifications view

使用切换按钮启用或禁用要与您的特定模板一起使用的通知。有关更多详细信息，请参阅启用和禁用通知。

如果尚未设置任何通知，请单击添加按钮以创建新的通知。有关配置各种通知类型和扩展消息传递的更多详细信息，请参阅通知类型。

20.4. 查看已完成的作业

已完成的作业选项卡提供已运行的作业模板列表。单击展开以查看每个作业的详细信息，包括其状态、ID 和名称；作业类型、开始和完成时间、谁启动了作业；以及使用了哪些模板、清单、项目和凭据。您可以使用任何这些条件过滤已完成的作业列表。

在此列表中显示的切片作业将相应标记，并显示已运行的切片作业数量

20.5. 调度

从计划选项卡访问特定作业模板的计划。

Job Templates - schedule launch

20.5.1. 安排作业模板

要安排作业模板运行，请单击计划选项卡。

如果已设置计划；查看、编辑或启用/禁用您的计划首选项。
如果尚未设置计划，请参阅计划以获取更多信息。

如果为凭据字段选择了启动时提示，并且您创建或编辑作业模板的计划信息，则计划表单底部会显示一个提示按钮。在保存之前，您将无法在“提示”对话框中删除默认机器凭据，而无需将其替换为其他机器凭据。以下是此类消息的示例

注意

为了能够在计划任务中设置extra_vars，您必须在作业模板的**变量**中选择**启动时提示**，或在作业模板上配置并启用调查，然后这些已回答的调查问题将成为extra_vars。

20.6. 调查

运行或检查类型的作业将在作业模板创建或编辑屏幕中提供一种设置调查的方式。调查为剧本设置额外的变量，类似于“提示输入额外变量”的功能，但以用户友好的问答方式进行。调查还允许验证用户输入。点击**调查**选项卡创建调查。

调查的用例很多。例如，如果运维人员希望为开发人员提供一个“推送到暂存环境”按钮，他们可以在没有高级 Ansible 知识的情况下运行。启动时，此任务可能会提示用户回答以下问题：“我们应该发布哪个标签？”

可以提出多种类型的问题，包括多选题。

20.6.1. 创建调查

创建调查

点击**调查**选项卡，然后点击**添加**按钮。
一个调查可以包含任意数量的问题。对于每个问题，请输入以下信息

问题：要询问用户的问题
描述：(可选) 对向用户提出的问题进行描述。
答案变量名：用于存储用户响应的 Ansible 变量名。这是剧本将使用的变量。变量名不能包含空格。
答案类型：从以下问题类型中选择。
- 文本：一行文本。您可以为此答案设置最小和最大长度（以字符为单位）。
- 文本区域：一个多行文本字段。您可以为此答案设置最小和最大长度（以字符为单位）。
- 密码：响应被视为敏感信息，就像实际密码一样。您可以为此答案设置最小和最大长度（以字符为单位）。
- 多选（单选）：选项列表，一次只能选择一个。在**多选选项**框中，每行输入一个选项。
- 多选（多选）：选项列表，可以同时选择任意数量的选项。在**多选选项**框中，每行输入一个选项。
- 整数：一个整数。您可以为此答案设置最小和最大长度（以字符为单位）。
- 浮点数：一个小数。您可以为此答案设置最小和最大长度（以字符为单位）。
必填：用户是否必须回答此问题。
最小长度和最大长度：指定答案是否需要一定的长度。
默认答案：问题的默认答案。此值在界面中预先填充，如果用户未提供答案，则使用此值。

输入完问题信息后，点击**保存**添加问题。

调查问题显示在调查列表中。对于任何问题，您可以点击编辑问题，或选中每个问题旁边的复选框并点击**删除**删除问题，或使用屏幕顶部的切换按钮启用或禁用调查提示。

Job templates - completed survey

如果您有多个调查问题，请使用**编辑顺序**按钮通过点击和拖动网格图标来重新排列问题的顺序。

要添加更多问题，请点击**添加**按钮添加其他问题。

20.6.2. 可选调查问题

调查问题上的**必填**设置决定了与之交互的用户是否可以选择回答此问题。

在后台，即使可选调查变量未填写，也可以在extra_vars中传递给剧本。

如果非文本变量（输入类型）被标记为可选，并且未填写，则不会将任何调查extra_var传递给剧本。
如果文本输入或文本区域输入被标记为可选，未填写，并且最小length > 0，则不会将任何调查extra_var传递给剧本。
如果文本输入或文本区域输入被标记为可选，未填写，并且最小length === 0，则该调查extra_var将传递给剧本，其值设置为空字符串（“”）。

20.7. 启动作业模板

AWX 的一个主要优势是能够一键式部署 Ansible 剧本。您可以轻松配置模板以存储您通常在命令行上传递给 ansible-playbook 的所有参数，不仅包括剧本，还包括清单、凭据、额外变量以及您可以在命令行上指定的全部选项和设置。

更简单的部署方式提高了一致性，因为每次运行剧本的方式都相同，并且允许您委派职责，即使不是 Ansible 专家也可以运行其他人编写的剧本。

可以通过以下任何一种方式启动作业模板

从左侧导航栏的**模板**菜单访问作业模板列表，或在作业模板详细信息视图中，滚动到底部以从模板列表中访问按钮。

Job templates - home with example job template - launch

在要启动的作业模板的作业模板详细信息视图中，点击**启动**。

作业可能需要其他信息才能运行。启动时可能会请求以下数据

已设置的凭据
任何参数都选择了Prompt on Launch选项
已设置为**询问**的密码或密码短语
如果已为作业模板配置了调查，则会显示调查
如果作业模板请求，则会显示额外变量

注意

如果作业具有用户提供的变量，则在重新启动时会尊重这些变量。如果用户未指定变量，则作业将使用作业模板中的默认值。作业不会按原样重新启动。它们将重新启动，并将用户提示重新应用于作业模板。

以下是一个作业启动示例，该示例提示输入作业标签，并运行在调查中创建的示例调查。

Job launch with prompt job tags

Job launch with prompt survey

注意

在一个选项卡上提供变量，然后返回到上一个选项卡，再继续到下一个选项卡，会导致需要在其余选项卡上重新提供变量。请确保按照提示出现的顺序填写选项卡，以避免这种情况。

除了作业模板和调查中设置的任何额外变量外，AWX 还会自动将以下变量添加到作业环境中。另请注意，awx_``* 变量由系统定义且不可覆盖。关于作业上下文的变量，例如 ``awx_job_template_name如果在extra_vars中设置，则不会受到影响。

awx_job_id：此作业运行的作业 ID
awx_job_launch_type：指示作业如何启动的描述
- 手动：作业由用户手动启动。
- 重新启动：作业通过重新启动启动。
- 回调：作业通过主机回调启动。
- 计划：作业从计划任务启动。
- 依赖：作业作为另一个作业的依赖项启动。
- 工作流：作业从工作流作业启动。
- 同步：作业从项目同步启动。
- scm：作业作为清单 SCM 同步创建。
awx_job_template_id：此作业运行使用的作业模板 ID
awx_job_template_name：此作业使用的作业模板名称
awx_execution_node：启动此作业的执行节点名称
awx_project_revision：此特定作业使用的源树的修订版标识符（它也与作业的字段scm_revision相同）
awx_project_scm_branch：作业模板使用的项目的配置的默认项目 SCM 分支
awx_job_scm_branch如果作业覆盖了 SCM 分支，则此处显示该值
awx_user_email：启动此作业的 AWX 用户的电子邮件。回调作业或计划作业中不提供此信息。
awx_user_first_name：启动此作业的 AWX 用户的姓。回调作业或计划作业中不提供此信息。
awx_user_id：启动此作业的 AWX 用户的用户 ID。回调作业或计划作业中不提供此信息。
awx_user_last_name：启动此作业的 AWX 用户的姓氏。回调或计划作业不可用此信息。
awx_user_name：启动此作业的 AWX 用户的用户名。回调或计划作业不可用此信息。
awx_schedule_id：如果适用，则为启动此作业的计划的 ID。
awx_schedule_name：如果适用，则为启动此作业的计划的名称。
awx_workflow_job_id：如果适用，则为启动此作业的工作流作业的 ID。
awx_workflow_job_name：如果适用，则为启动此作业的工作流作业的名称。请注意，这也与工作流作业模板相同。
awx_inventory_id：如果适用，则为此作业使用的清单的 ID。
awx_inventory_name：如果适用，则为此作业使用的清单的名称。

为了兼容性，所有变量也都会加上“awx”前缀，例如 awx_job_id。

启动后，AWX 会自动将 Web 浏览器重定向到“作业”选项卡下此作业的“作业状态”页面。

注意

您可以从列表视图中重新启动最近的作业，以在指定清单中的所有主机或仅失败的主机上重新运行。有关更多详细信息，请参阅《AWX 用户指南》中的作业。

当切片作业正在运行时，作业列表会显示工作流和作业切片，以及查看其详细信息的链接。

注意

您可以使用 API 中新添加的端点 /api/v2/bulk/job_launch 批量启动作业。此端点接受 JSON，您可以指定要启动的统一作业模板列表（例如作业模板、项目更新等）。用户必须具有启动所有作业的相应权限。要么所有作业都启动，要么返回一个错误，指示操作无法完成的原因。使用OPTIONS请求返回相关的模式。有关更多信息，请参阅《AWX API 指南》“参考”部分的批量端点。

20.8. 复制作业模板

如果您选择复制作业模板，则**不会**复制任何关联的计划、通知或权限。计划和通知必须由创建作业模板副本的用户或管理员重新创建。复制作业模板的用户将被授予管理员权限，但不会将任何权限分配（复制）给作业模板。

从左侧导航栏上的“模板”菜单访问作业模板列表，或者在“作业模板详细信息”视图中，滚动到底部以从模板列表中访问它。

Job templates - home with example job template

单击与您要复制的模板关联的按钮。

新的模板将显示在模板列表中，其名称为复制模板的名称和时间戳。

单击以打开新模板，然后单击“编辑”。
用新名称替换“名称”字段的内容，并在其他字段中提供或修改条目以完成此页面。
完成后，单击“保存”。

20.8.1. 事实扫描剧本

扫描作业剧本 scan_facts.yml 包含三个 fact scan modules 的调用 - 包、服务和文件，以及 Ansible 的标准事实收集。 scan_facts.yml 剧本文件如下所示

- hosts: all
  vars:
    scan_use_checksum: false
    scan_use_recursive: false
  tasks:
    - scan_packages:
    - scan_services:
    - scan_files:
        paths: '{{ scan_file_paths }}'
        get_checksum: '{{ scan_use_checksum }}'
        recursive: '{{ scan_use_recursive }}'
      when: scan_file_paths is defined

scan_files 事实模块是唯一接受参数的模块，通过扫描作业模板上的 extra_vars 传递。

scan_file_paths: '/tmp/'
scan_use_checksum: true
scan_use_recursive: true

scan_file_paths 参数可能有多个设置（例如 /tmp/ 或 /var/log）。
scan_use_checksum 和 scan_use_recursive 参数也可以设置为 false 或省略。省略与 false 设置相同。

扫描作业模板应启用 become 并使用 become 可能存在的凭据。您可以通过从“选项”菜单中选中“启用权限提升”来启用 become。

Job template with Privilege Escalation checked from the Options field.

20.8.2. `scan_facts.yml` 支持的操作系统

如果您使用 scan_facts.yml 剧本并使用事实缓存，请确保您的操作系统受支持

Red Hat Enterprise Linux 5、6 和 7
OEL 6 和 7
SLES 11 和 12
Debian 6、7、8
Fedora 22、23、24
Amazon Linux 2016.03
Windows Server 2008 及更高版本

请注意，某些操作系统可能需要进行初始配置才能能够运行 python 和/或访问扫描模块依赖的 python 包（例如 python-apt）。

20.8.3. 扫描前设置

以下是配置某些发行版以使其能够针对其运行扫描作业的剧本示例。

引导 Fedora（23、24）

---

- name: Get Fedora ready
 hosts: all
 sudo: yes
 gather_facts: no

 tasks:

 - name: install python-simplejson
   raw: sudo dnf -y update
   raw: sudo dnf -y install python-simplejson
   raw: sudo dnf -y install rpm-python

20.8.4. 自定义事实扫描

自定义事实扫描的剧本类似于上面事实扫描剧本的示例。例如，仅使用自定义 scan_foo Ansible 事实模块的剧本如下所示

scan_custom.yml:

- hosts: all
  gather_facts: false
  tasks:
    - scan_foo:

scan_foo.py:

def main():
    module = AnsibleModule(
        argument_spec = dict())

    foo = [
      {
        "hello": "world"
      },
      {
        "foo": "bar"
      }
    ]
    results = dict(ansible_facts=dict(foo=foo))
    module.exit_json(**results)

main()

要使用自定义事实模块，请确保它位于扫描作业模板中使用的 Ansible 项目的 /library/ 子目录中。此事实扫描模块非常简单，返回一组硬编码的事实

[
   {
     "hello": "world"
   },
   {
     "foo": "bar"
   }
 ]

有关更多信息，请参阅 Ansible 文档的创建信息或事实模块部分。

20.9. 事实缓存

AWX 可以通过 Ansible 事实缓存插件在每个主机基础上存储和检索事实。此行为可在每个作业模板基础上进行配置。事实缓存默认情况下处于关闭状态，但可以启用以服务与正在运行的作业相关的清单中所有主机的缓存请求。这允许您在使用 --limit 的作业模板时仍然可以访问主机事实的整个清单。可以通过“作业设置”菜单指定插件对每个主机实施的全局超时设置（以秒为单位）。

Jobs Settings window showing the location of the Per-Host Ansible Fact Cache Timeout parameter from the Edit Details screen.

启动使用事实缓存的作业（use_fact_cache=True）后，AWX 将存储与作业关联的清单中每个主机关联的所有 ansible_facts。与 AWX 一起提供的 Ansible 事实缓存插件将仅在启用了事实缓存的作业（use_fact_cache=True）上启用。

当启用事实缓存的作业（use_fact_cache=True）完成运行后，AWX 将恢复清单中所有主机的所有记录。任何更新时间晚于当前每个主机存储的事实的记录都将在数据库中更新。

新的和更改的事实将通过 AWX 的日志记录工具记录。具体来说，到 system_tracking 命名空间或记录器。日志记录有效负载将包括以下字段

host_name

inventory_id

ansible_facts

其中 ansible_facts 是 AWX 清单 inventory_id 中 host_name 的所有 Ansible 事实的字典。

注意

如果主机名包含正斜杠（/），则该主机的事实缓存将无法使用。如果您有一个包含 100 个主机且其中一个主机名称包含 / 的清单，则其中 99 个主机仍将收集事实。

20.9.1. 事实缓存的好处

事实缓存与运行事实收集相比节省了大量时间。如果您在作业中有一个针对一千个主机并进行分叉的剧本，则您很容易花费 10 分钟来收集所有这些主机的事实。但是，如果您定期运行作业，则第一次运行将缓存这些事实，并且下一次运行将仅从数据库中提取它们。这将针对大型清单（包括智能清单）的作业的运行时间缩短了巨大幅度。

注意

不要修改 ansible.cfg 文件以应用事实缓存。自定义事实缓存可能与 AWX 的事实缓存功能冲突。建议使用 AWX 附带的事实缓存模块。

您可以通过在“作业模板”窗口的“选项”字段中启用它来选择在作业中使用缓存的事实。

要清除事实，您需要运行 Ansible clear_facts 元任务。以下是用 Ansible clear_facts 元任务的剧本示例。

- hosts: all
  gather_facts: false
  tasks:
    - name: Clear gathered facts from all currently targeted hosts
      meta: clear_facts

您可以在以下位置找到事实缓存的 API 端点

http://<awx server name>/api/v2/hosts/x/ansible_facts

20.10. 利用云凭据

在同步相应的云清单时可以使用云凭据。云凭据也可以与作业模板关联，并包含在运行时环境中供剧本使用。当前支持的云凭据

20.10.1. OpenStack 

以下示例剧本调用了 nova_compute Ansible OpenStack 云模块，需要凭据才能执行有意义的操作，并且特别需要以下信息：auth_url、username、password 和 project_name。这些字段通过环境变量 OS_CLIENT_CONFIG_FILE 提供给剧本，该变量指向由 AWX 基于云凭据内容编写的 YAML 文件。此示例剧本将 YAML 文件加载到 Ansible 变量空间中。

OS_CLIENT_CONFIG_FILE 示例

clouds:
  devstack:
    auth:
      auth_url: http://devstack.yoursite.com:5000/v2.0/
      username: admin
      password: your_password_here
      project_name: demo

剧本示例

- hosts: all
  gather_facts: false
  vars:
    config_file: "{{ lookup('env', 'OS_CLIENT_CONFIG_FILE') }}"
    nova_tenant_name: demo
    nova_image_name: "cirros-0.3.2-x86_64-uec"
    nova_instance_name: autobot
    nova_instance_state: 'present'
    nova_flavor_name: m1.nano

    nova_group:
      group_name: antarctica
      instance_name: deceptacon
      instance_count: 3
  tasks:
    - debug: msg="{{ config_file }}"
    - stat: path="{{ config_file }}"
      register: st
    - include_vars: "{{ config_file }}"
      when: st.stat.exists and st.stat.isreg

    - name: "Print out clouds variable"
      debug: msg="{{ clouds|default('No clouds found') }}"

    - name: "Setting nova instance state to: {{ nova_instance_state }}"
      local_action:
        module: nova_compute
        login_username: "{{ clouds.devstack.auth.username }}"
        login_password: "{{ clouds.devstack.auth.password }}"

20.10.2. Amazon Web Services 

在剧本执行期间，Amazon Web Services 云凭据以以下环境变量的形式公开（在作业模板中，选择设置所需的云凭据）

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY

所有 AWS 模块在通过 AWX 运行时都会隐式使用这些凭据，而无需设置 aws_access_key_id 或 aws_secret_access_key 模块选项。

20.10.3. Google 

在剧本执行期间，Google 云凭据以以下环境变量的形式公开（在作业模板中，选择设置所需的云凭据）

GCE_EMAIL
GCE_PROJECT
GCE_CREDENTIALS_FILE_PATH

所有 Google 模块在通过 AWX 运行时都会隐式使用这些凭据，而无需设置 service_account_email、project_id 或 pem_file 模块选项。

20.10.4. Azure 

在剧本执行期间，Azure 云凭据以以下环境变量的形式公开（在作业模板中，选择设置所需的云凭据）

AZURE_SUBSCRIPTION_ID
AZURE_CERT_PATH

所有 Azure 模块在通过 AWX 运行时都会隐式使用这些凭据，而无需设置 subscription_id 或 management_cert_path 模块选项。

20.10.5. VMware 

在剧本执行期间，VMware 云凭据以以下环境变量的形式公开（在作业模板中，选择设置所需的云凭据）

VMWARE_USER
VMWARE_PASSWORD
VMWARE_HOST

以下示例剧本演示了如何使用这些凭据

- vsphere_guest:
    vcenter_hostname: "{{ lookup('env', 'VMWARE_HOST') }}"
    username: "{{ lookup('env', 'VMWARE_USER') }}"
    password: "{{ lookup('env', 'VMWARE_PASSWORD') }}"
    guest: newvm001
    from_template: yes
    template_src: linuxTemplate
    cluster: MainCluster
    resource_pool: "/Resources"
    vm_extra_config:
      folder: MyFolder

20.11. 预配回调

预配回调是 AWX 的一项功能，它允许主机自行发起剧本运行，而不是等待用户从 AWX UI 启动作业来管理主机。请注意，预配回调**仅**用于在调用主机上运行剧本。预配回调旨在用于云突发（即，需要客户端到服务器通信进行配置（例如传输授权密钥）的新实例），而不是对其他主机运行作业。这使得可以在另一个系统预配系统后自动配置系统（例如 AWS 自动扩展或像 kickstart 或 preseed 这样的操作系统预配系统），或者以编程方式启动作业而无需直接调用 AWX API。启动的作业模板仅针对请求预配的主机运行。

通常，这将通过 firstboot 类型的脚本或 cron 访问。

要启用回调，请选中作业模板中的“预配回调”复选框。这将显示此作业模板的**预配回调 URL**。

注意

如果您打算将 AWX 的预配回调功能与动态清单一起使用，则应为作业模板中使用的清单组设置“启动时更新”。

回调还需要主机配置密钥，以确保具有 URL 的外部主机无法请求配置。请为主机配置密钥提供自定义值。主机密钥可以在多个主机之间重复使用，以便对多个主机应用此作业模板。如果您希望控制能够请求配置的主机，则可以随时更改密钥。

要通过 REST 手动进行回调，请查看 UI 中的回调 URL，其格式如下

https://<AWX_SERVER_NAME>/api/v2/job_templates/7/callback/

此示例 URL 中的“7”是 AWX 中的作业模板 ID。

来自主机请求必须为 POST。以下是一个使用 curl 的示例（所有内容都在一行上）

curl -k -f -i -H 'Content-Type:application/json' -XPOST -d '{"host_config_key": "redhat"}' \
                 https://<AWX_SERVER_NAME>/api/v2/job_templates/7/callback/

请求的主机必须在您的清单中定义，回调才能成功。如果 AWX 无法通过名称或 IP 地址在您定义的某个清单中找到主机，则会拒绝请求。以这种方式运行作业模板时，自行发起剧本运行的主机必须在清单中。如果清单中缺少主机，则作业模板将失败，并显示“无主机匹配”类型的错误消息。

注意

如果您的主机不在清单中，并且为清单组设置了启动时更新，则 AWX 会尝试在运行回调之前更新基于云的清单源。

成功请求会在“作业”选项卡上生成一个条目，您可以在其中查看结果和历史记录。

虽然可以通过 REST 访问回调，但建议使用回调的方法是使用 AWX 附带的示例脚本之一 - /usr/share/awx/request_awx_configuration.sh（Linux/UNIX）或 /usr/share/awx/request_awx_configuration.ps1（Windows）。如以下所示，通过传递 -h 标志，可以在文件源代码中找到使用方法

./request_awx_configuration.sh -h
Usage: ./request_awx_configuration.sh <options>

Request server configuration from AWX.

OPTIONS:
 -h      Show this message
 -s      AWX server (e.g. https://ac.example.com) (required)
 -k      Allow insecure SSL connections and transfers
 -c      Host config key (required)
 -t      Job template ID (required)
 -e      Extra variables

此脚本具有一定的智能，它知道如何重试命令，因此它是比简单的 curl 请求更可靠地使用回调的方法。按照编写方式，脚本每分钟重试一次，最多重试十分钟。

注意

请注意，这是一个示例脚本。如果您需要在检测故障场景时获得更多动态行为，则应编辑此脚本，因为任何非 200 错误代码可能不是需要重试的瞬态错误。

您最有可能将回调与 AWX 中的动态清单一起使用，例如从支持的云提供商之一提取云清单。在这些情况下，除了设置“启动时更新”外，还要确保为清单源配置清单缓存超时，以避免对云 API 端点进行过度访问。由于 request_awx_configuration.sh 脚本每分钟轮询一次，最多轮询十分钟，因此建议的清单失效时间（在清单源本身配置）为一到两分钟。

虽然我们建议不要从 cron 作业运行 request_awx_configuration.sh 脚本，但建议的 cron 间隔可能是每 30 分钟一次。可以轻松地通过在 AWX 中安排来处理重复配置，因此大多数用户使用回调的主要目的是启用一个基本镜像，该镜像在上线后将引导到最新配置中。为此，在首次启动时运行是更好的做法。首次启动脚本只是简单的初始化脚本，通常会自行删除，因此您将设置一个初始化脚本，该脚本调用 request_awx_configuration.sh 脚本的副本，并将其转换为自动扩展镜像。

20.11.1. 将额外变量传递给预配回调

就像您可以在常规作业模板中传递 extra_vars 一样，您也可以将它们传递给预配回调。要传递 extra_vars，发送的数据必须作为应用程序/json（作为内容类型）成为 POST 请求主体的一部分。在添加您自己的 extra_vars 以进行传递时，请使用以下 JSON 格式作为示例

'{"extra_vars": {"variable1":"value1","variable2":"value2",...}}'

您还可以使用 curl 将额外变量传递给作业模板调用，例如以下示例所示

.. code-block:: bash

root@localhost:~$ curl -f -H ‘Content-Type: application/json’ -XPOST
-d ‘{“host_config_key”: “redhat”, “extra_vars”: “{"foo": "bar"}”}’ https://<AWX_SERVER_NAME>/api/v2/job_templates/7/callback

有关更多信息，请参阅使用 Curl 启动作业。

20.12. 额外变量

注意

仅当以下条件之一为真时，传递给作业启动 API 的 extra_vars 才会被接受

它们对应于已启用的调查中的变量
ask_variables_on_launch 设置为 True

当您传递调查变量时，它们会作为额外变量（extra_vars）在 AWX 中传递。这可能很棘手，因为将额外变量传递给作业模板（如您对调查所做的那样）可能会覆盖从清单和项目传递的其他变量。

默认情况下，extra_vars 被标记为 !unsafe，除非您在作业模板的“额外变量”部分指定它们。这些变量是可信的，因为只有拥有足够权限添加或编辑作业模板的用户才能添加它们。例如，嵌套变量在作为提示输入时不会展开，因为 Jinja 括号被视为字符串。有关不安全变量的更多信息，请参阅不安全或原始字符串。

例如，假设您为清单定义了一个变量，用于 debug = true。完全有可能在作业模板调查中覆盖此变量 debug = true。

为了确保您需要传递的变量不会被覆盖，请确保通过在调查中重新定义它们来包含它们。请记住，可以在清单、组和主机级别定义额外变量。

如果指定 ALLOW_JINJA_IN_EXTRA_VARS 参数，请参阅《AWX 管理指南》中的AWX 提示和技巧部分，以在 AWX UI 的“作业设置”屏幕中进行配置。

注意

作业模板额外变量字典与调查变量合并。

以下是 YAML 和 JSON 格式的 extra_vars 的一些简化示例

YAML 格式的配置

launch_to_orbit: true
satellites:
  - sputnik
  - explorer
  - satcom

JSON 格式的配置

{
  "launch_to_orbit": true,
  "satellites": ["sputnik", "explorer", "satcom"]
}

下表记录了 AWX 中变量优先级（层次结构）的行为，以及它与 Ansible 中变量优先级的比较。

AWX 变量优先级层次结构（最后列出的优先级最高）

20.12.1. 重新启动作业模板

与其手动重新启动作业，不如通过将 launch_type 设置为 relaunch 来表示重新启动。重新启动行为与启动行为不同，因为它**不**继承 extra_vars。

作业重新启动不会经过继承逻辑。它使用与正在重新启动的作业计算出的相同的 extra_vars。

例如，假设您启动了一个没有 extra_vars 的作业模板，这将导致创建一个名为**j1**的作业。接下来，假设您编辑作业模板并添加一些 extra_vars（例如添加 "{ "hello": "world" }"）。

重新启动**j1**将导致创建**j2**，但由于没有继承逻辑并且**j1**没有 extra_vars，因此**j2**将没有任何 extra_vars。

继续此示例，如果您在创建**j1**之后使用您添加的 extra_vars 启动作业模板，则创建的重新启动作业（**j3**）将包含 extra_vars。并且重新启动**j3**将导致创建**j4**，它也将包含 extra_vars。