Documentation

20. 作业模板

job template 是用于运行 Ansible 作业的定义和参数集。作业模板对于多次执行同一作业很有用。作业模板还可促进 Ansible playbook 内容的重复使用和团队之间的协作。

Templates 菜单会打开当前可用的作业模板列表。默认视图为折叠状态 (Compact),显示模板名称、模板类型和使用该模板运行的最后一个作业的时间戳,但您可以点击 **Expanded**(每个项旁边的箭头) 查看更多信息。该列表按名称字母顺序排序,但您可以按照其他条件排序,或者根据模板的不同字段和属性进行搜索。

Job templates - home with example job template

在这个屏幕中,您可以启动(launch)、编辑(edit)和复制(copy)作业模板。要删除作业模板,您必须选择一个或多个模板并点击 Delete 按钮。删除作业模板前,请确定在工作流作业模板中使用。

注解

如果删除了由其他工作项目使用的项,则会打开一条信息,列出会受到删除影响的项,并提示您确认删除。一些界面会包括无效的或以前已被删除的项,因此它们将无法运行。以下是这类信息的一个示例:

_images/warning-deletion-dependencies.png

注解

作业模板可以用来构建工作流模板。旁边显示工作流可视化工具 (wf-viz-icon) 图标的模板为工作流模板。点击此图标可通过图形方式构建工作流。作业模板中的许多参数允许您启用 Prompt on Launch,这些参数可在工作流级别进行修改,且不会影响在作业模板级别分配的值。如需了解相关说明,请参阅 工作流可视化工具 部分。

20.1. 创建作业模板

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

  1. Add 按钮,然后从菜单列表中选择 Job Template

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

注解

If a field has the Prompt on launch checkbox selected, launching the job will prompt you for the value for that field upon launch. Most prompted values will override any values set in the job template; exceptions are noted below.

Field

Options

Prompt on Launch

Name

Enter a name for the job.

N/A

Description

Enter an arbitrary description as appropriate (optional).

N/A

Job Type

Choose a job type:
  • Run:启动时执行 playbook,在所选主机上运行 Ansible 任务。

  • Check:执行 playbook 的“dry run”并报告将要进行的更改,而无需实际进行更改。不支持检查模式的任务将被跳过,且不会报告潜在的更改。

More information on job types can be found in the Playbooks: Special Topics section of the Ansible documentation.

Yes

Inventory

Choose the inventory to be used with this job template from the inventories available to the currently logged in user.

Yes. Inventory prompts will show up as its own step in a subsequent prompt window.

Project

Choose the project to be used with this job template from the projects available to the currently logged in user.

N/A

SCM Branch

This field is only present if you chose a project that allows branch override. Specify the overriding branch to use in your job run. If left blank, the specified SCM branch (or commit hash or tag) from the project is used. For more detail, see job branch overriding.

Yes

Execution Environment

Select the container image to be used to run this job. A project must be selected before you can select an execution environment.

Yes. Execution environment prompts will show up as its own step in a subsequent prompt window.

Playbook

Choose the playbook to be launched with this job template from the available playbooks. This field automatically populates with the names of the playbooks found in the project base path for the selected project. Alternatively, you can enter the name of the playbook if it is not listed, such as the name of a file (like foo.yml) you want to use to run with that playbook. If you enter a filename that is not valid, the template will display an error, or cause the job to fail.

N/A

Credentials

Click the search button to open a separate window. Choose the credential from the available options to be used with this job template. Use the drop-down menu list to filter by credential type if the list is extensive. Some credential types are not listed because they do not apply to certain job templates.

  • If selected, upon launching a job template that has a default credential and supplying another credential will replace the default credential if it is the same type. Example of such a message:

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.
  • Alternatively, you can add more credentials as you see fit.

  • Credential prompts will show up as its own step in a subsequent prompt window.

Labels

  • Optionally supply labels that describe this job template, such as "dev" or "test". Labels can be used to group and filter job templates and completed jobs in the display.

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

  • 保存作业模板后,标签会显示在 Expanded 视图的作业模板概述中。

  • Click the (x) beside a label to remove it. When a label is removed, it is no longer associated with that particular Job or Job Template, but it will remain associated with any other jobs that reference it.

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

  • If selected, even if a default value is supplied, you will be prompted upon launch to supply additional labels if needed.

  • You will not be able to delete existing labels - clicking (x-circle) only removes the newly added labels, not existing default labels.

