Documentation

30. Tower 使用技巧

30.1. 使用 Tower CLI 工具

Ansible Tower 有一个功能齐全的命令行界面。如需配置和用法说明,请参阅 AWX CLI Ansible Tower documentation

30.2. 更改 Tower 管理密码

在安装过程中,会提示您输入一个管理员密码,该密码是在 Tower 中创建的 admin 超级用户/第一用户的密码。如果您通过 SSH 登录实例,它会在提示符后为您提供默认的管理员密码。如果您需要更改这个密码,请在 Tower 服务器中以 root 用户身份运行以下命令:

awx-manage changepassword admin

下一步,输入新密码。之后,您输入的新密码将作为 Web UI 中的管理员密码。

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

在一些情况下,您可能需要从命令行创建管理员(超级用户)帐户。要创建一个管理员,请以 root 用户身份在 Tower 服务器上运行以下命令,并在提示时输入管理员信息:

awx-manage createsuperuser

30.4. 设置要与 Tower 搭配使用的跳过主机

Tower 提供的凭证不会通过 ProxyCommand 流向跳过主机。设置通道连接后,这些凭证仅用于终端节点。

这需要在 ProxyCommand 定义中的 AWX 用户的 SSH 配置中配置固定的用户/密钥文件,该配置通过跳过主机设置连接。例如:

Host tampa
Hostname 10.100.100.11
IdentityFile [privatekeyfile]

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

注解

如果您需要使用跳过主机,则必须默认禁用 PRoot。您可以通过 Configure Tower 用户界面禁用 PRoot,方法是从 Jobs 选项卡中将**Enable Job Isolation** 切换设置为 OFF

_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 获取命令的 Ansible 输出(JSON 格式)。

要查看 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 都会被忽略。

要了解在这个文件中可以使用的值,请参阅 configuration file on github

您可以使用默认选项做为一个开始,并根据需要配置默认模块路径或者连接类型,以及其它功能。

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

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

Ansible 默认收集其管理下的机器的“事实 (fact)”,可在 Playbook 和模板中访问。要查看有关机器的所有可用事实 (fact) ,可以临时运行 setup 模块:

ansible -m setup hostname

这会输出特定主机所有可用事实的字典. 详情请参考: https://docs.ansible.com/ansible/playbooks_variables.html#information-discovered-from-systems-facts

30.8. 使用 Ansible Tower 的 virtualenv

Ansible Tower 3.0 和以后的版本使用 virtualenv。Virtualenv 会创建相互隔离的 Python 环境以避免因为冲突的依赖软件包和不同版本造成的问题。Virtualenv 会被每个特定的 Python 版本创建一个单独的目录来包括所有需要的可执行代码和依赖软件包。Ansible Tower 在安装时创建两个 virtualenvs,一个用于运行 Tower,另外一个用于运行 Ansible。这样,Tower 就可以在一个稳定的环境中运行,而您可以根据运行 playbook 的需要在 Ansible Python 环境中增加或更新模块。如需了解更新信息,请参阅 Python 指南中的 Virtual EnvironmentsPython virtualenv 项目。

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

Tower 还预安装了各种第三方库/SDK 支持,用于与各种云供应商(如 EC2 、OpenStack 、Azure 等)集成。另外,您也可以在此 virtualenv 中添加额外的 SDK 支持,详情如下。

注解

在将任何软件包安装到虚拟环境前,强烈建议先运行 umask 0022。不正确配置权限可能会导致 Tower 服务失败。示例如下:

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

除了在 Tower 用来运行 Ansible 的 virtualenv 中添加模块外,您还可以创建新的 virtualenv,如下所述。

30.8.1. 准备新的自定义 virtualenv

您可以指定一个不同的 virtualenv 用于在 Tower 中运行作业(Job)模板。您需要指定该这些 venv 所在的目录。您可以选择把自定义 venv 存放在``/var/lib/awx/venv/`` 中,但强烈建议您创建一个自定义目录。以下示例使用 /opt/my-envs/ 做为目录的示例,但可以使用您需要的目录路径替换它。

  1. 首先,为您的自定义 venv 创建一个目录:

$ sudo mkdir /opt/my-envs
  1. 为您的目录设置正确的写入和执行权限:

$ sudo chmod 0755 /opt/my-envs
  1. 另外,您还可以在 Tower 中指定要查找自定义 venvs 的目录,方法是将这个目录添加到 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'

如果您的 venvs 包括多个目录,请添加所有路径,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. 您新创建的 virtualenv 需要一些基本的依赖项来正确运行 playbook(例如,事实 (fact) 收集):

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

在这里,您可以安装 additional 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/``中的**每个**本地文件系统上。自定义 virtualenvs 在隔离的实例上被支持。如果您使用的是自定义的虚拟环境,则需要在您要使用的任何独立节点中复制或复制它,而不仅仅在 Tower 节点上。如需了解在容器中设置自定义虚拟环境的信息,请参考|ata| 中的 Build custom virtual environments 部分。

30.8.2. 分配自定义 virtualenv

