Documentation

14. 项目

:term:`Project`是 Tower 中的 Ansible playbook 的逻辑集合。

您可以将 playbook 和 playbook 目录手动放置到 Tower 服务器的 Project Base 路径下,或者将 playbook 放置到 Tower 支持的源代码管理 (SCM) 系统,包括 Git、Subversion、Mercurial 和红帽 Insights,这两种方法均可管理 playbook 和 playbook 目录。要创建红帽 Insights 项目,请参阅 设置 Insights 项目

注解

默认情况下,项目基本路径是 /var/lib/awx/projects,但可能已被 Tower 管理员修改。它在 /etc/tower/conf.d/custom.py 中配置。编辑此文件时请小心谨慎,因为不正确的设置可能会禁用您的安装。

此菜单显示了当前可用的项目列表。默认视图为折叠状态 (Compact),显示项目名称及其状态,但您可以扩展为查看更多信息。您可以按照各种条件对列表进行排序,然后执行搜索来过滤相关的项目。

Projects - home with example project

_images/projects-list-all-expanded.png

对于列出的每个项目,您可以使用每个项目旁边的相应图标获取最新的 SCM 修订(refresh),复制项目属性(copy)或删除项目(delete-icon)。 从 Ansible Tower 3.7 开始,允许在运行相关任务时更新项目。 如果您有大项目(大约 10 GB),则 /tmp 可能会出现磁盘空间的问题。

Status 指示项目的状态,可能是以下之一(注意您也可以根据特定状态类型过滤您的视图):

  • Pending - 已创建源控制更新但尚未排队或启动。在实际准备好由系统运行之前,任何作业(不仅仅是源控制更新)都会停留在等待状态。源控制更新未准备就绪的原因是有依赖项当前正在运行,必须等到它们都已完成,或者其配置的位置没有足够的运行容量。

  • Waiting - 源控制更新处于等待执行的队列中。

  • Running - 源控制更新当前正在进行中。

  • Successful - 此项目的最后源控制更新成功。

  • Failed - 此项目的最后源控制更新失败。

  • Error - 最后的源控制更新作业根本无法运行。(即将弃用。)

  • Canceled - 项目的最后源控制更新已被取消。

  • Never updated - 项目被配置用于源控制,但从未更新。

  • OK - 项目未被配置用于源控制,并且位于正确的位置。(即将弃用。)

  • Missing - 项目不存在于 /var/lib/awx/projects 的项目基本路径中(适用于手动或源控制管理的项目)。

注解

凭证类型为 Manual 的项目若不重新配置为 SCM 类型的凭证,将无法更新或调度基于源控制的操作。

注解

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

_images/warning-deletion-dependencies.png

14.1. 添加新项目

要创建新项目,请执行以下操作:

  1. 点击 add 按钮,启动 Create Project 窗口。

Projects - create new project

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

  • 名称

  • **Description**(可选)

  • Organization - 一个项目必须至少有一个机构。现在选择一个机构以创建项目,然后在创建项目后,您可以添加额外的机构。

  • **Ansible Environment**(可选)- 从下拉菜单中选择一个自定义虚拟环境以针对其运行此项目。这个字段只有在之前创建了自定义环境时才会出现。请参阅 Ansible Tower Upgrade and Migration Guide 中的 使用 Ansible Tower 的 virtualenv

  • SCM Type - 从下拉菜单中选择与这个项目关联的 SCM 类型。后续部分中的选项会根据您选择的类型显示出来。更多详情请参阅后续部分中的 手动管理 playbook使用源控制管理 playbook

注解

如果添加手动项目,项目根文件夹中的每个项目路径只能分配给一个项目。如果您收到以下消息,请确保您还没有将项目路径分配给现有项目:

All of the project paths have been assigned to existing projects, or there are no directories found in the base path. You will need to add a project path before creating a new project.

  1. 完成后请点击 Save

14.1.1. 手动管理 playbook

  • 在项目基本路径下创建一个或多个目录来存储 playbook(例如,/var/lib/awx/projects/)

  • 创建 playbook 文件或将其复制到 playbook 目录中。

  • 确保 playbook 目录和文件属于运行 Tower 服务的同一 UNIX 用户和组。

  • 确保权限适合 playbook 目录和文件。

