文档

30. 塔式提示和技巧

30.1. 使用 Tower CLI 工具

Ansible Tower 具有功能齐全的命令行界面。 有关配置和使用说明，请参阅AWX CLI Ansible Tower 文档。

30.2. 更改 Tower 管理员密码

在安装过程中，系统会提示您输入管理员密码，该密码用于在 Tower 中创建的 admin 超级用户/第一个用户。 如果您通过 SSH 登录到实例，它将在提示符中告诉您默认的管理员密码。 如果您需要在任何时候更改此密码，请在 Tower 服务器上以 root 用户身份运行以下命令

awx-manage changepassword admin

接下来，输入新密码。 之后，您输入的密码将用作 Web UI 中的管理员密码。

要使用 Django 在创建时为密码验证设置策略，请参阅Django 密码策略了解详细信息。

30.3. 从命令行创建 Tower 管理员

有时您可能会发现从命令行创建管理员（超级用户）帐户很有用。 要创建管理员，请在 Tower 服务器上以 root 用户身份运行以下命令，并在出现提示时输入管理员信息

awx-manage createsuperuser

30.4. 设置要与 Tower 一起使用的跳转主机

Tower 提供的凭据不会通过 ProxyCommand 传递到跳转主机。 它们仅在建立隧道连接后用于最终节点。

要使其正常工作，请在 AWX 用户的 SSH 配置中配置 ProxyCommand 定义中的固定用户/密钥文件，该定义设置了通过跳转主机的连接。 例如

Host tampa
Hostname 10.100.100.11
IdentityFile [privatekeyfile]

Host 10.100..
Proxycommand ssh -W [jumphostuser]@%h:%p tampa

注意

如果您需要使用跳转主机，则必须默认情况下禁用 PRoot。 您可以通过 Configure Tower 用户界面禁用 PRoot，方法是将作业选项卡中的“启用作业隔离”切换设置为“关闭”。

_images/configure-tower-jobs-disable-proot-job-isolation.png

您还可以通过清单变量将跳转主机添加到 Tower 实例。 这些变量可以在清单、组或主机级别设置。 要添加此内容，请导航到您的清单，并在您选择的任何级别的 variables 字段中添加以下变量

ansible_user: <user_name>
ansible_connection: ssh
ansible_ssh_common_args: '-o ProxyCommand="ssh -W %h:%p -q <user_name>@<jump_server_name>"'

30.5. 使用 Tower 时查看 JSON 命令的 Ansible 输出

使用 Ansible Tower 时，您可以使用 API 以 JSON 格式获取命令的 Ansible 输出。

要查看 Ansible 输出，请浏览到

https://<tower server name>/api/v2/jobs/<job_id>/job_events/

30.6. 查找和配置 Ansible 配置文件

虽然 Ansible 不需要配置文件，但操作系统包通常会在 /etc/ansible/ansible.cfg 中包含一个默认配置文件，以供可能的自定义。为了使用自定义的 ansible.cfg 文件，请将其放置在项目的根目录中。Ansible Tower 从项目目录的根目录运行 ansible-playbook，它将在那里找到自定义的 ansible.cfg 文件。项目中任何其他位置的 ansible.cfg 文件将被忽略。

要了解可以在此文件中使用的值，请参阅 github 上的配置文件。

使用默认值对于开始来说是可以接受的，但要知道你可以在这里配置默认模块路径或连接类型，以及其他一些东西。

Tower 会覆盖一些 ansible.cfg 选项。例如，Tower 将 SSH ControlMaster 套接字、SSH 代理套接字以及任何其他每个作业运行项存储在每个作业的临时目录中，这些目录通过 PRoot 受多租户访问控制限制保护。

30.7. 查看所有 ansible_ 变量的列表

Ansible 默认情况下会收集其管理下的机器的“事实”，这些事实可以在剧本和模板中访问。要查看机器上的所有可用事实，请将 setup 模块作为临时操作运行

ansible -m setup hostname

这将打印出该特定主机上所有可用事实的字典。有关更多信息，请参阅：https://docs.ansible.org.cn/ansible/playbooks_variables.html#information-discovered-from-systems-facts

30.8. ALLOW_JINJA_IN_EXTRA_VARS 变量

设置 ALLOW_JINJA_IN_EXTRA_VARS = template 仅适用于保存的作业模板额外变量。提示变量和调查变量不包含在“模板”中。此参数有三个值：template，允许直接在作业模板定义上使用 Jinja（默认值），never，禁用所有 Jinja 使用（推荐），以及 always，始终允许 Jinja（强烈不建议，但为了向后兼容，可以选择）。

