Documentation

29. 控制器使用技巧

29.1. 使用 Controller CLI 工具

automation controller 有一个功能齐全的命令行界面。如需配置和用法说明,请参阅 AWX Command Line Interface 文档。

29.2. 更改控制器管理员密码

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

awx-manage changepassword admin

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

要在创建策略时使用 Django 验证密码,请参阅 Django 密码策略

29.3. 通过命令行创建控制器管理员

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

awx-manage createsuperuser

29.4. 设置要与控制器搭配使用的跳过主机

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

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

Host tampa
Hostname 10.100.100.11
IdentityFile [privatekeyfile]

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

您还可以通过清单变量在控制器实例中添加一个跳过主机。这些变量可以在清单、组或主机级别上设置。要添加它,请导航到清单并在您选择的级别 variables 字段中添加以下变量:

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

29.5. 在使用控制器时查看 JSON 命令的 Ansible 输出

使用 automation controller 时,可以通过 API 获取命令的 Ansible 输出(JSON 格式)。

要查看 Ansible 输出,请浏览:

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

29.6. 查找并配置 Ansible 配置文件

虽然 Ansible 不需要配置文件,但操作系统软件包通常会在 /etc/ansible/ansible.cfg 中包括默认文件来进行定制。为了使用自定义 ansible.cfg 文件,请将其放在项目根目录。Automation controller 从项目根目录运行 ansible-playbook,然后在其中找到自定义 ansible.cfg 文件。在项目的其他位置中的 ansible.cfg 都会被忽略。

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

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

控制器会覆盖一些 ansible.cfg 选项。例如,控制器存储 SSH ControlMaster 套接字、SSH 代理套接字,以及每个作业临时目录中的其他每个作业运行项目,后者将传递给用于作业执行的容器。

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

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

ansible -m setup hostname

这将显示特定主机可用的所有事实 (fact) 的字典。如需更多信息,请参阅:https://docs.ansible.com/ansible/playbooks_variables.html#information-discovered-from-systems-facts

29.8. ALLOW_JINJA_IN_EXTRA_VARS 变量

设置 ALLOW_JINJA_IN_EXTRA_VARS = template 仅适用于保存的作业模板额外变量。提示的变量和问卷调查变量可从"template"中排除。此参数有三个值:template 允许使用直接保存在作业模板定义中的 Jinja(默认);never 禁用所有 Jinja 的使用(推荐使用);always 始终允许 Jinja(不建议使用它,但在需要满足之前的兼容性时可能是一个选项)。

此参数可在控制器 UI 的 Jobs Settings 屏幕中配置:

_images/settings-jobs-jinja.png

29.9. 使用 execution environments

请参阅 Automation Controller User Guide 中的 Execution Environments

29.10. 为通知配置 controllerhost 主机名

System Settings 中,您可以使用自己的主机名替换 Base URL of The Controller Host 项中的 https://controller.example.com 以更改通知主机名。

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

刷新您的控制器许可证也会更改通知主机名。automation controller 的新安装不必设置通知主机名。

29.11. 使用 curl 启动作业

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

假设作业模板 ID 为"1",控制器 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 字典,因此在对引号进行转义时,请小心谨慎。

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

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

  • 在控制器界面中,选择您的清单。

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

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

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

注解

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

29.13. 过滤控制器中动态清单源返回的实例

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

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

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

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

29.14. 在控制器中使用来自 Ansible 源的未发布的模块

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

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

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

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

29.15. 在控制器中使用回调插件

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

注解

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

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

要使用这些插件,请将回调插件 .py 文件和 playbook 放到控制器项目中的名为 /callback_plugins 的目录中。然后,在作业设置屏幕结尾部分的 Ansible Callback Plugins 字段中指定它们的路径(每行一个路径):

_images/configure-tower-jobs-callback.png

注解

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

29.16. 使用 winrm 连接到 Windows

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

添加 winrm 连接信息:

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

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

29.17. 将现有清单文件和 host/group 变量导入到控制器中

要将现有的静态清单以及附带的主机和组的变量导入控制器,您的清单应采用类似如下的结构:

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

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

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

例如,如果您只有一个清单平面文件(名为 ansible-hosts 的文件),按如下所示将其导入:

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

如果有冲突,或者覆盖名为 "My Controller Inventory" 的清单,请运行:

awx-manage inventory_import --source=inventory/ \
  --inventory-name="My Controller 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 格式设置变量格式。

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