Variables

  • Pass extra command line variables to the playbook. This is the "-e" or "--extra-vars" command line parameter for ansible-playbook that is documented in the Ansible documentation at Passing Variables on the Command Line.

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

git_branch: production
release_version: 1.5

Yes. If you want to be able to specify extra_vars on a schedule, you must select Prompt on Launch for Variables on the job template, or a enable a survey on the job template, then those answered survey questions become extra_vars.

Forks

The number of parallel or simultaneous processes to use while executing the playbook. A value of zero uses the Ansible default setting, which is 5 parallel processes unless overridden in /etc/ansible/ansible.cfg.

Yes

Limit

A host pattern to further constrain the list of hosts managed or affected by the playbook. Multiple patterns can be separated by colons (:). As with core Ansible, a:b means "in group a or b", a:b:&c means "in a or b but must be in c", and a:!b means "in a, and definitely not in b". For more information and examples refer to Patterns in the Ansible documentation.

Yes

Verbosity

Control the level of output Ansible produces as the playbook executes. Choose the verbosity from Normal to various Verbose or Debug settings. This only appears in the "details" report view. Verbose logging includes the output of all commands. Debug logging is exceedingly verbose and includes information on SSH operations that can be useful in certain support instances. Most users do not need to see debug mode output.

警告

详细程度 5 会导致 automation controller 在作业运行时大量阻断,这可能会延迟报告作业已完成(即使它已经完成),并可能导致浏览器标签页锁定。

Yes

Job Slicing

Specify the number of slices you want this job template to run. Each slice will run the same tasks against a portion of the inventory. For more information about job slices, see 任务分片.

Yes

Timeout

Allows you to specify the length of time (in seconds) that the job may run before it is canceled. Some caveats for setting the timeout value:
  • There is a global timeout defined in the settings which defaults to 0, indicating no timeout.

  • A negative timeout (<0) on a job template is a true "no timeout" on the job.

  • A timeout of 0 on a job template defaults the job to the global timeout (which is no timeout by default).

  • A positive timeout sets the timeout for that job template.

Yes

Show Changes

Allows you to see the changes made by Ansible tasks.

Yes

Instance Groups

Choose 实例组 to associate with this job template. If the list is extensive, use the search to narrow the options. Note, job template instance groups contribute to the job scheduling criteria, see 作业运行时行为 and 控制作业运行位置 for rules.

  • Yes. If selected, you are providing the jobs preferred instance groups in order of preference. If the first group is out of capacity, subsequent groups in the list will be considered until one with capacity is available, at which point that will be selected to run the job.

  • If you prompt for an instance group, what you enter replaces the normal instance group hierarchy and overrides all of the organizations' and inventories' instance groups.

  • Instance Groups prompts will show up as its own step in a subsequent prompt window.

Job Tags

Begin typing and selecting the Create x drop-down to specify which parts of the playbook should be executed. For more information and examples refer to Tags in the Ansible documentation.

Yes

Skip Tags

Begin typing and selecting the Create x drop-down to specify certain tasks or parts of the playbook to skip. For more information and examples refer to Tags in the Ansible documentation.

Yes

  1. Options:根据需要指定启动此模板的选项。

  • Privilege Escalation:如果选择此项,代表以管理员身份运行此 playbook。这等同于将 --become 选项传递给 ansible-playbook 命令。

  • Provisioning Callbacks:如果选择此项,代表启用主机通过 REST API 回调至 automation controller,并调用从该作业模板启动作业。如需了解更多信息,请参阅 置备回调

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

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

_images/job-templates-options-webhooks.png
  • Webhook Service:从中选择侦听 Webhook 的服务

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

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

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

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

  • Concurrent Jobs:如果选择,代表如果队列中的作业不相互依赖,则允许它们同时运行。如果您想同时运行作业分片,请选中此复选框。如需了解更多信息,请参阅 自动化控制器容量确定和作业影响

  • Enable Fact Storage:当选中时,automation controller 将收集到与作业运行相关的清单中所有主机的事实。

