Ansible-navigator 其余的子命令

上次介绍了 Ansible-navigator 的 exec 和 run，这次把剩下的子命令说一遍。

Ansible-navigator welcome

ansible-navigator welcome 启动一个类似帮助文档的交互界面，用于快速了解 ansible-navigator 的使用。

[root@ansible-controller ansible-navigator]# ansible-navigator welcome \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive
 0│Welcome
 1│————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
 2│
 3│Some things you can try from here:
 4│- :collections                                    Explore available collections
 5│- :config                                         Explore the current ansible configuration
 6│- :doc <plugin>                                   Review documentation for a module or plugin
 7│- :help                                           Show the main help page
 8│- :images                                         Explore execution environment images
 9│- :inventory -i <inventory>                       Explore an inventory
10│- :log                                            Review the application log
11│- :lint <file or directory>                       Lint Ansible/YAML files (experimental)
12│- :open                                           Open current page in the editor
13│- :replay                                         Explore a previous run using a playbook artifact
14│- :run <playbook> -i <inventory>                  Run a playbook in interactive mode
15│- :settings                                       Review the current ansible-navigator settings
16│- :quit                                           Quit the application
17│
18│happy automating,
19│
20│-winston

ansible-navigator welcome 只能在交互模式运行。

Ansible-navigator config

ansible-navigator config 用于在容器内查看 Ansible 的配置文件（相当于在容器内执行 ansible-config 命令），可用选项如下：

参数	类型	默认值	说明
`-c`, `--config`	`str`	自动查找（按 Ansible 的默认查找顺序）	指定要使用的 `ansible.cfg` 配置文件路径
`--hc`, `--help-config`	`bool`	不加参数表示 `false`，加参数表示 `true`	显示 `ansible-config` 命令的帮助（stdout 模式下）

查看 config 帮助：

