16. 项目¶
Project 是 Ansible playbook 的逻辑集合。
You can manage playbooks and playbook directories by either placing them manually under the Project Base Path on your server, or by placing your playbooks into a source code management (SCM) system supported by automation controller, including Git, Subversion, and Red Hat Insights. To create a Red Hat Insights project, refer to Setting up Insights Remediations.
注解
默认情况下，项目基本路径是 /var/lib/awx/projects，但可能已被管理员修改。它在 /etc/tower/conf.d/custom.py 中配置。编辑此文件时请小心谨慎，因为不正确的设置可能会禁用您的安装。
Projects 页显示了当前可用的项目列表。默认视图为折叠状态 (Compact)，显示项目名称及其状态，但您可以扩展为查看更多信息。您可以按照各种条件对列表进行排序，然后执行搜索来过滤相关的项目。
对于列出的每个项目，您可以使用每个项目旁边的相应图标获取最新的 SCM 修订（
），复制项目属性（
）或删除项目（
）。 从 automation controller 3.7 开始，允许在运行相关任务时更新项目。 如果您有大项目（大约 10 GB），则 /tmp 可能会出现磁盘空间的问题。
Status 指示项目的状态，可能是以下之一（注意您也可以根据特定状态类型过滤您的视图）：
Pending - 已创建源控制更新但尚未排队或启动。在实际准备好由系统运行之前，任何作业（不仅仅是源控制更新）都会停留在等待状态。源控制更新未准备就绪的原因是有依赖项当前正在运行，必须等到它们都已完成，或者其配置的位置没有足够的运行容量。
Waiting - 源控制更新处于等待执行的队列中。
Running - 源控制更新当前正在进行中。
Successful - 此项目的最后源控制更新成功。
Failed - 此项目的最后源控制更新失败。
Error - 最后的源控制更新作业根本无法运行。（即将弃用。）
Canceled - 项目的最后源控制更新已被取消。
Never updated - 项目被配置用于源控制，但从未更新。
OK - 项目未被配置用于源控制，并且位于正确的位置。（即将弃用。）
Missing - 项目不存在于
/var/lib/awx/projects的项目基本路径中（适用于手动或源控制管理的项目）。
注解
凭证类型为 Manual 的项目若不重新配置为 SCM 类型的凭证，将无法更新或调度基于源控制的操作。
注解
如果删除了由其他工作项目使用的项，则会打开一条信息，列出会受到删除影响的项，并提示您确认删除。一些界面会包括无效的或以前已被删除的项，因此它们将无法运行。以下是这类信息的一个示例：
16.1. 添加新项目¶
要创建新项目，请执行以下操作：
Click the Add button, which launches the Create Project window.
在以下必填字段中输入相关信息：
名称
**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.
完成后请点击 Save。
16.1.1. 手动管理 playbook¶
在项目基本路径下创建一个或多个目录来存储 playbook（例如，/var/lib/awx/projects/）
创建 playbook 文件或将其复制到 playbook 目录中。
确保 playbook 目录和文件属于运行 automation controller 服务的同一 UNIX 用户和组。
确保权限适合 playbook 目录和文件。
如果您在添加项目路径时遇到问题，请检查项目目录和文件的权限和 SELinux 上下文设置。
警告
如果您尚未将任何 Ansible playbook 目录添加到基本项目路径，您将收到以下消息：
要纠正这个问题，请创建适当的 playbook 目录并从您的 SCM 中签出 playbook 或将 playbook 复制到适当的 playbook 目录。
16.1.2. 使用源控制管理 playbook¶
16.1.2.1. SCM Types - Git and Subversion¶
要配置 playbook 以使用源控制，在 Project Details 选项卡中：
Select the appropriate option (Git or Subversion) from the SCM Type drop-down menu list.
在以下字段中输入相关信息：
SCM URL - 请参阅工具提示
中的示例。
SCM Branch/Tag/Commit - Optionally enter the SCM branch, tags, commit hashes, arbitrary refs, or revision number (if applicable) from the source control (Git or Subversion) to checkout. Some commit hashes and refs may not be available unless you also provide a custom refspec in the next field.
SCM Refspec - 这个字段是 git 源控制特有的选项，只有熟悉并能够轻松使用 git 的高级用户才应该指定要从远程存储库下载哪些参考。更多详情请参阅 job branch overriding。
SCM Credential - 如果需要验证，请选择适当的 SCM 凭证
在 SCM Update Options 中，在适用的情况下，可以选择启动行为。
Clean - 在进行更新前删除任何本地修改。
Delete on Update - 在进行更新前删除整个本地存储库。根据存储库的大小，这可能会显著增加完成更新所需的时间。
Update Revision on Launch - 将项目的修订更新至远程源控制中的当前修订，并缓存来自 Galaxy 或 Collections 的角色目录。 Automation controller 确保本地修订版本与最新角色和集合匹配。 另外，如果作业的生成速度快于项目的同步速度，为了避免作业溢出，您可以配置一个缓存超时来为以前的项目同步缓存特定的时间（秒）。
Allow Branch Override - 允许使用这个项目的作业模板通过项目以外的指定 SCM 分支或修订来启动。如需了解更多详情，请参阅 job branch overriding。
点击 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 标签页中：
从 SCM Type 下拉菜单中选择 Red Hat Insights。
Red Hat Insights 需要一个凭证来进行身份验证。从 Credential 字段中选择可用于 Insights 的适当凭证。
在 SCM Update Options 中，在适用的情况下，可以选择启动行为。
Clean - 在进行更新前删除任何本地修改。
Delete on Update - 在进行更新前删除整个本地存储库。根据存储库的大小，这可能会显著增加完成更新所需的时间。
Update Revision on Launch - 将项目的修订更新至远程源控制中的当前修订，并缓存来自 Galaxy 或 Collections 的角色目录。 Automation controller 确保本地修订版本与最新角色和集合匹配。 另外，如果作业的生成速度快于项目的同步速度，为了避免作业溢出，您可以配置一个缓存超时来为以前的项目同步缓存特定的时间（秒）。
点击 Save 保存您的项目。
16.1.2.3. SCM 类型 - 远程归档¶
使用远程存档的 playbook 允许基于生成版本工件或发行版本的构建过程提供项目，其中包含该项目在单个存档中的所有要求。
要将 playbook 配置为使用远程存档，在 Project Details 选项卡中：
从 SCM Type 下拉菜单中选择 Remote Archive。
在以下字段中输入相关信息：
SCM URL - 需要一个远程归档的 URL，如 GitHub Release 或存储在 Artifactory 中的构建工件，并将其解包到要使用的项目路径中
SCM Credential - 如果需要验证，请选择适当的 SCM 凭证
在 SCM Update Options 中，在适用的情况下，可以选择启动行为。
Clean - 在进行更新前删除任何本地修改。
Delete on Update - 在进行更新前删除整个本地存储库。根据存储库的大小，这可能会显著增加完成更新所需的时间。
Update Revision on Launch - 不建议使用此选项，因为它会将项目的修订更新至远程源控制中的当前修订版本，并缓存来自 Galaxy 或 Collections 的角色目录。
Allow Branch Override - 不建议使用此选项，因为它允许使用此项目的作业模板使用项目以外的指定 SCM 分支或修订启动。
注解
由于此 SCM 类型旨在支持未修改工件的概念，因此建议禁用 Galaxy 集成（至少针对角色）。
点击 Save 保存您的项目。
16.2. 从源控制更新项目¶
通过选择项目并点击
按钮来更新基于 SCM 的现有项目。
注解
请注意，在添加项目设置以使用源控制后，会立即启动一个“同步”进程来从配置的源控制获取项目详情。
点击 **Status**（最左侧，项目名称旁边）下的点来获得更新过程的更多详情。
16.3. 使用权限¶
权限是指分配给此项目的权限集（基于角色的访问控制），可提供读取、修改和管理项目、清单、作业模板及其他 automation controller 元素的能力。
您可以通过 Details 标签页旁边的 Permissions 标签页来访问项目权限。这个屏幕显示目前对此项目具有权限的用户列表。这个列表可以根据 User、Role 或 Team Role 进行排序和搜索。
16.3.1. 添加权限¶
In the Access tab, click the Add button.
Select a user or team to add and click Next
Select one or more users or teams from the list by clicking the check box(es) next to the name(s) to add them as members and click Next.
In this example, two users have been selected to be added.
Select the role(s) you want the selected user(s) or team(s) to have. Be sure to scroll down for a complete list of roles. Different resources have different options available.
Click the Save button to apply the roles to the selected user(s) or team(s) and to add them as members.
The Add Users/Teams window closes to display the updated roles assigned for each user and team.
To remove roles for a particular user, click the disassociate (x) button next to its resource.
这会出现确认对话框，要求您确认解除关联。
16.4. 使用通知¶
点击 Notifications 标签页可以查看您设置的任何通知集成。
请使用切换按钮启用或禁用要与特定项目搭配使用的通知。更多详情请参阅 启用和禁用通知。
如果没有设置通知，请点击灰色框内的 NOTIFICATIONS 链接来创建新通知。
有关配置各种通知类型的其他详情，请参阅 通知类型。
16.5. 使用作业模板¶
您可以点击 Job Templates 来添加和查看与此项目关联的任何作业模板或工作流模板。点击 Expanded 可查看每个模板的详情，包括使用该模板运行的作业的状态，以及其他有用的信息。您可以按照各种条件对此列表进行排序，并通过执行搜索来过滤相关的模板。
从此视图中，您也可以启动 (
)、复制 () 或删除 () 模板配置。注意，上面的例子显示了展开的视图。
16.7. Ansible Galaxy 支持¶
在项目更新结束时，automation controller 会搜索位于 <project-top-level-directory>/roles/requirements.yml 的 roles 目录中名为 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:
缓存目录是全局项目目录中的一个子目录。内容可以从缓存位置复制到 <job private directory>/requirements_roles 位置。
默认情况下，automation controller 有一个系统范围设置，允许从 SCM 项目的 roles/requirements.yml 文件中动态下载角色。您可以通过将 Enable Role Download 切换按钮切换到 OFF，在 Settings 菜单的 Jobs settings 标签页中关闭这个设置。
每当项目同步运行时，automation controller 会决定项目源以及来自 Galaxy 和/或集合的任何角色是否已与项目不同步。项目更新将会下载更新内的角色。
如果作业需要获取上游角色的更改，更新项目会确保这种情况发生。 对角色的更改意味着新提交被推送到 provision-role 源控制。 要使这一更改在作业中生效，您不需要将新提交推送到 playbooks 仓库，但您**需要**更新项目，该项目会将角色下载到本地缓存中。例如，假设您在源控制中有两个 git 仓库。 第一个是 playbooks，automation controller 中的项目指向这个 URL。 第二个是 provision-role，它被 playbooks git repo 中的 roles/requirements.yml 文件引用。
简而言之，作业会在每个作业运行前下载最新角色。因为性能的原因，角色和集合会在本地被缓存，您需要在项目的 SCM 更新选项中选择 Update Revision on Launch，以确保上游角色在每次作业运行前都会重新下载：
更新的过程比同步要更早发生，因此在此阶段可以更快地显示错误和详细信息。
如需有关 requirements.yml 文件语法的更多信息和示例，请参阅 Ansible 文档中的 role requirements section。
如果有任何需要特别公开的目录，您可以在 Settings 界面的 Paths to Expose to Isolated Jobs 的 Jobs 部分指定，或者在设置文件中更新以下条目：
AWX_ISOLATION_SHOW_PATHS = ['/list/of/', '/paths']
注解
The primary file you may want to add to
AWX_ISOLATION_SHOW_PATHSis/var/lib/awx/.ssh, if your playbooks need to use keys or settings defined there.
如果您更改了设置文件，请确定在保存了更改后使用 automation-controller-service restart 命令重启服务。
在用户界面中，您可以在 Jobs settings 窗口中配置这些设置。
注解
Primary Galaxy Server Username 和 Primary 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）。
因为性能的原因，角色和集合会在本地缓存。您需要在项目 SCM 更新选项中选择 Update Revision on Launch 以确保：
16.8.1. 通过 Hub 使用集合¶
在 automation controller 可以使用 Automation Hub 作为集合内容的默认源前，您需要在 Automation Hub UI 中创建 API 令牌，以便在 automation controller 中指定它。您可以连接到私有 Automation Hub 或公共 Automation Hub 集合，唯一的区别是您指定哪个 URL。
导航到 https://cloud.redhat.com/ansible/automation-hub/token 并点击 Load token。
点复制图标将 API 令牌复制到剪贴板。
要使用公共 Automation Hub，请使用复制的令牌创建一个 Automation Hub 凭证，并指向令牌页面的 Server URL 和 SSO 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
要使用私有 Automation Hub，请使用本地 Automation Hub 的 Repo Management 仪表板中获取的令牌创建一个 Automation Hub 凭证，并指向公布的存储库 URL，如下所示：
您可以使用不同的命名空间/集合创建不同的仓库。 但是，对于 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>：
与 Automation Hub UI 具体相关的信息，请参阅 Managing Red Hat Certified and Ansible Galaxy Collections in Ansible Hub。
进入到您要从 Automation Hub 进行同步内容的机构，并将新的 Automation Hub 凭证添加到这个机构。此步骤允许您将每个机构与您要使用内容的 Automation Hub 凭证（例如 repo）相关联。
注解
假设您有两个仓库：
prod：
Namespace 1和Namespace 2每个都有集合A和B：namespace1.collectionA:v2.0.0和namespace2.collectionB:v2.0.0Stage:
Namespace 1只有集合A：namespace1.collectionA:v1.5.0Automation Hub，您将会有一个 Prod 和 Stage 的 repo URL。
您可以为每个创建一个 Automation Hub 凭证。然后您可以为不同机构分配不同级别的访问权限。例如，您可以创建一个 Developers 机构，两个仓库都可以被这个机构访问。另外，创建一个 Operations 机构，它只能访问 Automation Hub Prod 仓库。
与 Automation Hub UI 具体相关的信息，请参阅 Managing User Access in Ansible Hub。
如果 Automation Hub 有自签名证书，点切换启用设置 Ignore Ansible Galaxy SSL Certificate Verification。对于使用签名证书的 public Automation Hub，点切换来禁用它。请注意，这是一个全局设置：
创建一个项目，其源仓库在
collections/requirements.yml文件中指定需要的集合。请参阅 Ansible 文档中的语法： https://docs.ansible.com/ansible/latest/user_guide/collections_using.html#install-multiple-collections-with-a-requirements-file。
在 Projects 列表视图中，点
以针对此项目运行更新。Automation controller 从文件 collections/requirements.yml中获取 Galaxy 集合并按更改报告 ; 现在将使用这个项目为任何作业模板安装集合。
注解
如果需要从 Galaxy 或 Collections 进行更新，则会执行一个下载所需角色的同步，这将消耗您的 /tmp 文件中的更多空间。当您的项目较大时（大约 10 GB），/tmp 可能会导致磁盘空间的问题。
如需有关集合的更多信息，请参阅 Using Collections。如需有关红帽官方发布的、可用于直接自动化 automation controller 安装的集合信息，请参阅 AWX Ansible Collection 文档。此页面可通过您的红帽客户凭证进行访问，它是您的 Red Hat Ansible Automation Platform 订阅的一部分。