Job templates - create new job template

  1. 当您完成作业模板详情配置后,请点击 Save

保存该模板不会退出作业模板页面,而是进入到作业模板详情标签页用于查看信息。在保存模板后,您可以点击 Launch 来启动作业,或者继续添加更多有关模板的属性,如权限、通知,查看已完成的作业,以及添加一个调查问卷(如果作业类型不是扫描)。在启动之前,您必须先保存模板,否则 Launch 按钮将一直灰显。

_images/job-templates-job-template-details.png

当新创建的模板出现在模板列表中时,代表模板已保存。

20.2. 添加权限

  1. Access 选项卡中,点 Add 按钮。

  2. 选择要添加的用户或团队并点 Next

  3. 点名称旁边的复选框从列表中选择一个或多个用户或团队,将它们添加为成员并点 Next

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

在这个示例中,选择了两个用户来添加。

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

_images/organizations-add-users-roles.png
  1. Save 按钮将角色应用到所选用户或团队,并将它们添加为成员。

将关闭 Add Users/Teams 窗口,以显示为每个用户和团队分配的更新角色。

Permissions tab with Role Assignments

若要删除特定用户的角色,可单击其资源旁边的解除关联(x)按钮。

_images/permissions-disassociate.png

这会出现确认对话框,要求您确认解除关联。

_images/permissions-disassociate-confirm.png

20.3. 使用通知

Notifications 标签页可以查看您设置的任何通知集成以及它们的状态(如果已运行)。

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

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

如果没有设置通知,点 Add 按钮创建新通知。如需配置各种通知类型和扩展消息传递的详情,请参阅 通知类型

20.4. 查看完成的作业

Completed Jobs 标签页提供了已运行的作业模板列表。点击 Expanded 查看每个作业的详情,包括其状态、ID 和名称、作业类型、启动和完成的时间、谁启动了作业,以及使用了哪个模板、清单、项目和凭证。您可以使用任何这些条件过滤已完成的作业列表。

_images/job-template-completed-jobs-view.png

在此列表中显示的切片作业会进行相应标记,包含已运行的分片作业数量:

_images/sliced-job-shown-jobs-list-view.png

20.5. 调度

Schedules 标签页访问特定作业模板的计划。

Job Templates - schedule launch

20.5.1. 调度作业模板

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

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

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

如果在 Credentials 字段中选择了 Prompt on Launch,当您为作业模板创建或编辑调度信息时,Schedules 表单的底部将显示 Prompt 按钮。如果没有在保存前将默认机器凭证替换为另一个机器凭证,您将无法在 Prompt 对话框中删除默认机器凭证。以下是此类消息的示例:

注解

To able to set extra_vars on schedules, you must select Prompt on Launch for Variables on the job template, or a configure and enable a survey on the job template, then those answered survey questions become extra_vars.

20.6. 调查

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

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

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

20.6.1. 创建问卷调查

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

  1. Survey 标签页并点 Add 按钮。

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

  • Question: The question to ask the user

  • **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:小数。您可以为该答案设置最小和最大长度(字符数)。

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

  • Minimum lengthMaximum length:指定何时需要回答的一个长度。

  • Default answer: The default answer to the question. This value is pre-filled in the interface and is used if the answer is not provided by the user.

_images/job-template-create-survey.png
  1. 输入问题信息后,点 Save 添加问题。

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

job-template-completed-survey

如果您有多个调查问题,请使用 Edit Order 按钮通过点击并拖动网格图标来重新安排问题的顺序。

_images/job-template-rearrange-survey.png
  1. 要添加更多问题,请点 Add 按钮添加其他问题。

20.6.2. 可选的问卷调查问题

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

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

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

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

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

20.7. 启动作业模板

automation controller 的主要优点是 Ansible playbook 的按钮式部署。您可以轻松地配置模板,以存储您通常会在命令行上传递给 ansible-playbook 的所有参数,不仅仅包括 playbook,还包括清单、凭证、额外变量以及您可在命令行上指定的所有选项和设置。

更简单的部署意味着每次都能以相同的方式运行 playbook,可以提高一致性,并且您可以委托职责。即使用户不是 Ansible 专家,也可以运行由其他人编写的 playbook。