30.9. 在 Ansible Tower 中使用 virtualenv

Virtualenv 创建独立的 Python 环境，以避免由冲突的依赖项和不同的版本造成的错误。Virtualenv 通过简单地创建一个文件夹来工作，该文件夹包含特定 Python 版本所需的所有可执行文件和依赖项。Ansible Tower 在安装期间创建两个 virtualenv——一个用于运行 Tower，另一个用于运行 Ansible。这使得 Tower 可以在稳定的环境中运行，同时允许您根据需要在 Ansible Python 环境中添加或更新模块以运行您的剧本。有关 virtualenv 的更多信息，请参阅 Python 指南的 虚拟环境 和 Python virtualenv 项目本身。

默认情况下，virtualenv 位于文件系统上的 /var/lib/awx/venv/ansible，但您可以创建自己的自定义目录并在清单导入中使用它们。这允许您选择如何运行清单导入，因为清单来源使用自定义虚拟环境。

Tower 还预先安装了各种第三方库/SDK 支持到这个 virtualenv 中，以用于其与各种云提供商（如 EC2、OpenStack、Azure 等）的集成点。您可能需要定期将额外的 SDK 支持添加到此 virtualenv 中，这将在下面更详细地介绍。

注意

强烈建议您在将任何包安装到虚拟环境之前运行 umask 0022。未能正确配置权限会导致 Tower 服务故障。以下是示例

# source /var/lib/awx/venv/ansible/bin/activate
# umask 0022
# pip install --upgrade pywinrm
# deactivate

除了将模块添加到 Tower 用于运行 Ansible 的 virtualenv 之外，您还可以创建新的 virtualenv，如下所述。

30.9.1. 准备新的自定义 virtualenv

您可以在 Tower 中指定一个不同的 virtualenv 来运行作业模板。为此，您必须指定这些 venv 所在的目录。您可以选择将自定义 venv 保留在 /var/lib/awx/venv/ 内，但强烈建议创建一个自定义目录。以下示例使用占位符目录 /opt/my-envs/，但您可以用您选择的目录路径替换它，无论何时何地指定它。

  1. 准备新的自定义 virtualenv 需要预先安装 virtualenv 包

$ sudo yum install python-virtualenv

  1. 为您的自定义 venv 创建一个目录

$ sudo mkdir /opt/my-envs

  1. 确保为您的目录提供适当的写入权限、执行权限和所有权

$ sudo chmod 0755 /opt/my-envs
$ sudo chown awx:awx /opt/my-envs

  1. 您可以选择在 Tower 中指定要查找自定义 venv 的目录，方法是将此目录添加到 CUSTOM_VENV_PATHS 设置中，如下所示

$ curl -X PATCH 'https://user:[email protected]/api/v2/settings/system/' \
    -d '{"CUSTOM_VENV_PATHS": ["/opt/my-envs/"]}'  -H 'Content-Type:application/json'

如果您在多个目录中跨越 venv，请添加所有路径，Tower 将从这些路径中聚合 venv

$ curl -X PATCH 'https://user:[email protected]/api/v2/settings/system/' \
    -d '{"CUSTOM_VENV_PATHS": ["/path/1/to/venv/", "/path/2/to/venv/", "/path/3/to/venv/"]}' \
    -H 'Content-Type:application/json'

  1. 现在已设置好 venv 目录，请在该位置创建一个虚拟环境

$ sudo virtualenv /opt/my-envs/custom-venv

注意

支持多个版本的 Python，但在 Python 3 中创建 virtualenv 的语法略有不同：$ sudo python3 -m venv /opt/my-envs/custom-venv

  1. 接下来，安装 gcc 以便能够编译 psutil

$ yum install gcc

  1. 需要 Python 头文件才能编译 psutil。在 RHEL 8 系统上成功编译 psutil 所需的软件包是 platform-python-devel

$ yum install platform-python-devel

  1. 您新创建的 virtualenv 需要一些基本依赖项才能正常运行剧本（例如，事实收集）

$ sudo /opt/my-envs/custom-venv/bin/pip install psutil

从这里开始，您可以安装您关心的其他 Python 依赖项，例如每个 virtualenv 版本的 Ansible 本身

$ sudo /opt/my-envs/custom-venv/bin/pip install -U "ansible == X.Y.Z"

或者您可以添加一个不在基本 Tower 安装中包含的额外第三方 SDK

$ sudo /opt/my-envs/custom-venv/bin/pip install -U python-digitalocean

