Documentation

16. 项目

Project 是 Ansible playbook 的逻辑集合。

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

注解

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

Projects 页面中显示当前可用的项目列表。默认视图为折叠状态(Compact),只显示项目名称及其状态,但您可以使用每个条目旁边的箭头展开以了解更多信息。

Projects - home with example project

_images/projects-list-all-expanded.png

对于列出的每个项目,您可以使用每个项目旁边的相应图标获取最新的 SCM 修订 (refresh)、编辑项目 (edit) 或复制项目属性 (copy)。在相关作业运行时允许更新项目。如果您的项目太大(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

16.1. 添加新项目

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

  1. Add 按钮,启动 Create Project 窗口。

Projects - create new project

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

  • 名称

  • **Description**(可选)

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

  • **Default Execution Environment**(可选)- 输入执行环境的名称,或从现有环境列表中搜索以运行此项目。如需更多信息,请参阅 Ansible Automation Platform Upgrade and Migration Guide 中的 升级至 Execution Environments

  • Source Control Credential 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

16.1.1. 手动管理 playbook

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

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

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

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

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

警告

如果您尚未将任何 Ansible playbook 目录添加到基本项目路径,您将收到以下消息:

Projects - create new warning

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

16.1.2. 使用源控制管理 playbook

16.1.2.1. SCM 类型 - Git 和 Subversion

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

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

Projects - create SCM project

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

  • SCM URL - 请参阅工具提示 tooltip 中的示例。

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

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

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

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

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

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

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

  • 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 非常相似。使用它不会给您的系统带来任何改变或损害。

16.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 的角色目录。 Automation controller 确保本地修订版本与最新角色和集合匹配。 另外,如果作业的生成速度快于项目的同步速度,为了避免作业溢出,您可以配置一个缓存超时来为以前的项目同步缓存特定的时间(秒)。

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

16.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 保存您的项目。

16.2. 从源控制更新项目

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

注解

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

projects - list all

  1. Status 列下项目的状态,以获取有关更新过程的更多详情。

_images/projects-list-status-more.png

Project - update status

16.3. 使用权限

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

您可以通过 Details 标签页旁边的 Access 标签页访问项目权限。此屏幕显示目前对此项目具有权限的用户列表。该列表可以根据 UsernameFirst NameLast Name 进行排序和搜索。

Projects - permissions list for example project

16.3.1. 添加权限

  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

16.4. 使用通知

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

_images/projects-notifications-example-list.png

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

如果没有设置通知,您可以从左侧导航栏中的 Notifications 链接配置它们,以创建新通知。

_images/project-notifications-empty.png

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

16.5. 使用作业模板

您可以点击 Job Templates 来添加和查看与此项目关联的任何作业模板或工作流模板。

_images/projects-templates-example-list.png

点使用该模板运行的作业的状态来查看其详细信息和其他有用信息。您可以根据各种条件对列表进行排序,并执行搜索来过滤相关的模板。

_images/projects-templates-job-status.png

从此视图中,您还可以启动 (launch) 或编辑 (edit) 模板配置。

16.6. 使用计划

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

_images/generic-schedules-list-configured.png

16.6.1. 调度项目

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

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

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

16.7. Ansible Galaxy 支持

在项目更新结束时,automation controller 会搜索位于 <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> 。 但是,您可以根据您的环境,在 Settings 窗口的 Jobs Settings 选项卡中指定另外一个 Job Execution Path:

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

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

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

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

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

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

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

update-on-launch

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

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

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

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

注解

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

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

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

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

注解

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

16.8. 集合支持

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

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

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

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

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

update-on-launch

16.8.1. 通过 Hub 使用集合

在 automation controller 可以使用 Automation Hub 作为集合内容的默认源前,您需要在 Automation Hub UI 中创建 API 令牌,以便在 automation controller 中指定它。您可以连接到私有 Automation Hub 或公共 Automation Hub 集合,唯一的区别是您指定哪个 URL。

  1. 导航到 https://cloud.redhat.com/ansible/automation-hub/token 并点击 Load token

  2. 点复制图标将 API 令牌复制到剪贴板。

_images/projects-ah-loaded-token-shown.png
  1. 要使用公共 Automation Hub,请使用复制的令牌创建一个 Automation Hub 凭证,并指向令牌页面的 Server URLSSO URL 字段中显示的 URL:

  • Galaxy Server URL = https://cloud.redhat.com/api/automation-hub/

  • AUTH SEVER URL = https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token

  1. 要使用私有 Automation Hub,请使用本地 Automation Hub 的 Repo Management 仪表板中获取的令牌创建一个 Automation Hub 凭证,并指向公布的存储库 URL,如下所示:

_images/projects-ah-repo-mgmt-get-token.png _images/projects-ah-repo-mgmt-repos-published.png

您可以使用不同的命名空间/集合创建不同的仓库。 但是,对于 Automation Hub 中的每个仓库,您需要创建不同的 Automation Hub 凭证。将 Automation Hub UI 中的 Ansible CLI URL 复制到 Create Credential 表单的 Galaxy Server URL 字段中,格式为 https://$<hub_url>/api/galaxy/content/<repo you want to pull from>

_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 有自签名证书,点切换启用设置 Ignore Ansible Galaxy SSL Certificate Verification。对于使用签名证书的 public Automation Hub,点切换来禁用它。请注意,这是一个全局设置:

_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 以针对此项目运行更新。Automation controller 从文件 collections/requirements.yml 中获取 Galaxy 集合并按更改报告 ; 现在将使用这个项目为任何作业模板安装集合。

注解

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

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