通过以下任一方式启动作业模板:

  • 从左侧导航栏上的 Templates 菜单或在 Job Template Details 视图中访问作业模板列表,滚动到底部以从模板列表中访问 launch 按钮。

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

作业可能需要额外信息才能运行。启动时可能会要求提供以下数据:

  • 设置的凭证

  • 为任意参数选择 Prompt on Launch 选项

  • 已设置为 Ask 的密码

  • 问卷调查(如果已经为作业模板配置了问卷调查)

  • 额外变量(如果作业模板要求提供)

注解

如果一个作业有用户提供的值,则这些值会在重新启动时被考虑。如果用户没有指定值,作业会使用作业模板中的默认值。作业并不会按当前的状态原样重新启动。在重新启动时用户的输入会被应用到作业模板中。

以下是一个作业启动示例,它提示输入作业标签,并运行 调查 中创建的示例问卷调查。

job-launch-with-prompt-job-tags

job-launch-with-prompt-survey

注解

在一个标签页中输入值,然后返回上一个标签页,然后再继续进入下一个标签页会导致在剩余标签页中需要重新提供值。请安装提示出现的顺序填写标签页来避免出现这种情况。

除了作业模板和问卷调查中设置的额外变量之外,automation controller 会自动在作业环境中添加以下变量。另外,awx_``* 变量由系统定义,且无法覆盖。有关作业上下文的变量,如 ``awx_job_template_name 不会受到影响(如果它们设置了 extra_vars)。

  • awx_job_id:此作业运行的作业 ID

  • awx_job_launch_type:用于说明作业启动方式的描述:

    • manual:作业是由用户手动启动的。

    • relaunch:作业是通过重启来启动的。

    • callback:作业是通过主机回调启动的。

    • scheduled:作业是由一个调度启动的。

    • dependency:作业是作为另一个作业的依赖项启动的。

    • workflow:作业是从工作流作业中启动的。

    • sync:作业是从项目同步启动的。

    • scm:作业是作为清单 SCM 同步创建的。

  • awx_job_template_id:此作业运行使用的作业模板 ID

  • awx_job_template_name:此作业使用的作业模板名称

  • awx_project_revision:此特定作业使用的源树的修订标识符(它还与作业的字段 scm_revision 相同)

  • awx_project_scm_branch:作业模板使用的项目配置的默认项目 SCM 分支

  • awx_job_scm_branch 如果作业覆盖了 SCM 分支,其值将显示在此显示

  • awx_user_email:启动了此作业的控制器用户的用户电子邮件。此变量不可用于回调或调度的作业。

  • awx_user_first_name:启动了此作业的控制器用户的名字。此变量不可用于回调或调度的作业。

  • awx_user_id:启动了此作业的控制器用户的用户 ID。此变量不可用于回调或调度的作业。

  • awx_user_last_name:启动了此作业的控制器用户的姓。此变量不可用于回调或调度的作业。

  • awx_user_name:启动了此作业的控制器用户的用户名。此变量不可用于回调或调度的作业。

  • 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

启动后,automation controller 会在 Jobs 标签页下自动将 Web 浏览器重定向到此作业的 Job Status 页面。

注解

您可以从列表视图中重新启动最新的作业,以便针对指定清单中的所有主机或者仅仅是失败的主机重新运行。更多详情请参阅 Automation Controller User Guide 中的 Jobs

当分片作业正在运行时,作业列表会显示工作流和作业分片,以及用于单独查看其详情的链接。

_images/sliced-job-shown-jobs-list-view.png

20.8. 复制作业模板

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

  1. 从左侧导航栏上的 Templates 菜单或在 Job Template Details 视图中访问作业模板列表,滚动到底部以从模板列表中访问它。

Job templates - home with example job template

  1. 点与您要复制的模板关联的 copy 按钮。

在模板列表中会显示带有作为复制来源的新模板的名称和一个时间戳。

  1. 点击以打开新模板并点 Edit

  2. Name 字段的内容替换为新名称,并提供或者修改其他字段中的条目以完成此页面。

  3. 完成后请点击 Save

20.9. 扫描作业模板

从 automation controller 3.2 开始,不再支持扫描作业。此系统跟踪功能曾用来捕获和存储事实作为历史数据。现在,事实将通过事实缓存存储在控制器中。如需了解更多信息,请参阅 事实缓存

