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),只显示项目名称及其状态,但您可以使用每个条目旁边的箭头展开以了解更多信息。
对于列出的每个项目,您可以使用每个项目旁边的相应图标获取最新的 SCM 修订 ()、编辑项目 () 或复制项目属性 ()。在相关作业运行时允许更新项目。如果您的项目太大(10 GB 左右),则 /tmp
上的磁盘空间可能会出现问题。
Status 指示项目的状态,可能是以下之一(注意您也可以根据特定状态类型过滤您的视图):
Pending - 已创建源控制更新但尚未排队或启动。在实际准备好由系统运行之前,任何作业(不仅仅是源控制更新)都会停留在等待状态。源控制更新未准备就绪的原因是有依赖项当前正在运行,必须等到它们都已完成,或者其配置的位置没有足够的运行容量。
Waiting - 源控制更新处于等待执行的队列中。
Running - 源控制更新当前正在进行中。
Successful - 此项目的最后源控制更新成功。
Failed - 此项目的最后源控制更新失败。
Error - 最后的源控制更新作业根本无法运行。(即将弃用。)
Canceled - 项目的最后源控制更新已被取消。
Never updated - 项目被配置用于源控制,但从未更新。
OK - 项目未被配置用于源控制,并且位于正确的位置。(即将弃用。)
Missing - 项目不存在于 /var/lib/awx/projects
的项目基本路径中(适用于手动或源控制管理的项目)。
注解
凭证类型为 Manual 的项目若不重新配置为 SCM 类型的凭证,将无法更新或调度基于源控制的操作。
注解
如果删除了由其他工作项目使用的项,则会打开一条信息,列出会受到删除影响的项,并提示您确认删除。一些界面会包括无效的或以前已被删除的项,因此它们将无法运行。以下是这类信息的一个示例:
要创建新项目,请执行以下操作:
点 Add 按钮,启动 Create Project 窗口。
在以下必填字段中输入相关信息:
名称
**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。
在项目基本路径下创建一个或多个目录来存储 playbook(例如,/var/lib/awx/projects/)
创建 playbook 文件或将其复制到 playbook 目录中。
确保 playbook 目录和文件属于运行 automation controller 服务的同一 UNIX 用户和组。
确保权限适合 playbook 目录和文件。
如果您在添加项目路径时遇到问题,请检查项目目录和文件的权限和 SELinux 上下文设置。
警告
如果您尚未将任何 Ansible playbook 目录添加到基本项目路径,您将收到以下消息:
要纠正这个问题,请创建适当的 playbook 目录并从您的 SCM 中签出 playbook 或将 playbook 复制到适当的 playbook 目录。
要配置 playbook 以使用源控制,在 Project Details 选项卡中:
从 SCM Type 下拉菜单中选择适当的选项(Git 或 Subversion)。
在以下字段中输入相关信息:
SCM URL - 请参阅工具提示 中的示例。
**SCM Branch/Tag/Commit**(可选)- 输入源控制(Git 或 Subversion)中的 SCM 分支、标签、提交散列、任意 refs 或修订号(若适用)以签出。除非您在下一字段中还提供了自定义 refspec,否则某些提交散列和 refs 可能无法使用。如果留空,则默认为 HEAD,这是该项目的最近的签出分支/标签/提交。
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 非常相似。使用它不会给您的系统带来任何改变或损害。
要配置 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 保存您的项目。
使用远程存档的 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 保存您的项目。
通过选择项目并点 按钮来更新基于 SCM 的现有项目。
注解
请注意,在添加项目设置以使用源控制后,会立即启动一个“同步”进程来从配置的源控制获取项目详情。
点 Status 列下项目的状态,以获取有关更新过程的更多详情。
权限是指分配给此项目的权限集(基于角色的访问控制),可提供读取、修改和管理项目、清单、作业模板及其他 automation controller 元素的能力。
您可以通过 Details 标签页旁边的 Access 标签页访问项目权限。此屏幕显示目前对此项目具有权限的用户列表。该列表可以根据 Username、First Name 或 Last Name 进行排序和搜索。
在 Access 选项卡中,点 Add 按钮。
选择要添加的用户或团队并点 Next
点名称旁边的复选框从列表中选择一个或多个用户或团队,将它们添加为成员并点 Next。
在这个示例中,选择了两个用户来添加。
选择您希望所选用户或团队具有的角色。请确保向下滚动以获得完整的角色列表。不同的资源有不同的可用选项。
点 Save 按钮将角色应用到所选用户或团队,并将它们添加为成员。
将关闭 Add Users/Teams 窗口,以显示为每个用户和团队分配的更新角色。
若要删除特定用户的角色,可单击其资源旁边的解除关联(x)按钮。
这会出现确认对话框,要求您确认解除关联。
点击 Notifications 标签页可以查看您设置的任何通知集成。
请使用切换按钮启用或禁用要与特定项目搭配使用的通知。更多详情请参阅 启用和禁用通知。
如果没有设置通知,您可以从左侧导航栏中的 Notifications 链接配置它们,以创建新通知。
有关配置各种通知类型的其他详情,请参阅 通知类型。
您可以点击 Job Templates 来添加和查看与此项目关联的任何作业模板或工作流模板。
点使用该模板运行的作业的状态来查看其详细信息和其他有用信息。您可以根据各种条件对列表进行排序,并执行搜索来过滤相关的模板。
从此视图中,您还可以启动 () 或编辑 () 模板配置。
您可以点击 Schedules 来查看为此项目设置的所有计划。
在项目更新结束时,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']
注解
如果 playbook 需要使用在
/var/lib/awx/.ssh
中定义的密钥或设置,则需要把它做为主文件添加到AWX_ISOLATION_SHOW_PATHS
。
如果您更改了设置文件,请确定在保存了更改后使用 automation-controller-service restart
命令重启服务。
在用户界面中,您可以在 Jobs settings 窗口中配置这些设置。
注解
Primary Galaxy Server Username 和 Primary Galaxy Server Password 字段在 automation controller 3.8 中无法进行配置。我们推荐使用令牌访问 Galaxy 或 Automation Hub。
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 以确保:
在 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.0
Stage: Namespace 1
只有集合 A
:namespace1.collectionA:v1.5.0
Automation 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 订阅的一部分。