[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive config --hc
usage: ansible-config [-h] [--version] [-v] {list,dump,view,init} ...

View ansible configuration.

positional arguments:
  {list,dump,view,init}
    list                Print all config options
    dump                Dump configuration
    view                View configuration file
    init                Create initial configuration

optional arguments:
  --version             show program's version number, config file location, configured module search path, module location, executable location and exit
  -h, --help            show this help message and exit
  -v, --verbose         Causes Ansible to print more debug messages. Adding multiple -v will increase the verbosity, the builtin plugins currently evaluate up to -vvvvvv. A reasonable level to
                        start is -vvv, connection debugging might require -vvvv.

以交互模式查看 ansible.cfg 的配置：

[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive config -c ansible.cfg

交互模式好像只能查看配置。

以非交互模式查看配置：

# 查看帮助
[root@ansible-controller ansible-navigator]# ansible-navigator config --hc

# 查看当前配置
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout config view -c ansible.cfg
[defaults]
inventory=./inventory
host_key_checking=False
fact_caching=jsonfile
fact_caching_connection=./cache

其实就是在容器里执行 ansible-config 命令，更详细的可以看看 ansible-config -h，用的不多，多数时候用它初始化配置文件。

Ansible-navigator doc

ansible-navigator doc 通过容器执行 ansible-doc 命令。

可用选项：

选项 / 参数名	类型	默认值	说明
`--hd`, `--help-doc`	`bool`	无	控制是否以标准输出形式展示 `ansible-doc` 的帮助信息（`true` 或 `false`）。
`plugin_name`	`str`	无	指定要查看文档的插件名称，例如 `copy`、`ping`、`lineinfile` 等。
`-t`, `--type`	`str`	`module`	指定插件类型，例如：`become`、`callback`、`inventory`、`lookup`、`module`、`role` 等等。

支持的插件类型包括：

become：权限提升插件
cache：缓存插件
callback：回调插件（如 JSON、YAML 输出）
cliconf：网络设备 CLI 插件
connection：连接插件（如 ssh、local）
filter：Jinja2 过滤器插件
httpapi：HTTP API 插件
inventory：主机清单插件
keyword：关键字插件（少用）
lookup：查找插件（如 env、file）
module：模块（Ansible 的核心功能）
netconf：网络设备 NETCONF 插件
role：角色
shell：Shell 插件
strategy：执行策略插件（如 linear、free）
test：Jinja2 测试插件
vars：变量插件

这个也是分交互和非交互，交互只能查看某个插件的帮助文档，其他的只能非交互：

# 查看帮助
[root@ansible-controller ansible-navigator]# ansible-navigator doc --hd

# 交互运行，查看某个插件帮助文档
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive doc ansible.builtin.ping

# 非交互运行，列出属于模块类型的插件
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout doc -t module -l

Ansible-navigator images

ansible-navigator images 用于查看可用的容器执行环境镜像，并查看详细信息。

选项	类型	默认值	说明
`--fmt`, `--format`	`str`	`yaml`	指定输出格式，可选：`json` 或 `yaml`，控制 stdout 输出的格式。
`-d`, `--details`	`str`	`everything`	指定要显示的执行环境详细信息内容，可选：

ansible_collections：已安装的 Ansible 集合
ansible_version：Ansible 的版本
os_release：基础操作系统信息
python_packages：Python 包信息
python_version：Python 版本
redhat_release：Red Hat 版本（如适用）
system_packages：系统包信息
everything：全部信息（默认）

# 以交互模式查看所有可用镜像信息
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive images
  Image                           Tag       Execution environment     Created         Size
0│ansible-ee-rocky8.10-py3.9      2.12.10   True                      13 days ago     231 MB
1│awx-ee                          24.6.1    True                      11 months ago   1.84 GB
2│community-ansible-dev-tools     latest    True                      3 days ago      1.3 GB
3│community-ee-base               2.17.3-1  True                      8 months ago    344 MB
4│fedora41-test-container         9.2.0     False                     4 months ago    610 MB
# 这里可以看到前四个镜像是支持 ansible-navigator 的

# 以非交互模式查看某个镜像的信息
[root@ansible-controller ansible-navigator]# ansible-navigator images \
    --mode stdout --eei ghcr.io/ansible-community/ansible-community/community-ee-base:2.17.3-1 \
    -d os_release -d python_version --fmt yaml
---
image_name: ghcr.io/ansible-community/ansible-community/community-ee-base:2.17.3-1
os_release:
  details:
  - ansi-color: 0;38;2;60;110;180
    bug-report-url: https://bugzilla.redhat.com/
    cpe-name: cpe:/o:fedoraproject:fedora:40
    default-hostname: fedora
    documentation-url: https://docs.fedoraproject.org/en-US/fedora/f40/system-administrators-guide/
    home-url: https://fedoraproject.org/
    id: fedora
    logo: fedora-logo-icon
    name: Fedora Linux
    platform-id: platform:f40
    pretty-name: Fedora Linux 40 (Container Image)
    redhat-bugzilla-product: Fedora
    redhat-bugzilla-product-version: '40'
    redhat-support-product: Fedora
    redhat-support-product-version: '40'
    support-end: '2025-05-13'
    support-url: https://ask.fedoraproject.org/
    variant: Container Image
    variant-id: container
    version: 40 (Container Image)
    version-codename: ''
    version-id: '40'
python_version:
  details:
    version: 3.12.5 (main, Aug 23 2024, 00:00:00) [GCC 14.2.1 20240801 (Red Hat 14.2.1-1)]

这里注意格式，想看哪个镜像的信息就使用 --eei 设置哪个镜像。

关于如何检测镜像是否支持 ansible-navigator，是通过镜像标签识别的，支持 ansible-navigator 的镜像含有标签 ansible-execution-environment": "true"。

[root@ansible-controller ansible-navigator]# podman image inspect \
    ghcr.io/ansible-community/ansible-community/community-ee-base:2.17.3-1 \
    -f json | jq .[0].Config.Labels
{
  "ansible-execution-environment": "true",
  "io.buildah.version": "1.23.1",
  "license": "MIT",
  "name": "fedora",
  "org.opencontainers.image.license": "MIT",
  "org.opencontainers.image.name": "fedora",
  "org.opencontainers.image.url": "https://fedoraproject.org/",
  "org.opencontainers.image.vendor": "Fedora Project",
  "org.opencontainers.image.version": "40",
  "vendor": "Fedora Project",
  "version": "40"
}

Ansible-navigator inventory

ansible-navigator inventory 用于在镜像内执行 ansible-inventory。

选项	类型	默认值	说明
`--hi`, `--help-inventory`	`bool`	无	控制是否以标准输出模式显示 `ansible-inventory` 的帮助信息。加这个选项就是 `true`，不加就是 `false`。
`-i`, `--inventory`	`str`	无	指定清单文件路径或逗号分隔的主机列表。例如：`-i inventory.yml` 或 `-i host1,host2,`。
`--ic`, `--inventory-column`	`str`	无	指定在主机列表视图中要显示的主机属性，只能看在主机清单中定义的变量（部分魔法变量），仅在 TUI 模式下有效。

# 查看帮助
[root@ansible-controller ansible-navigator]# ansible-navigator inventory --hi

# 交互式查看主机清单
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive inventory -i inventory
  Title                      Description
0│Browse groups              Explore each inventory group and group members members
1│Browse hosts               Explore the inventory with a list of all hosts
# 按 1 看主机
  Inventory hostname
0│master1
1│worker1

# 交互式查看主机并显示特定变量
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive inventory -i inventory \
    --ic inventory_hostname --ic ansible_ssh_host --ic ansible_ssh_user
# 直接看主机内容
  Inventory hostname     Inventory hostname     Ansible ssh host    Ansible ssh user
0│master1                master1                192.168.221.142     ansible
1│worker1                worker1                192.168.221.143     ansible

# 非交互查看主机清单
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout inventory -i inventory \
    --list --yaml
all:
  children:
    k8s:
      hosts:
        master1:
          HOSTNAME: master1.example.com
          ansible_ssh_host: 192.168.221.142
          ansible_ssh_password: redhat
          ansible_ssh_user: ansible
        worker1:
          HOSTNAME: worker1.example.com
          ansible_ssh_host: 192.168.221.143
          ansible_ssh_password: redhat
          ansible_ssh_user: ansible

Ansible-navigator lint

ansible-navigator lint 在容器内执行 ansible-lint，用于分析和检查 Ansible Playbook、角色和任务中潜在问题。

选项 / 参数名	类型	默认值	说明
`--lic`, `--lint-config`	`str`	无	指定 `ansible-lint` 的配置文件路径（如 `.ansible-lint` 或 `ansible-lint.yml`）。
`lintables`	`path`	无	要执行 `ansible-lint` 检查的文件或目录路径，可以是 Playbook、角色、任务等。

[root@ansible-controller ansible-navigator]# ansible-navigator \
    --ee false lint test.yml
ansible-lint 25.4.0 using ansible-core:2.18.6 ansible-compat:25.5.0 ruamel-yaml:0.18.10 ruamel-yaml-clib:0.2.12
name[casing]: All names should start with an uppercase letter.
test.yml:2:9

yaml[trailing-spaces]: Trailing spaces
test.yml:5

name[casing]: All names should start with an uppercase letter.
test.yml:6:11 Task/Handler: debug

yaml[indentation]: Wrong indentation: expected at least 3
test.yml:6

fqcn[action-core]: Use FQCN for builtin module actions (debug).
test.yml:7:5 Use `ansible.builtin.debug` or `ansible.legacy.debug` instead.

yaml[trailing-spaces]: Trailing spaces
test.yml:7

前边一直说 ansible-navigator 是在容器内执行命令，其他也可以直接在物理机执行，设置 --ee false 就行，这里设置是因为用的镜像不带 ansible-lint 命令，如果镜像带 ansible-lint 命令就可以通过容器去运行了。

Ansible-navigator collections

ansible-navigator collections 查看容器内可用的集合。

选项	类型	默认值	说明
`--fmt`, `--format`	`str`	`yaml`	指定标准输出的格式，支持 `json` 或 `yaml` 格式

# 交互模式查看集合
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive collections

# 非交互模式查看集合
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout collections --fmt json

Ansible-navigator settings

ansible-navigator settings 用于查看和初始化 ansible-navigator 的设置，可用选项如下：

选项	类型	默认值	说明
`--se`, `--effective`	`bool`	无	显示当前生效的所有配置，包括默认值、CLI 参数、环境变量、设置文件等的合并结果。（加这个选项表示 `true`）
`--gs`, `--sample`	`bool`	无	生成一个可用于修改的设置文件示例。（加这个选项表示 `true`）
`--ss`, `--schema`	`str`	`json`	生成设置文件的 schema 结构（目前仅支持 `json` 格式，符合 JSON Schema draft-07 标准）。
`--so`, `--sources`	`bool`	无	显示每一项设置的来源（是默认值、环境变量、命令行参数，还是设置文件）。（加这个选项表示 `true`）

# 交互式查看配置
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive settings

# 非交互查看配置
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout settings --se

# 初始化一个配置
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout settings --gs > ansible-navigator
[root@ansible-controller ansible-navigator]# mv ansible-navigator ansible-navigator.yaml

在初始化配置的时候，并没有直接当默认配置导入到 ansible-navigator.yaml，这是因为重定向内容到文件时会先创建空文件 ansible-navigator.yaml，因为内容为空所以会导致命令执行失败，所以需要先将默认配置输出到一个其他名字文件，然后改名成 ansible-navigator.yaml。

[root@ansible-controller test]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout --ll debug settings --gs > ansible-navigator.yaml
Warning: Issues were found while applying the settings.
   Hint: Command provided: '--eei quay.io/ansible/awx-ee:24.6.1 -m stdout --ll
         debug settings --gs'

  Error: Settings file found /tmp/test/ansible-navigator.yaml, but failed to
         load it.
           error was: 'Settings file cannot be empty.'
   Hint: Try checking the settings file '/tmp/test/ansible-navigator.yaml'and
         ensure it is properly formatted

   Note: Configuration failed, using default log file location.
         (/tmp/test/ansible-navigator.log) Log level set to debug
   Hint: Review the hints and log file to see what went wrong.

这里只介绍这个命令怎么用，关于配置的详细信息后边单独解释。

Ansible-navigator replay

ansible-navigator replay 用于对执行过的 Playbook 任务结果进行回访，它没有特殊选项。

# 交互模式查看
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m interactive \
    replay artifacts/test/test-artifact-2025-05-30T15\:55\:35.891605+00\:00.json

# 非交互模式查看
[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout \
    replay artifacts/test/test-artifact-2025-05-30T15\:55\:35.891605+00\:00.json

PLAY [Ansible playbook test] ***************************************************

TASK [Gathering Facts] *********************************************************
ok: [worker1]
ok: [master1]

TASK [Print "Hello World!"] ****************************************************
ok: [master1] => {
    "msg": "Hello World!"
}
ok: [worker1] => {
    "msg": "Hello World!"
}

PLAY RECAP *********************************************************************
master1                    : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
worker1                    : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

关于回放文件的位置看前边 ansible-navigator run 章节。

Ansible-navigator builder

ansible-navigator builder 用于构建 Ansible 执行环境镜像。

选项	参数类型	默认值	说明
`--hb`, `--help-builder`	`bool`	无	是否以标准输出模式显示 `ansible-builder` 的帮助信息，取值为 `true` 或 `false`。
`--bwd`, `--workdir`	`str`	当前目录	指定包含 `ansible-builder` 清单文件（如 `execution-environment.yml`）的目录路径。

[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 -m stdout \
    builder --workdir /tmp/test/ build --tag test:v1 -vvv

除了这个还可以用 ansible-builder 命令来进行构建。

关于如何构建 Ansible 执行环境镜像后边在说。