16. 项目

一个项目是 Ansible 剧本的逻辑集合。

您可以通过将剧本手动放置在服务器上的项目基本路径下，或者将剧本放置到 AWX 支持的源代码管理 (SCM) 系统（包括 Git、Subversion 和 Red Hat Insights）中来管理剧本和剧本目录。要创建 Red Hat Insights 项目，请参阅设置 Insights 补救措施。

注意

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

“项目”页面显示当前可用的项目列表。默认视图是折叠的（**紧凑**），显示项目名称及其状态，但您可以使用每个条目旁边的箭头展开以获取更多信息。

Compact Projects list view with two projects shown.

Projects list view showing arrows used to expand and collapse projects in the view.

对于列出的每个项目，您可以获取最新的 SCM 修订版本（Refresh button）、编辑项目（edit button）或复制项目属性（copy button），使用每个项目旁边的相应图标。在相关作业运行期间，允许更新项目。如果您有一个大型项目（大约 10 GB），则/tmp上的磁盘空间可能成为问题。

**状态**指示项目的状态，可能是以下之一（请注意，您还可以按特定状态类型过滤视图）

  • **挂起** - 源代码控制更新已创建，但尚未排队或启动。任何作业（不仅仅是源代码控制更新）都将保持挂起状态，直到它实际上准备由系统运行。它未准备好的原因可能是它具有当前正在运行的依赖项，因此它必须等到它们完成后才能运行，或者在其配置的运行位置没有足够的容量。

  • **等待** - 源代码控制更新正在队列中等待执行。

  • **运行中** - 源代码控制更新当前正在进行中。

  • **成功** - 此项目的上次源代码控制更新成功。

  • **失败** - 此项目的上次源代码控制更新失败。

  • **错误** - 上次源代码控制更新作业根本无法运行。（即将弃用。）

  • **已取消** - 项目的上次源代码控制更新已取消。

  • **从未更新** - 项目已配置为源代码控制，但从未更新过。

  • **正常** - 项目未配置为源代码控制，并且正确地就位。（即将弃用。）

  • **丢失** - 项目不存在于/var/lib/awx/projects的项目基本路径中（适用于手动或源代码控制管理的项目）。

注意

凭据类型为“手动”的项目无法更新或计划基于源代码控制的操作，除非将其重新配置为 SCM 类型凭据。

注意

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

../_images/warning-deletion-dependencies.png

16.1. 添加新项目

要创建新项目

  1. 单击“添加”按钮，这将启动“创建项目”窗口。

Create New Project form

  1. 在以下必填字段中输入相应的详细信息

  • 名称

  • 描述（可选）

  • 组织 - 项目必须至少拥有一个组织。现在选择一个组织来创建项目，然后在创建项目后，您可以添加其他组织。

  • 执行环境（可选） - 输入执行环境的名称或从现有执行环境列表中搜索以运行此项目。有关更多信息，请参阅AWX 升级和迁移指南中的升级到执行环境。

  • 源代码控制类型 - 从下拉菜单列表中选择与该项目关联的 SCM 类型。后续部分中的选项将根据您选择的类型而可用。有关更多详细信息，请参阅后续部分中的手动管理剧本或使用源代码控制管理剧本。

  • 内容签名验证凭据 - 使用此可选字段启用内容验证。指定用于在项目同步期间验证内容签名的 GPG 密钥。如果内容已被篡改，则作业将不会运行。有关更多详细信息，请参阅项目签名和验证。

  1. 完成后，单击“保存”。

以下描述了 AWX 中项目源的方式

16.1.1. 手动管理剧本

  • 创建一个或多个目录以在项目基本路径下存储剧本（例如，/var/lib/awx/projects/）。

  • 在剧本目录中创建或复制剧本文件。

  • 确保剧本目录和文件由与 AWX 服务运行相同的 UNIX 用户和组拥有。

  • 确保剧本目录和文件的权限适当。

如果添加手动项目，则项目根文件夹内的每个项目路径只能分配给一个项目。如果您收到以下消息，请确保您尚未将项目路径分配给现有项目

所有 项目 路径 都已 分配给 现有 项目， 或者 基本路径中 没有 找到 目录。 您 需要 添加 项目 路径 才能 创建 新 项目。

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

警告

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

Create New Project form showing warning associated with selecting Source Control Credential Type of Manual

通过创建相应的剧本目录并从您的 SCM 中检出剧本或以其他方式将剧本复制到相应的剧本目录中来更正此问题。

16.1.2. 使用源代码管理管理剧本

16.1.2.1. SCM 类型 - Git 和 Subversion

要配置 playbook 以使用源代码管理，请在项目**详细信息**选项卡中

  1. 从**SCM 类型**下拉菜单列表中选择相应的选项（Git 或 Subversion）。