如果您在 automation controller 3.2 之前的系统中有作业模板扫描作业,它们已被转换为运行类型(类似于正常作业模板),并且保留了其相关资源(例如清单、凭证)。默认情况下会为没有相关项目的作业模板扫描作业分配一个特殊的 playbook,或者您可以使用自己的扫描 playbook 指定一个项目。之前为每个机构创建了一个指向 https://github.com/ansible/tower-fact-modules 的项目,并将作业模板设为 playbook https://github.com/ansible/tower-fact-modules/blob/master/scan_facts.yml.

20.9.1. 事实扫描 Playbook

扫描作业 playbook scan_facts.yml 包含三个 fact scan modules``(软件包、服务和文件)的调用以及 Ansible 的标准事实收集。``scan_facts.yml playbook 文件类似如下:

- 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_checksumscan_use_recursive 参数也可以设为 false 或省略。省略等同于 false 设置。

扫描作业模板应启用 become 并使用使 become 成为可能的凭证。您可以通过从 Options 菜单中选中 Enable Privilege Escalation 来启用 become:

_images/job-templates-create-new-job-template-become.png

20.9.2. scan_facts.yml 支持的操作系统

如果您将 scan_facts.yml playbook 与“使用事实缓存”搭配使用,请确保您的操作系统受支持:

  • Red Hat Enterprise Linux 5、6 和 7

  • Ubuntu 16.04(Unbuntu 支持已被弃用并将在以后的发行版本中删除)

  • 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.9.3. 预扫描设置

以下的 playbook 示例配置了特定发行版运行扫描,以便可以针对它们运行扫描作业。

Bootstrap Ubuntu (16.04)

---

- name: Get Ubuntu 16, and on ready
 hosts: all
 sudo: yes
 gather_facts: no

 tasks:

 - name: install python-simplejson
   raw: sudo apt-get -y update
   raw: sudo apt-get -y install python-simplejson
   raw: sudo apt-get install python-apt

Bootstrap 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.9.4. 自定义事实扫描

自定义事实扫描的 playbook 与上方的事实扫描 Playbook 类似。例如,只使用自定义 scan_foo Ansible 事实模块的 playbook 类似如下:

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 文档的 Module Provided 'Facts' 部分。

20.10. 事实缓存

自动化控制器可以通过 Ansible 事实缓存插件按主机存储和检索事实。此行为可以按作业模板进行配置。事实缓存默认关闭,但可以启用以满足与作业运行相关的清单中所有主机的事实请求。这可让您将作业模板与 --limit 搭配使用,同时仍可访问整个主机事实清单。插件按主机强制应用的全局超时设置可在 Jobs 设置菜单中指定(以秒为单位):

_images/configure-tower-jobs-fact-cache-timeout.png

在启动使用事实缓存(use_fact_cache=True)的作业后,控制器会保存与作业关联的清单中的每个主机所关联的所有 ansible_facts。automation controller 附带的 Ansible 事实缓存插件只会在启用了事实缓存(use_fact_cache=True)的作业上启用。

当启用事实缓存(use_fact_cache=True)的作业完成运行时,控制器将恢复清单中主机的所有记录。任何更新时间比每个主机当前存储的事实“更新”的记录都会在数据库中更新。

新事实和更改的事实将通过控制器的日志记录功能记录,具体来说是记录到 system_tracking 命名空间或日志记录器。日志记录有效负载将包括以下字段:

  • host_name

  • inventory_id

  • ansible_facts

其中 ansible_facts 是控制器清单 inventory_idhost_name 的所有 Ansible 事实的字典。

注解

如果主机名包含正斜杠 (/),事实缓存将不适用于该主机。如果清单中有 100 个主机,其中一个主机的名称中有一个 /,其中的 99 个主机仍会收集事实。

20.10.1. 事实缓存的好处

相较于运行事实收集,事实缓存会节省大量时间。如果您在一个针对一千个主机和 fork 运行的作业中有一个 playbook,您可以轻松地花 10 分钟来收集所有这些主机的事实。但是如果您定期运行一个作业,第一次运行会缓存这些事实,而下一次运行只需从数据库中拉取它们。这会大幅削减针对大型清单(包括智能清单)的作业运行时间。