如果您在添加项目路径时遇到问题,请检查项目目录和文件的权限和 SELinux 上下文设置。

警告

如果您还没有将任何 Ansible playbook 目录添加到基本项目路径,您将收到来自 Tower 的以下消息:

Projects - create new warning

要纠正这个问题,请创建适当的 playbook 目录并从您的 SCM 中签出 playbook 或将 playbook 复制到适当的 playbook 目录。

14.1.2. 使用源控制管理 playbook

14.1.2.1. SCM 类型 - Git、Mercurial 和 Subversion

要配置 playbook 以使用源控制,在 Project Details 选项卡中:

  1. SCM Type 下拉菜单中选择适当的选项(Git、Subversion 或 Mercurial)。

Projects - create SCM project

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

  • SCM URL - 请参阅帮助 help 文本中的示例。

  • **SCM Branch/Tag/Commit**(可选)- 输入源控制(Git、Subversion 或 Mercurial)中的 SCM 分支、标签、提交散列、任意 refs 或修订号(若适用)以签出。除非您在下一字段中还提供了自定义 refspec,否则某些提交散列和 refs 可能无法使用。

  • SCM Refspec - 这个字段是 git 源控制特有的选项,只有熟悉并能够轻松使用 git 的高级用户才应该指定要从远程存储库下载哪些参考。更多详情请参阅 job branch overriding

  • SCM Credential - 如果需要验证,请选择适当的 SCM 凭证

  1. SCM Update Options 中,在适用的情况下,可以选择启动行为。

  • Clean - 在进行更新前删除任何本地修改。

  • Delete on Update - 在进行更新前删除整个本地存储库。根据存储库的大小,这可能会显著增加完成更新所需的时间。

  • Update Revision on Launch - 将项目的修订更新至远程源控制中的当前修订,并缓存来自 GalaxyCollections 的角色目录。 Tower 确保本地修订版本与最新角色和集合匹配。 另外,如果作业的生成速度快于项目的同步速度,为了避免作业溢出,您可以配置一个缓存超时来为以前的项目同步缓存特定的时间(秒)。

  • Allow Branch Override - 允许使用这个项目的作业模板通过项目以外的指定 SCM 分支或修订来启动。如需了解更多详情,请参阅 job branch overriding

_images/projects-create-scm-project-branch-override-checked.png
  1. 点击 Save 保存您的项目。

小技巧