Create New Project form for Git Source Control Credential Type.

  1. 在以下字段中输入相应的详细信息

  • **SCM URL** - 在工具提示中查看示例 tooltips icon。

  • **SCM 分支/标签/提交** - 可选地输入源代码管理（Git 或 Subversion）中的 SCM 分支、标签、提交哈希、任意引用或修订号（如果适用）。除非您还在下一个字段中提供自定义 refspec，否则某些提交哈希和引用可能不可用。如果留空，则默认为 HEAD，即此项目的最后一个签出的分支/标签/提交。

  • **SCM Refspec** - 此字段是特定于 git 源代码管理的选项，只有熟悉并精通 git 的高级用户才能指定要从远程存储库下载哪些引用。有关更多详细信息，请参阅 作业分支覆盖。

  • **源代码管理凭据** - 如果需要身份验证，请选择相应的源代码管理凭据

  1. 在**SCM 更新选项**中，可选地选择启动行为（如果适用）。

  • **清理** - 在执行更新之前删除任何本地修改。

  • **删除** - 在执行更新之前完全删除本地存储库。根据存储库的大小，这可能会大大增加完成更新所需的时间。

  • **跟踪子模块** - 跟踪最新的提交。在工具提示中查看更多详细信息 tooltips icon。

  • **启动时更新版本** - 将项目的版本更新为远程源代码管理中的当前版本，并缓存来自 Galaxy 或 集合 的角色目录。AWX 确保本地版本匹配，并且角色和集合与上次更新保持最新。此外，为了避免如果作业启动速度快于项目同步速度而导致的作业溢出，选择此选项允许您配置缓存超时，以在一定秒数内缓存以前的项目同步。

  • **允许分支覆盖** - 允许使用此项目的作业模板或清单源以指定的 SCM 分支或版本启动，而不是项目的版本。有关更多详细信息，请参阅 作业分支覆盖。

create scm project branch override checked

  1. 单击**保存**以保存您的项目。

提示

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

此链接提供的 playbook 与在 AWX 快速入门中找到的说明中手动创建的 playbook 非常相似。使用它不会以任何方式更改或损害您的系统。

16.1.2.2. SCM 类型 - Red Hat Insights

要配置 playbook 以使用 Red Hat Insights，请在项目**详细信息**选项卡中

  1. 从**SCM 类型**下拉菜单列表中选择**Red Hat Insights**。

  2. Red Hat Insights 需要凭据进行身份验证。从**凭据**字段中选择用于 Insights 的相应凭据。

  3. 在**SCM 更新选项**中，可选地选择启动行为（如果适用）。

  • **清理** - 在执行更新之前删除任何本地修改。

  • **删除** - 在执行更新之前完全删除本地存储库。根据存储库的大小，这可能会大大增加完成更新所需的时间。

  • **启动时更新版本** - 将项目的版本更新为远程源代码管理中的当前版本，并缓存来自 Galaxy 或 集合 的角色目录。AWX 确保本地版本匹配，并且角色和集合与上次更新保持最新。此外，为了避免如果作业启动速度快于项目同步速度而导致的作业溢出，选择此选项允许您配置缓存超时，以在一定秒数内缓存以前的项目同步。

Create New Project form for Red Hat Insights Source Control Credential Type.

  1. 单击**保存**以保存您的项目。

16.1.2.3. SCM 类型 - 远程存档

使用远程存档的 playbook 允许根据生成版本化工件或版本的过程提供项目，该过程在一个存档中包含该项目的所有要求。

要配置 playbook 以使用远程存档，请在项目**详细信息**选项卡中

  1. 从**SCM 类型**下拉菜单列表中选择**远程存档**。

  2. 在以下字段中输入相应的详细信息

  • **SCM URL** - 需要指向远程存档的 URL，例如GitHub 发布或存储在Artifactory中的构建工件，并将其解压缩到项目路径中以供使用

  • **SCM 凭据** - 如果需要身份验证，请选择相应的 SCM 凭据

  1. 在**SCM 更新选项**中，可选地选择启动行为（如果适用）。

  • **清理** - 在执行更新之前删除任何本地修改。

  • **删除** - 在执行更新之前完全删除本地存储库。根据存储库的大小，这可能会大大增加完成更新所需的时间。

  • **启动时更新版本** - 不推荐，因为此选项会将项目的版本更新为远程源代码管理中的当前版本，并缓存来自 Galaxy 或 集合 的角色目录。

  • **允许分支覆盖** - 不推荐，因为此选项允许使用此项目的作业模板以指定的 SCM 分支或版本启动，而不是项目的版本。

Create New Project form for Remote Archive Source Control Credential Type.

注意

由于此 SCM 类型旨在支持不变工件的概念，因此建议禁用 Galaxy 集成（至少对于角色而言）。

  1. 单击**保存**以保存您的项目。