注解

不要修改 ansible.cfg 文件来应用事实缓存。自定义事实缓存可能会与 控制器的事实缓存功能冲突。我们推荐使用 automation controller 附带的事实缓存模块。隔离的节点不支持事实缓存。

您可以选择在作业模板窗口的 Options 字段中启用缓存的事实以在作业中使用它。

_images/job-templates-options-use-factcache.png

要清除事实,您需要运行 Ansible clear_facts meta task。以下是使用 Ansible clear_facts 元任务的示例 playbook。

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

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

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

20.11. 使用云凭证

云凭证可以在同步相应的云清单时使用。云凭证还可能与作业模板关联,并包含在运行时环境中,供 playbook 使用。当前支持的云凭证:

20.11.1. OpenStack

以下示例 playbook 调用 nova_compute Ansible OpenStack 云模块,并要求凭证进行任何有意义的操作,它要求提供以下信息:auth_urlusernamepasswordproject_name。这些字段通过环境变量 OS_CLIENT_CONFIG_FILE 提供给 playbook,此变量指向控制器根据云凭证的内容编写的 YAML 文件。此示例 playbook 会将 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

Playbook 示例:

- 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.11.2. Amazon Web Services

Amazon Web Services 云凭证在 playbook 执行过程中作为以下环境变量公开(在作业模板中,选择您的设置所需的云凭证):

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

所有 AWS 模块在通过控制器运行时都会隐式使用这些凭证,而无需设置 aws_access_key_idaws_secret_access_key 模块选项。

20.11.3. Google

Google 云凭证在 playbook 执行过程中作为以下环境变量公开(在作业模板中,选择您的设置所需的云凭证):

  • GCE_EMAIL

  • GCE_PROJECT

  • GCE_CREDENTIALS_FILE_PATH

所有 Google 模块在通过控制器运行时都会隐式使用这些凭证,而无需设置 service_account_emailproject_idpem_file 模块选项。

20.11.4. Azure

Azure 云凭证在 playbook 执行过程中作为以下环境变量公开(在作业模板中,选择您的设置所需的云凭证):

  • AZURE_SUBSCRIPTION_ID

  • AZURE_CERT_PATH

所有 Azure 模块在通过控制器运行时都会隐式使用这些凭证,而无需设置 subscription_idmanagement_cert_path 模块选项。

20.11.5. VMware

VMware 云凭证在 playbook 执行过程中作为以下环境变量公开(在作业模板中,选择您的设置所需的云凭证):

  • VMWARE_USER

  • VMWARE_PASSWORD

  • VMWARE_HOST

以下示例 playbook 演示了这些凭证的使用情况:

- 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.12. 置备回调

置备回调是自动化控制器的一项功能,允许主机启动针对自身运行的 playbook,而不是等待用户启动作业以从自动化控制器控制台管理主机。请注意,置备回调*仅*用于在调用主机上运行 playbook。置备回调用于云爆发,即:需要客户端到服务器通信以进行配置(例如传输授权密钥)的新实例,而不是针对另一台主机运行作业。这就为以下操作提供了条件:当一个系统通过另一个系统(例如 AWS 自动缩放或操作系统置备系统,如 kickstart 或 preseed)进行配置后,会自动配置该系统;或者通过编程方式启动作业,而无需直接调用自动化控制器 API。启动的作业模板仅针对请求配置的主机运行。

通常这会通过 firstboot 类型脚本或从 cron 访问。

要启用回调,请选中作业模板中的 Provisioning Callbacks 复选框。这会显示此作业模板的 Provisioning Callback URL

注解

如果要将自动化控制器的置备回调功能与动态清单结合使用,则应该为作业模板中使用的清单组设置在启动时更新。

_images/provisioning-callbacks-config.png

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

要通过 REST 手动回调,请查看 UI 中的回调 URL,其格式为:

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

这个示例 URL 中的“7”是自动化控制器中的作业模板 ID。

来自主机的请求必须是 POST。以下是一个使用 curl 的示例(全部在一行):

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

