Ansible-navigator 介绍

简单讲，ansible-navigator 就是通过容器来运行 Ansible 任务，ansible-navigator 调用 ansible-runner 接口来启动容器并执行任务。

┌──────────────────────────────────────────────┐
│ 🟦 ansible-navigator                         │
│    - Reads .ansible-navigator.yml            │
│    - Parses CLI arguments                    │
│    - Constructs execution context            │
└────────────┬─────────────────────────────────┘
             │ calls ansible-runner API
             ▼
┌──────────────────────────────────────────────┐
│ 🟨 ansible-runner (Python API)               │
│    - Builds podman/docker command            │
│    - Prepares artifacts directory structure  │
│    - Generates env.list, cmd, settings       │
└────────────┬─────────────────────────────────┘
             │ launches container
             ▼
┌──────────────────────────────────────────────┐
│ 🟩 EE Container (Execution Environment)      │
│    - Entrypoint: ansible-playbook            │
│    - Uses mounted inventory/playbook/env     │
│    - Runs tasks, connects to targets         │
└────────────┬─────────────────────────────────┘
             │ writes output
             ▼
┌──────────────────────────────────────────────┐
│ 🟪 artifacts/ (on host)                      │
│    - stdout                                  │
│    - job_events/*.json                       │
│    - command, env.list, status               │
└──────────────────────────────────────────────┘

我应该是没画错（莫名的自信），错了就怪临时工 ChatGPT。(●ˇ∀ˇ●)

ansible-navigator 可以通过容器完成 Ansible 所有的命令。

查看帮助文档

通过 ansible-navigator --help 可以查看帮助文档。

通过 ansible-navigator <subcommand> --help 可以查看子选项帮助文档（比方说 ansible-navigator run --help）。

[root@ansible-controller ansible-navigator]# ansible-navigator --help
Usage: ansible-navigator [options]

Options (global):
 -h     --help                                   Show this help message and exit
 --version                                       Show the application version and exit
 --rad  --ansible-runner-artifact-dir            The directory path to store artifacts generated by ansible-runner
 --rac  --ansible-runner-rotate-artifacts-count  Keep ansible-runner artifact directories, for last n runs, if set to 0 artifact directories won't be deleted
 --rt   --ansible-runner-timeout                 The timeout value after which ansible-runner will forcefully stop the execution
 --rwje --ansible-runner-write-job-events        Write ansible-runner job_events in the artifact directory (true|false)
 --cdcp --collection-doc-cache-path              The path to collection doc cache (default: /root/.cache/ansible-navigator/collection_doc_cache.db)
 --ce   --container-engine                       Specify the container engine (auto=podman then docker) (auto|podman|docker) (default: auto)
 --co   --container-options                      Extra parameters passed to the container engine command
 --dc   --display-color                          Enable the use of color for mode interactive and stdout (true|false) (default: true)
 --ecmd --editor-command                         Specify the editor command (default: vi +{line_number} {filename})
 --econ --editor-console                         Specify if the editor is console based (true|false) (default: true)
 --ee   --execution-environment                  Enable or disable the use of an execution environment (true|false) (default: true)
 --eei  --execution-environment-image            Specify the name of the execution environment image (default: ghcr.io/ansible/community-ansible-dev-tools:latest)
 --eev  --execution-environment-volume-mounts    Specify volume to be bind mounted within an execution environment (--eev /home/user/test:/home/user/test:Z)
 --la   --log-append                             Specify if log messages should be appended to an existing log file, otherwise a new log file will be created per session (true|false)
                                                 (default: true)
 --lf   --log-file                               Specify the full path for the ansible-navigator log file (default: /root/ansible-navigator/ansible-navigator.log)
 --ll   --log-level                              Specify the ansible-navigator log level (debug|info|warning|error|critical) (default: warning)
 -m     --mode                                   Specify the user-interface mode (stdout|interactive) (default: interactive)
 --osc4 --osc4                                   Enable or disable terminal color changing support with OSC 4 (true|false) (default: true)
 --penv --pass-environment-variable              Specify an existing environment variable to be passed through to and set within the execution environment (--penv MY_VAR)
 --pa   --pull-arguments                         Specify any additional parameters that should be added to the pull command when pulling an execution environment from a container
                                                 registry. e.g. --pa='--tls-verify=false'
 --pp   --pull-policy                            Specify the image pull policy always:Always pull the image, missing:Pull if not locally available, never:Never pull the image, tag:if the
                                                 image tag is 'latest', always pull the image, otherwise pull if not locally available (always|missing|never|tag) (default: tag)
 --senv --set-environment-variable               Specify an environment variable and a value to be set within the execution environment (--senv MY_VAR=42)
 --tz   --time-zone                              Specify the IANA time zone to use or 'local' to use the system time zone (default: utc)

Subcommands:
 {subcommand} --help
  builder                                        Build [execution environment](https://ansible.readthedocs.io/en/latest/getting_started_ee/index.html) (container image)
  collections                                    Explore available collections
  config                                         Explore the current ansible configuration
  doc                                            Review documentation for a module or plugin
  exec                                           Run a command within an execution environment
  images                                         Explore execution environment images
  inventory                                      Explore an inventory
  lint                                           Lint a file or directory for common errors and issues
  replay                                         Explore a previous run using a playbook artifact
  run                                            Run a playbook
  settings                                       Review the current ansible-navigator settings
  welcome                                        Start at the welcome page

ansible-navigator 子命令

ansible-navigator 通用选项

基础选项

执行环境相关（Execution Environment）

这里解释一下 --pull-policy：

• always：总是拉取镜像
• missing：本地没有时拉取镜像
• never：从不拉取镜像
• tag：当镜像标签为 latest 时总是拉取镜像，为其他标签时，只在本地没有时拉取镜像

日志与调试

ansible-runner 相关

UI 和颜色控制

编辑器行为（用于 doc、lint 等交互）

集合文档缓存

针对布尔值选项，有的布尔值后需要加 True/False，比方说 --log-append false。

有的是默认为 false，想要设置为 true 时，直接添加选项而不用加 true，比方说 --ansible-runner-write-job-events。

Ansible-navigator 常用选项

下边写一个例子：

[root@ansible-controller ansible-navigator]# ansible-navigator \
    --eei quay.io/ansible/awx-ee:24.6.1 --pa='--tls-verify=false' --pp missing \
    --ll debug --la false --lf ./log/ansible-navigator.log \
    -m stdout \
    run test.yml \
    --pas ./artifacts/{playbook_name}/{playbook_name}-{time_stamp}.json

有些参数，像 --pa、--co 或 --eev 等，其实就是 podman（或 Docker） 在启动容器时加的选项，就不做过多介绍了（后边会去验证）。

剩下的一些参数也不难理解，多测试看看，像 --rac 或 --rad 后边再说。

Ansible-navigator 常用操作

前边把所有子命令和选项都列出来了，不过我常用的不多，就下边这些：

• 通过 -m stdout 来设置非交互模式
• 通过 --eei 设置使用的镜像
• 通过 --pp 设置镜像拉取策略
• 通过 ansible-navigator.yml 为 ansible-navigator 设置持久化参数
• 设置 ansible-navigator 保存执行过程中的事件和执行结果，以便回放或故障排查
• 常用子选项：
  • run：跑 Playbook
  • exec：跑单条 Ansible 命令用
  • settings：查看 ansible-navigator 的设置，也可以用它导出一个默认的设置文件（就是上边那个 ansible-navigator.yml）
• 通过 ansible-builder 来构建 Ansible 执行环境容器镜像（ansible-navigator builder 也能构建，不过感觉没 ansible-builder 方便）