16.2. 从源代码管理更新项目

  1. 要更新现有的基于 SCM 的项目，请选择该项目并单击 Refresh button 按钮。

注意

请注意，在添加项目设置以使用源代码管理后，会立即开始“同步”，该同步从配置的源代码管理中获取项目详细信息。

Projects list view with the latest revision information of the projects that synched.

  1. 单击**状态**列下项目的**状态**以获取有关更新过程的更多详细信息。

Projects list view with example project with a successful status.

Example project with real-time standard output details.

16.3. 使用权限

分配给此项目（基于角色的访问控制）的一组权限，这些权限提供读取、修改和管理项目、清单、作业模板和其他 AWX 元素的功能，称为特权。

您可以通过**详细信息**选项卡旁边的**访问**选项卡访问项目权限。此屏幕显示当前具有此项目权限的用户列表。该列表可以按**用户名**、**名字**或**姓氏**排序和搜索。

Access tab of a sample project that shows list of users who have permissions to this project.

16.3.1. 添加权限

  1. 在**访问**选项卡中，单击**添加**按钮。

  2. 选择要添加的用户或团队，然后单击**下一步**

  3. 通过单击名称旁边的复选框选择列表中的一个或多个用户或团队以将其添加为成员，然后单击**下一步**。

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

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

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

../_images/organizations-add-users-roles.png

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

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

Permissions tab with Role Assignments

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

../_images/permissions-disassociate.png

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

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

16.4. 使用通知

单击**通知**选项卡，您可以查看已设置的任何通知集成。

List of notifications configured for this project.

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

如果尚未设置任何通知，您可以从左侧导航栏的**通知**链接配置它们以创建新的通知。

Notifications Templates page with no notification templates found.

有关配置各种通知类型的更多详细信息，请参阅 通知类型。

16.5. 使用作业模板

单击**作业模板**允许您添加和查看与此项目关联的任何作业模板或工作流模板。

List of job templates associated with this project.

单击使用该模板运行的最近作业以查看其详细信息和其他有用的信息。您可以根据各种标准对该列表进行排序，并执行搜索以筛选感兴趣的模板。

Job Templates tab of the project showing an example drop-down menu that can be used to filter your search.

从此视图中，您还可以启动 (launch button)、编辑 (edit button) 或复制 (copy button) 模板配置。

16.6. 使用计划

单击**计划**允许您查看为此项目设置的任何计划。

List of configured schedules that may be used with this project.

16.6.1. 计划项目

要计划项目运行，请单击**计划**选项卡。

  • 如果已设置计划；查看、编辑或启用/禁用您的计划首选项。

  • 如果尚未设置计划，请参阅 计划以获取更多信息。

16.7. Ansible Galaxy 支持

在项目更新结束时，AWX 会在 roles 目录（位于 <project-top-level-directory>/roles/requirements.yml）中搜索名为 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>。但是，您可以在“设置”窗口的“作业设置”选项卡中根据您的环境指定其他**作业执行路径**

Job Settings page showing where to configure the Job execution path.

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

默认情况下，AWX 具有一个系统范围的设置，允许从 SCM 项目的roles/requirements.yml文件动态下载角色。您可以在设置菜单的**作业设置**屏幕中关闭此设置，方法是将**启用角色下载**切换按钮切换到**关闭**。

Job Settings page showing the option to Enable Role Download.

每当项目同步运行时，AWX 都会确定项目源以及来自 Galaxy 和/或 Collections 的任何角色是否已过时。项目更新将在更新过程中下载角色。

如果作业需要获取对上游角色所做的更改，则更新项目将确保此操作发生。对角色的更改意味着一个新的提交被推送到provision-role源代码控制。要使此更改在作业中生效，您不需要将新的提交推送到playbooks存储库，但您**确实需要**更新项目，这会将角色下载到本地缓存。例如，假设您在源代码控制中有两个 Git 存储库。第一个是playbooks，AWX 中的项目指向此 URL。第二个是provision-role，它由playbooks Git 存储库内的roles/requirements.yml文件引用。

简而言之，作业会在每次作业运行之前下载最新的角色。出于性能原因，角色和集合会被本地缓存，您需要在项目 SCM 更新选项中选择**启动时更新版本**，以确保在上游角色在每次作业运行之前重新下载。

SCM update options Update Revision on Launch checked.

更新发生在比同步更早的流程中，因此错误和详细信息显示得更快，并且位置更合理。

有关requirements.yml文件语法的信息和示例，请参阅 Ansible 文档中的角色需求部分。

如果有任何应该特别公开的目录，您可以在设置屏幕的作业部分中的**要公开到隔离作业的路径**中指定这些目录，或者通过更新设置文件中的以下条目来指定。

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