如果您想复制它们，则可以使用 pip freeze 找到 Tower 默认 virtualenv 中包含的库

$ sudo /var/lib/awx/venv/ansible/bin/pip freeze

在集群化的 Tower 安装中，您需要确保相同的自定义 virtualenv 存在于 /opt/my-envs/ 上的每个本地文件系统上。自定义 virtualenv 在独立实例上受支持。如果您使用自定义虚拟环境，则还需要将其复制或复制到您将使用的任何独立节点上，而不仅仅是在 Tower 节点上。有关在容器中设置自定义虚拟环境的信息，请参阅Ansible Tower 管理指南的 OpenShift 部署和配置 部分。

30.9.2. 分配自定义 virtualenv

创建自定义 virtualenv 后，您可以在组织、项目或作业模板级别分配它，以便在作业运行中使用它。您可以在清单来源上设置自定义 venv 以在该 venv 中运行清单更新。使用该清单的作业遵循其自己的规则，不会使用此 venv。如果 SCM 清单来源没有选择 venv，则可以使用与其链接的项目的 venv。您可以在组织上分配自定义 venv，但如果您这样做，它不会被组织中的清单更新使用，因为它只在作业运行中使用。

以下显示了在所需级别分配自定义 venv 的正确方法。

PATCH https://awx-host.example.org/api/v2/organizations/N/
PATCH https://awx-host.example.org/api/v2/projects/N/
PATCH https://awx-host.example.org/api/v2/job_templates/N/
PATCH https://awx-host.example.org/api/v2/inventory_sources/N/

Content-Type: application/json
{
        'custom_virtualenv': '/opt/my-envs/custom-venv'
}

对 /api/v2/config/ 的 HTTP GET 请求提供检测到的已安装 virtualenv 的列表

{
        "custom_virtualenvs": [
                "/opt/my-envs/custom-venv",
                "/opt/my-envs/my-other-custom-venv",
        ],
...
}

您也可以从 Ansible Tower 用户界面中各自的编辑屏幕指定要分配给组织、项目和作业模板的 virtualenv。从Ansible 环境下拉菜单中选择 virtualenv，如以下示例所示

_images/organizations-ansible-env-virtualenv-list.png

启动作业模板时，您还将在作业详细信息窗格中看到指定的 virtualenv

_images/jobs-show-job-details-venv.png

30.10. 配置用于通知的 towerhost 主机名

在 系统设置 中，您可以用您首选的主机名替换 https://tower.example.com 中的Tower 主机的基本 URL字段，以更改通知主机名。

_images/configure-tower-system-misc-baseurl.png

刷新 Tower 许可证也会更改通知主机名。新的 Ansible Tower 安装无需设置通知主机名。

30.11. 使用 curl 启动作业

使用 Tower API 启动作业非常简单。以下是一些使用 curl 工具的简单示例。

假设您的作业模板 ID 为“1”，您的 Tower IP 为 192.168.42.100，并且 admin 和 awxsecret 是有效的登录凭据，您可以通过以下方式创建一个新作业

curl -f -k -H 'Content-Type: application/json' -XPOST \
    --user admin:awxsecret \
    http://192.168.42.100/api/v2/job_templates/1/launch/

这将返回一个 JSON 对象，您可以解析该对象并使用它提取“id”字段，该字段是新创建作业的 ID。

您还可以将额外变量传递给作业模板调用，如以下示例所示

curl -f -k -H 'Content-Type: application/json' -XPOST \
    -d '{"extra_vars": "{\"foo\": \"bar\"}"}' \
    --user admin:awxsecret http://192.168.42.100/api/v2/job_templates/1/launch/

您可以通过登录 http://192.168.42.100/api/ 并浏览各种可用对象来查看实时 API 文档。

注意

该 extra_vars 参数需要是一个包含 JSON 的字符串，而不仅仅是一个 JSON 字典，正如您所料。在转义引号等方面要小心。

30.12. 动态清单和私有 IP 地址

默认情况下，Tower 仅显示与之关联了弹性 IP (EIP) 地址的 VPC 中的实例。要查看所有 VPC 实例，请执行以下步骤

  • 在 Tower 界面中，选择您的清单。

  • 单击来源设置为 AWS 的组，然后单击来源选项卡。

  • 在“来源变量”框中，输入：vpc_destination_variable: private_ip_address

保存并触发组更新。您现在应该能够看到所有 VPC 实例。

注意

Tower 必须在 VPC 中运行才能访问这些实例，以便有效地配置它们。

30.13. 过滤 Tower 中动态清单源返回的实例