使用 GitHub 链接为使用 playbook 提供了一种简单的方法。要帮助您入门,请使用 helloworld.yml 文件(https://github.com/ansible/tower-example.git

这个链接提供的 playbook 与 :ref:`Ansible Tower Quick Start Guide <qs_start>`说明中手动创建的 playbook 非常相似。使用它不会给您的系统带来任何改变或损害。

14.1.2.2. SCM 类型 - Red Hat Insights

要配置 playbook 来使用 Red Hat Insights,在 Project Details 标签页中:

  1. SCM Type 下拉菜单中选择 Red Hat Insights

  2. Red Hat Insights 需要一个凭证来进行身份验证。从 Credential 字段中选择可用于 Insights 的适当凭证。

  3. SCM Update Options 中,在适用的情况下,可以选择启动行为。

  • Clean - 在进行更新前删除任何本地修改。

  • Delete on Update - 在进行更新前删除整个本地存储库。根据存储库的大小,这可能会显著增加完成更新所需的时间。

  • Update Revision on Launch - 将项目的修订更新至远程源控制中的当前修订,并缓存来自 GalaxyCollections 的角色目录。 Tower 确保本地修订版本与最新角色和集合匹配。 另外,如果作业的生成速度快于项目的同步速度,为了避免作业溢出,您可以配置一个缓存超时来为以前的项目同步缓存特定的时间(秒)。

_images/projects-create-scm-insights.png
  1. 点击 Save 保存您的项目。

14.1.2.3. SCM 类型 - 远程归档

使用远程存档的 playbook 允许基于生成版本工件或发行版本的构建过程提供项目,其中包含该项目在单个存档中的所有要求。

要将 playbook 配置为使用远程存档,在 Project Details 选项卡中:

  1. SCM Type 下拉菜单中选择 Remote Archive

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

  • SCM URL - 需要一个远程归档的 URL,如 GitHub Release 或存储在 Artifactory 中的构建工件,并将其解包到要使用的项目路径中

  • SCM Credential - 如果需要验证,请选择适当的 SCM 凭证

  1. SCM Update Options 中,在适用的情况下,可以选择启动行为。

  • Clean - 在进行更新前删除任何本地修改。

  • Delete on Update - 在进行更新前删除整个本地存储库。根据存储库的大小,这可能会显著增加完成更新所需的时间。

  • Update Revision on Launch - 不建议使用此选项,因为它会将项目的修订更新至远程源控制中的当前修订版本,并缓存来自 GalaxyCollections 的角色目录。

  • Allow Branch Override - 不建议使用此选项,因为它允许使用此项目的作业模板使用项目以外的指定 SCM 分支或修订启动。

_images/projects-create-scm-rm-archive.png

注解

由于此 SCM 类型旨在支持未修改工件的概念,因此建议禁用 Galaxy 集成(至少针对角色)。

  1. 点击 Save 保存您的项目。

14.2. 从源控制更新项目

  1. 通过选择项目并点击 refresh 按钮来更新基于 SCM 的现有项目。

注解

请注意,在添加项目设置以使用源控制后,会立即启动一个“同步”进程来从配置的源控制获取项目详情。

projects - list all

  1. 点击 **Status**(最左侧,项目名称旁边)下的点来获得更新过程的更多详情。

Project - update status

14.3. 使用权限

权限是指分配给此项目的权限集(基于角色的访问控制),可提供读取、修改和管理项目、清单、作业模板及其他 Tower 元素的能力。

您可以通过 Details 标签页旁边的 Permissions 标签页来访问项目权限。这个屏幕显示目前对此项目具有权限的用户列表。这个列表可以根据 UserRoleTeam Role 进行排序和搜索。

Projects - permissions list for example project

14.3.1. 添加权限

Permissions 标签页允许您为用户和团队成员审核、授权、编辑和删除相关权限。要为特定用户分配这个资源的权限:

  1. 点击**Permissions** 标签页。

  2. 点击 add 按钮,打开 Add Users/Teams 窗口。

Add Permissions Form
  1. 指定将分配访问权限的用户或团队,然后为其分配特定的角色:

  1. 点击需要选择的用户或团队名称旁的复选框来选择它们。

注解

您可以同时选择多个用户和团队,方法是在没有保存的情况下在 UsersTeams 标签页中进行选择。

选择后,窗口将展开,以便您为选择的每个用户或团队从下拉菜单中选择一个角色。

Roles Assignment for Selected Users

上面的例子显示了与清单关联的选项. 不同的资源有不同的可用选项:

  • Admin 允许读、运行和编辑权限(适用于所有资源)

  • Use 允许使用作业模板中的资源(适用于除作业模板以外的所有资源)

  • Update 允许通过 SCM 更新项目(适用于项目和 inventory)

  • AdPriority 允许使用 Ad Hoc 命令(适用于 inventory)

  • Execute 允许启动作业模板(适用于作业模板)

  • Read 允许只读访问(适用于所有资源)

小技巧

使用角色选择栏中的 Key 按钮显示每个角色的描述信息。如需更多信息,请参阅本指南的 角色 部分。

  1. 选择应用到所选用户或团队的角色。

注解

您可以同时为多个用户和团队分配角色,方法是在没有保存的情况下在 UsersTeams 标签页中进行设置。

Add Permissions - Examples of users and teams selected
  1. 查看为每个用户和团队分配的角色。

Add Permissions - Examples of roles applied
  1. 完成后,点击 保存,然后关闭 Add Users/Teams 窗口以显示为每个用户和团队分配的更新角色。

    Permissions tab with Role Assignments

要删除特定用户的权限,请点击其资源旁的 Disassociate (x) 按钮。

_images/permissions-disassociate.png

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

_images/permissions-disassociate-confirm.png

14.4. 使用通知

点击 Notifications 标签页可以查看您设置的任何通知集成。

_images/projects-notifications-example-list.png

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

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

_images/project-notifications-empty.png

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

14.5. 使用作业模板

您可以点击 Job Templates 来添加和查看与此项目关联的任何作业模板或工作流模板。点击 Expanded 可查看每个模板的详情,包括使用该模板运行的作业的状态,以及其他有用的信息。您可以按照各种条件对此列表进行排序,并通过执行搜索来过滤相关的模板。

_images/projects-templates-example-list.png

从此视图中,您也可以启动 (launch)、复制 (copy) 或删除 (delete-icon) 模板配置。注意,上面的例子显示了展开的视图。

14.6. 使用计划

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

_images/projects-schedules-example-list.png

14.6.1. 调度项目

要调度项目运行,请点击 Schedules 标签页。

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

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

14.7. Ansible Galaxy 支持

在项目更新结束时,Tower 会搜索位于 <project-top-level-directory>/roles/requirements.ymlroles 目录中名为 requirements.yml 的文件。如果找到这个文件,以下命令会自动运行:

ansible-galaxy role install -r roles/requirements.yml -p <project-specific cache location>/requirements_roles -vvv

您可以通过此文件引用可以与您自己的项目一起签出的 Galaxy 角色或其他存储库中的角色。添加此 Ansible Galaxy 支持后便无需创建 git 子模块以实现此结果。由于 SCM 项目(以及角色/集合)被拉取并从私有作业环境中执行,因此默认会在 /tmp 中创建特定于具体项目的 <private job directory> 。 但是,您可以根据您的环境,在 Configure Tower 窗口的 Jobs Settings 选项卡中指定另外一个 Job Execution Path:

_images/configure-tower-jobs-execution-path.png

缓存目录是全局项目目录中的一个子目录。内容可以从缓存位置复制到 <job private directory>/requirements_roles 位置。

默认情况下,Ansible Tower 有一个系统范围设置,允许从 SCM 项目的 roles/requirements.yml 文件中动态下载角色。您可以通过将 Enable Role Download 切换按钮切换到 OFF,在 Settings (settings) 菜单的 Jobs 标签页中关闭这个设置。

_images/configure-tower-jobs-download-roles.png

每当项目同步运行时,Tower 会决定项目源以及来自 Galaxy 和/或集合的任何角色是否已与项目不同步。项目更新将会下载更新内的角色。

如果作业需要获取上游角色的更改,更新项目会确保这种情况发生。 对角色的更改意味着新提交被推送到 provision-role 源控制。 要使这一更改在作业中生效,您不需要将新提交推送到 playbooks 仓库,但您**需要**更新项目,该项目会将角色下载到本地缓存中。例如,假设您在源控制中有两个 git 仓库。 第一个是 playbooks,Tower 中的项目指向这个 URL。 第二个是 provision-role,它被 playbooks git repo 中的 roles/requirements.yml 文件引用。

简而言之,作业会在每个作业运行前下载最新角色。因为性能的原因,角色和集合会在本地被缓存,您需要在项目的 SCM 更新选项中选择 Update Revision on Launch,以确保上游角色在每次作业运行前都会重新下载:

update-on-launch

更新的过程比同步要更早发生,因此在此阶段可以更快地显示错误和详细信息。

_images/project-update-job-details-stdout.png

如需有关 requirements.yml 文件语法的更多信息和示例,请参阅 Ansible 文档中的 role requirements section

如果系统中有需要特别公开的目录,您可以在 Configure Tower 界面的 Paths to Expose to Isolated Jobs 中指定,或者在设置文件中更新以下条目:

AWX_PROOT_SHOW_PATHS = ['/list/of/', '/paths']

注解

如果 playbook 需要使用在 /var/lib/awx/.ssh 中定义的密钥或设置,则需要把它做为主文件添加到 AWX_PROOT_SHOW_PATHS

如果您更改了设置文件,请确定在保存了更改后使用 ansible-tower-service restart 命令重启服务。

在 Tower 用户界面中,可以在 Jobs 设置窗口中配置这些设置。

_images/configure-tower-jobs-path-to-expose.png

注解

Primary Galaxy Server UsernamePrimary Galaxy Server Password 字段在 Ansible Tower 3.8 中无法进行配置。我们推荐使用令牌访问 Galaxy 或 Automation Hub。

14.8. 集合支持

Tower 在作业运行中支持特定于项目的 Ansible 集合。如果您在 collections/requirements.yml 指定 SCM 中的集合要求文件,则 Tower 将在作业运行前在隐式项目同步中将集合安装到该文件中。要指定集合要求,请执行以下操作:

ansible-galaxy collection install -r requirements.yml -p <job tmp location>

默认情况下,Ansible Tower 有一个系统范围设置,允许从 SCM 项目的 collections/requirements.yml 文件中动态下载角色。您可以使用 Settings (settings) 菜单中的 Jobs 标签页关闭这个设置(将 Enable Collections Download 切换按钮切换到 OFF)。

_images/configure-tower-jobs-download-collections.png

因为性能的原因,角色和集合会在本地缓存。您需要在项目 SCM 更新选项中选择 Update Revision on Launch 以确保:

update-on-launch

14.8.1. 在 Tower 中使用集合

使用 Tower Automation Hub 中本地发布的集合:

  1. 创建一个 Automation Hub 凭证,指向已公布的仓库及其从您的本地 Automation Hub Repo Management 仪表板获取的令牌。

_images/projects-ah-repo-mgmt-repos.png

您可以使用不同命名空间/集合创建不同的仓库。但是对于 Automation Hub 中的每个仓库都需要创建不同的 Automation Hub 凭证。请以 https://$<hub_url>/api/galaxy/content/<repo you want to pull from> 的格式在 Galaxy Server URL 字段中输入 Automation Hub UI 的 "Ansible CLI URL":

_images/projects-create-ah-credential.png

与 Automation Hub UI 具体相关的信息,请参阅 Managing Red Hat Certified and Ansible Galaxy Collections in Ansible Hub

  1. 进入到您要从 Automation Hub 进行同步内容的机构,并将新的 Automation Hub 凭证添加到这个机构。此步骤允许您将每个机构与您要使用内容的 Automation Hub 凭证(例如 repo)相关联。

_images/projects-organizations-add-ah-credential.png

注解

假设您有两个仓库:

  • prodNamespace 1Namespace 2 每个都有集合 ABnamespace1.collectionA:v2.0.0namespace2.collectionB:v2.0.0

  • Stage: Namespace 1 只有集合 Anamespace1.collectionA:v1.5.0 Automation Hub,您将会有一个 ProdStage 的 repo URL。

您可以为每个创建一个 Automation Hub 凭证。然后您可以为不同机构分配不同级别的访问权限。例如,您可以创建一个 Developers 机构,两个仓库都可以被这个机构访问。另外,创建一个 Operations 机构,它只能访问 Automation Hub Prod 仓库。

与 Automation Hub UI 具体相关的信息,请参阅 Managing User Access in Ansible Hub

  1. 如果 Automation Hub 有自签名证书,点击以启用 Tower 的设置 Ignore Ansible Galaxy SSL Certificate Verification。请注意,这是全局设置:

_images/settings-jobs-ignore-galaxy-certs.png
  1. 创建一个项目,其源仓库在 collections/requirements.yml 文件中指定需要的集合。请参阅 Ansible 文档中的语法: https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#install-multiple-collections-with-a-requirements-file

_images/projects-add-ah-source-repo.png
  1. 在 Projects 列表视图中,点 update 以针对此项目运行更新。Tower 从文件 collections/requirements.yml 中获取 Galaxy 集合并按更改报告 ; 现在将使用这个项目为任何作业模板安装集合。

注解

如果需要从 Galaxy 或 Collections 进行更新,则会执行一个下载所需角色的同步,这将消耗您的 /tmp 文件中的更多空间。当您的项目较大时(大约 10 GB),/tmp 可能会导致磁盘空间的问题。

如需有关集合的更多信息,请参阅 Using Collections。如需有关红帽官方发布的、可用于直接自动化 Tower 安装的集合信息,请参阅 AWX Ansible Collection 文档。此页面可通过您的红帽客户凭证进行访问,它是您的 Red Hat Ansible Automation Platform 订阅的一部分。