发出请求的主机必须在您的清单中定义,才能使回调成功。如果自动化控制器无法按名称或 IP 地址在您定义的某一个清单中找到主机,则请求将被拒绝。在以这种方式运行作业模板时,启动针对其自身运行的 playbook 的主机必须位于清单中。如果该主机不在清单中,则作业模板将失败,并显示“No Hosts Matched”类型错误消息。

注解

如果您的主机不在清单中,并且为清单组设置了 Update on Launch,则自动化控制器会在运行回调前尝试更新基于云的清单源。

成功请求会在 Jobs 标签页中生成一个条目,可以在其中查看结果和历史记录。

虽然可以通过 REST 访问回调,但建议的回调使用方法是使用自动化控制器附带的示例脚本之一 - /usr/share/awx/request_tower_configuration.sh (Linux/UNIX) 或 /usr/share/awx/request_tower_configuration.ps1 (Windows)。用法在文件的源代码中通过传递 -h 标签进行描述,如下所示:

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

Request server configuration from Ansible Tower.

OPTIONS:
 -h      Show this message
 -s      Controller 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 的错误代码都可能不是需要重试的暂时性错误。

您最有可能在自动化控制器中将回调与动态清单搭配使用,如从支持的某个云提供商中拉取云清单。在这些情况下,除了设置 Update On Launch 以外,请务必为清单源配置清单缓存超时,以避免云的 API 端点受到攻击。由于 request_tower_configuration.sh 脚本每分钟轮询一次,最多十分钟,因此推荐的清单缓存失效时间(在清单源本身中配置)将为一分钟或两分钟。

虽然我们不推荐从 cron 作业运行 request_tower_configuration.sh 脚本,但建议的 cron 间隔可能为每 30 分钟。重复的配置可以通过在自动化控制器中调度来轻松处理,因此大多数用户主要使用回调来启用一个在上线时引导至最新配置的基础镜像。为此,在第一次引导时运行是更好的做法。初始引导脚本只是简单的 init 脚本,通常会自我删除,因此您可以设置一个调用 request_tower_configuration.sh 脚本副本的 init 脚本,并使之成为一个自动缩放镜像。

20.12.1. 将额外变量传递给配置回调

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

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

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

[email protected]:~$ curl -f -H 'Content-Type: application/json' -XPOST \
                 -d '{"host_config_key": "redhat", "extra_vars": "{\"foo\": \"bar\"}"}' \
                 https://<CONTROLLER_SERVER_NAME>/api/v2/job_templates/7/callback

有关详情请参阅 Launching Jobs with Curl

20.13. 额外变量

注解

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

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

  • ask_variables_on_launch 被设为 True

当您传递问卷调查变量时,它们作为控制器中的额外变量 (extra_vars) 传递。这样做可能需要非常小心,因为将额外变量传递给作业模板(就像对问卷调查的操作一样)可能会覆盖从清单和项目传递的其他变量。

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

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

如果指定 ALLOW_JINJA_IN_EXTRA_VARS 参数,请参阅 Automation Controller Administration GuideController Tips and Tricks 部分,以便在控制器 UI 的 Jobs Settings 屏幕中进行配置。

注解

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

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

YAML 格式的配置:

launch_to_orbit: true
satellites:
  - sputnik
  - explorer
  - satcom

JSON 格式的配置:

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

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

自动化控制器变量优先级层次结构(最后列出的优先)

_images/Architecture-Tower_Variable_Precedence_Hierarchy.png

20.13.1. 重新启动作业模板

重新启动通过将 launch_type 设置为 relaunch 来表示,而不是手动重新启动作业。重新启动行为与启动行为的偏差在于它**不**继承 extra_vars

作业重新启动不会通过继承逻辑。它会使用为重新启动的作业计算的相同 extra_vars

例如,假设您启动一个没有 extra_vars 的作业模板,导致创建一个名为 j1 的作业。下一步,假设您编辑作业模板,并加入一些 extra_vars``(如添加 ``"{ "hello": "world" }")。

重新启动 j1 导致创建 j2,但是由于没有继承逻辑,而且 j1 没有 extra_varsj2 将没有任何 extra_vars

继续前面的示例,如果您启动了包含您在创建 j1 之后添加的 extra_vars 的作业模板,创建的重新启动作业 (j3) 将包括 extra_vars。重新启动 j3 会导致创建 j4,其中也包括 extra_vars