默认情况下，Tower 中的动态清单源（AWS、Google 等）会返回可用于云凭据的所有实例。它们会根据各种属性自动加入组。例如，AWS 实例会按区域、标签名称和值、安全组等进行分组。要将目标定位到环境中的特定实例，请编写您的剧本以使它们定位到生成的组名称。例如

---
- hosts: tag_Name_webserver
  tasks:
  ...

您也可以在作业模板设置中使用 Limit 字段，将剧本运行限制在某个组、多个组、主机或其组合。语法与 ansible-playbook 命令行中的 --limit parameter 相同。

您也可以通过将自动生成的组复制到自定义组中来创建自己的组。确保在动态清单源上禁用 Overwrite 选项，否则后续同步操作将删除并替换您的自定义组。

30.14. 在 Tower 中使用 Ansible 源中未发布的模块

如果您希望在 Tower 系统中利用最新 Ansible 核心分支中提供的功能，在 Tower 中使用它非常简单。

首先，确定要使用的更新模块，该模块来自可用的 Ansible 核心模块或 Ansible 附加模块 GitHub 存储库。

接下来，在 Ansible 源剧本的同一目录级别创建一个名为 /library 的新目录。

创建完成后，将要使用的模块复制到 /library 目录中 - 它将在系统模块之前被优先使用，并且可以在通过正常的包管理器更新稳定版本后将其删除。

30.15. 在 Tower 中使用回调插件

Ansible 有一种灵活的方法来处理剧本运行期间的操作，称为回调插件。您可以在 Tower 中使用这些插件来执行一些操作，例如在剧本运行或失败时通知服务、在每次剧本运行后发送电子邮件等。有关回调插件体系结构的官方文档，请参考：https://docs.ansible.org.cn/developing_plugins.html#callbacks

注意

Ansible Tower 不支持 stdout 回调插件，因为 Ansible 仅允许使用一个插件，而 Ansible Tower 已经使用该插件来流式传输事件数据。

您可能还想查看一些示例插件，这些插件应该针对特定于站点的目的进行修改，例如在以下位置可用的插件：https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback

要使用这些插件，请将回调插件 .py 文件放入名为 /callback_plugins 的目录中，该目录与剧本位于 Tower 项目的同一目录中。然后，在配置 Tower 作业设置屏幕的“Ansible 回调插件”字段中指定它们的路径（每行一个路径）

_images/configure-tower-jobs-callback.png

注意

要将大多数与 Ansible 一起提供的回调全局应用，必须将它们添加到 ansible.cfg 文件的 callback_whitelist 部分。如果您有自定义回调，请参考 Ansible 文档了解 启用回调插件。

30.16. 使用 winrm 连接到 Windows

默认情况下，Tower 会尝试 ssh 到主机。您必须将 winrm 连接信息添加到 Windows 主机所属的组变量中。要开始使用，请编辑包含 Windows 主机的 Windows 组，并将变量放在组的源/编辑屏幕中。

要添加 winrm 连接信息

通过单击包含 Windows 服务器的组名称右侧的 edit 按钮来编辑所选组的属性。在“变量”部分，添加您的连接信息，如下所示：ansible_connection: winrm

完成后，保存您的编辑。如果 Ansible 之前尝试进行 SSH 连接并失败，则应重新运行作业模板。

30.17. 将现有的清单文件和主机/组变量导入 Tower

要将现有的静态清单和随附的主机和组变量导入 Tower，您的清单应采用类似于以下结构的结构

inventory/
|-- group_vars
|   `-- mygroup
|-- host_vars
|   `-- myhost
`-- hosts

要导入这些主机和变量，请运行 awx-manage 命令

awx-manage inventory_import --source=inventory/ \
  --inventory-name="My Tower Inventory"

如果您只有一个扁平的清单文件（例如名为 ansible-hosts 的文件），请按如下方式导入它

awx-manage inventory_import --source=./ansible-hosts \
  --inventory-name="My Tower Inventory"

如果遇到冲突，或者要覆盖名为“My Tower Inventory”的清单，请运行

awx-manage inventory_import --source=inventory/ \
  --inventory-name="My Tower Inventory" \
  --overwrite --overwrite-vars

如果您收到错误，例如

ValueError: need more than 1 value to unpack

创建一个目录来保存主机文件以及 group_vars

mkdir -p inventory-directory/group_vars

然后，对于每个包含：vars 的组，创建一个名为 inventory-directory/group_vars/<groupname> 的文件，并将变量格式化为 YAML 格式。

一旦分解出来，导入器将正确处理转换。