注意

如果您的 playbook 需要使用在那里定义的密钥或设置，则可能要添加到AWX_ISOLATION_SHOW_PATHS的主要文件是/var/lib/awx/.ssh。

如果您在设置文件中进行了更改，请确保在保存更改后使用awx-service restart命令重新启动服务。

在用户界面中，您可以在作业设置窗口中配置这些设置。

Job Settings page showing example paths to expose to isolated jobs.

16.8. 集合支持

AWX 支持在作业运行中使用项目特定的Ansible 集合。如果您在 SCM 中的collections/requirements.yml处指定了集合需求文件，则 AWX 将在作业运行之前的隐式项目同步中安装该文件中的集合。

默认情况下，AWX 具有一个系统范围的设置，允许从 SCM 项目的collections/requirements.yml文件动态下载集合。您可以在设置菜单的**作业设置**选项卡中关闭此设置，方法是将**启用集合下载**切换按钮切换到**关闭**。

Job Settings page showing where to enable collection(s) download.

出于性能原因，角色和集合会被本地缓存，您需要在项目 SCM 更新选项中选择**启动时更新版本**以确保这一点。

SCM update options Update Revision on Launch checked.

16.8.1. 通过 Hub 使用集合

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

  1. 导航到https://cloud.redhat.com/ansible/automation-hub/token 并点击**加载令牌**。

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

Connect to Hub page showing where to copy the offline token.

  1. 要使用公共 Automation Hub，请使用复制的令牌创建一个 Automation Hub 凭据，并指向令牌页面中**服务器 URL**和**SSO URL**字段显示的 URL。

  • **Galaxy 服务器 URL** = https://cloud.redhat.com/api/automation-hub/

  • **AUTH 服务器 URL** = https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token

  1. 要使用私有 Automation Hub，请使用从本地 Automation Hub 的 Repo Management 仪表板检索到的令牌创建一个 Automation Hub 凭据，并指向如所示的已发布的 Repo URL。

The Repo Management dashboard of your local Automation Hub. The Get token button next to the published repo URL in the Repo Management dashboard of your local Automation Hub.

您可以在其中创建具有不同命名空间/集合的不同 Repo。但是，对于 Automation Hub 中的每个 Repo，您都需要创建一个不同的 Automation Hub 凭据。从 Automation Hub UI 中以https://$<hub_url>/api/galaxy/content/<repo you want to pull from>格式复制**Ansible CLI URL**到“创建凭据”表单的**Galaxy 服务器 URL**字段中。

Create New Credential form for Ansible Galaxy/Automation Hub API Token Credential Type.

  1. 导航到您希望能够从 Automation Hub 同步内容的组织，并将新的 Automation Hub 凭据添加到该组织。此步骤允许您将每个组织与您希望能够从中使用内容的 Automation Hub 凭据（即 Repo）相关联。

Edit example default organizations form with Ansible Galaxy and Automation Hub credentials.

注意

假设您有两个 Repo

  • Prod：Namespace 1和Namespace 2，每个都包含集合A和B，因此：namespace1.collectionA:v2.0.0和namespace2.collectionB:v2.0.0

  • Stage：Namespace 1，仅包含集合A，因此：namespace1.collectionA:v1.5.0在 Automation Hub 上，您将拥有Prod和Stage的 Repo URL。

您可以为每个创建一个 Automation Hub 凭据。然后，您可以为不同的组织分配不同级别的访问权限。例如，您可以创建一个“开发人员”组织，使其能够访问这两个 Repo，而“运维”组织只能访问 Automation Hub Prod Repo。

  1. 如果 Automation Hub 具有自签名证书，请点击切换按钮以启用设置**忽略 Ansible Galaxy SSL 证书验证**。对于使用签名证书的**公共 Automation Hub**，请改为点击切换按钮将其禁用。请注意，这是一个全局设置。

Job Settings page showing where to enable the option to ignore Ansible Galaxy SSL Certificate Verification.

  1. 创建一个项目，其中源存储库在位于collections/requirements.yml文件中的需求文件中指定了必要的集合。请参阅相应Ansible 文档中描述的语法。

The URL for the Source Control URL in the Type Details section of the Create New Project form.

  1. 在项目列表视图中，点击刷新按钮。以针对此项目运行更新。AWX 从collections/requirements.yml文件中获取 Galaxy 集合并将其报告为已更改；并且现在将为使用此项目的任何作业模板安装这些集合。

注意

如果需要来自 Galaxy 或 Collections 的更新，则会执行同步以下载所需的角色，从而在您的 /tmp 文件中消耗更多空间。在您拥有大型项目（约 10 GB）的情况下，/tmp上的磁盘空间可能会成为问题。

有关集合的更多信息，请参阅使用集合。