在创建了自定义 virtualenv 后,您可以在 Organization 、Project 或 Job Template 级别上分配它以在作业运行时使用它。您可以在清单(inventory)源中设置自定义 venv 以在这个 venv 中运行清单更新。但是,从 Ansible Tower 3.5 开始,需要 Ansible 2.4 或之后的版本才可以运行清单更新。使用该清单的作业遵循自己的规则,且不会使用这个 venv。如果 SCM 清单源没有选择一个 venv,它可以使用与之连接的目录的 venv。您可以在机构(organization)中分配一个自定义 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 请求提供了所检测到的 virtualenvs 列表:

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

您还可以通过编辑 Ansible Tower 用户界面中的相应页,为 Organization、Project 和 Job Template 指定分配的虚拟环境。从 Ansible Environment 下拉菜单中选择 virtualenv,如以下示例所示:

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

启动作业模板时,您还会看到在作业详情框中指定的 virtualenv:

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

30.9. 为通知配置 towerhost 主机名

/etc/tower/conf.d/custom.py 中,您可以设置 TOWER_URL_BASE='https://tower.example.com' 以更改通知主机名,将 https://tower.example.com 替换为您首选的主机名。您必须在保存对 ansible-tower-service restart 的更改后重启 Tower 服务。

刷新您的 Tower 许可证也会更改通知主机名。Ansible Tower 3.0 的新安装不必设置通知主机名。

30.10. 使用 curl 启动作业

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

假设作业模板 ID 为“1”,您的 Tower IP 为 192.168.42.100,且 adminawxsecret 是有效的登录凭证,您可以以这种方式创建新作业:

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.11. 动态清单和私有 IP 地址

默认情况下,Tower 只显示 VPC 中具有与它们关联的弹性 IP (EIP) 地址的实例。要查看您的 VPC 实例,请执行以下步骤:

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

  • 点击来源设置为 AWS 的组,并点击 Source 选项卡。

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

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

注解

为了有效地配置这些实例,必须在 VPC 中运行 Tower,并可访问这些实例。

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

默认情况下,Tower 中的动态清单源(AWS 、RAckspace 等)返回所有使用的云凭证可用的实例。它们根据不同的属性自动加入到组中。例如,AWS 实例根据区域、标签名称和值、安全组等进行分组。要针对环境中的特定实例,请编写 playbook,它以生成组名称为目标。例如:

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

您也可以使用作业模板设置中的 Limit 字段将 playbook 运行限制为一个特定的组、多个组、主机或它们的组合。语法与 ansible-playbook 命令行上的 --limit parameter 相同。

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

30.13. 在 Tower 中使用来自于 Ansible 源的未发布的模块

如果在最新的 Ansible 核心分支中有一个您想要在 Tower 系统中使用的功能,可以按照以下方法在 Tower 中使用它。

首先,确定您要从可用的 Ansible 核心模块或 Ansible 额外模块 GitHub 库中使用的更新模块。

接下来,在名为 /library 的 Ansible 源 playbook 的同一目录级别创建新目录。

创建了这个模块后,复制您想要使用的模块,并将其拖放到 /library 目录——它就会首先通过系统模块机制被使用。当您可以通过普通的软件包管理器把这个功能更新到稳定版本后,就可以删除它。

30.14. 使用 Tower 的回调插件

Ansible 在 playbook 运行时具有处理操作的灵活方法,称为回调插件。您可以使用 Tower 的这些插件进行处理,例如在 playbook 运行或失败时通知服务、在每次 playbook 运行后发送电子邮件等。如需回调插件架构的官方文档,请参阅:http://docs.ansible.com/developing_plugins.html#callbacks

注解

Ansible Tower 不支持 stdout 回调插件,因为 Ansible 仅允许一个插件,且 Ansible Tower 已将该插件用于流传输事件数据。

您还可以查看一些示例插件,这些插件应该根据具体站点目的进行修改,比如以下网址的示例:https://github.com/ansible/ansible/tree/devel/lib/ansible/plugins/callback

要使用这些插件,请将回调插件 .py``文件和 playbook 放到 Tower 项目中的名为 ``/callback_plugins 的目录中。

注解

要使由 Ansible 提供的大部分回调可以在全局范围内应用,您必须将其添加到您的 ansible.cfgcallback_whitelist 部分。如果您有自定义回调,请参阅 Ansible 文档`Enabling callback plugins <https://docs.ansible.com/ansible/latest/plugins/callback.html#enabling-callback-plugins>`_。

30.15. 使用 winrm 连接到 Windows

默认情况下,Tower 会尝试``ssh``到主机。您需要将 winrm 连接信息添加 Windows 主机所属的组变量。您可以编辑主机所在的 Windows 组,并将变量放在组的源/编辑界面中。

添加 winrm 连接信息:

点击包含 Windows 服务器的组名称右边的 edit 按钮来编辑所选组的属性。在“variables”部分,添加以下连接信息:ansible_connection: winrm

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

30.16. 将现有清单文件和 host/group 变量导入 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 格式设置变量格式。

退出后,导入程序将正确处理转换。