Introduction to Ansible-navigator
In simple terms, <span>ansible-navigator</span> runs Ansible tasks through containers. The <span>ansible-navigator</span> calls the <span>ansible-runner</span> API to start the container and execute tasks.
┌──────────────────────────────────────────────┐
│ 🟦 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 │
└──────────────────────────────────────────────┘I should not have drawn it wrong (a strange confidence), if I did, blame the temporary worker ChatGPT. (●ˇ∀ˇ●)
<span>ansible-navigator</span> can complete all Ansible commands through containers.
View Help Documentation
You can view the help documentation by running <span>ansible-navigator --help</span>.
You can view sub-option help documentation by running <span>ansible-navigator <subcommand> --help</span> (for example, <span>ansible-navigator run --help</span>).
[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 pageSubcommands of ansible-navigator
| Subcommand | Description | Common Use |
<span>run</span> |
Run a playbook | Execute automation tasks |
<span>exec</span> |
Run commands within the execution environment | Debugging or executing shell commands in the container environment |
<span>images</span> |
View local execution environment images | Manage EE images |
<span>builder</span> |
Build EE container images (using ansible-builder) | Customize execution environments |
<span>collections</span> |
View currently available Ansible Collections | Understand installed module packages |
<span>config</span> |
View current ansible configuration (ansible.cfg) | Quickly identify configuration sources |
<span>doc</span> |
View documentation for a module or plugin | Check usage, e.g.: <span>doc -t module ping</span> |
<span>inventory</span> |
Browse and test inventory files | View group/host structure or variables |
<span>lint</span> |
Lint a playbook or role for syntax errors | Check best practices and errors |
<span>replay</span> |
Review previously executed playbooks (artifacts) | For debugging and reviewing historical executions |
<span>settings</span> |
Display current <span>ansible-navigator</span> settings |
View configuration items and sources |
<span>welcome</span> |
Open the welcome interface (TUI mode) | Start navigation from the TUI interface |
Common Options for ansible-navigator
Basic Options
| Parameter | Meaning | Default Value |
<span>-h</span>, <span>--help</span> |
Show help information | – |
<span>--version</span> |
Show version information | – |
<span>-m</span>, <span>--mode</span> |
UI mode:<span>stdout</span> or <span>interactive</span> |
<span>interactive</span> |
<span>--tz</span> |
Set time zone (e.g. <span>utc</span>, <span>local</span>) |
<span>utc</span> |
Execution Environment Related
| Parameter | Meaning | Default Value |
<span>--ee</span>, <span>--execution-environment</span> |
Enable or disable EE containers | <span>true</span> |
<span>--eei</span>, <span>--execution-environment-image</span> |
Specify EE image name | <span>ghcr.io/ansible/community-ansible-dev-tools:latest</span> |
<span>--ce</span>, <span>--container-engine</span> |
Container engine:<span>auto</span> / <span>podman</span> / <span>docker</span> |
<span>auto</span> |
<span>--co</span>, <span>--container-options</span> |
Additional parameters for <span>docker/podman run</span> |
– |
<span>--eev</span>, <span>--execution-environment-volume-mounts</span> |
Execution environment mount paths (can be used multiple times) | – |
<span>--penv</span>, <span>--pass-environment-variable</span> |
Pass existing environment variables | – |
<span>--senv</span>, <span>--set-environment-variable</span> |
Set new variables in EE | – |
<span>--pa</span>, <span>--pull-arguments</span> |
Additional parameters when pulling images (<span>docker/podman pull</span><span> parameters, e.g. </span><code><span>--tls-verify=false</span>) |
– |
<span>--pp</span>, <span>--pull-policy</span> |
Image pull policy:<span>always</span>/<span>missing</span>/<span>never</span>/<span>tag</span> |
<span>tag</span> |
Here is an explanation of
<span>--pull-policy</span><span>:</span>
- •
<span>always</span>: Always pull the image- •
<span>missing</span>: Pull the image if not available locally- •
<span>never</span>: Never pull the image- •
<span>tag</span>: Always pull the image if the tag is<span>latest</span>, otherwise pull if not available locally
Logging and Debugging
| Parameter | Meaning | Default Value |
<span>--ll</span>, <span>--log-level</span> |
Log level (debug/info/warning/…) | <span>warning</span> |
<span>--lf</span>, <span>--log-file</span> |
Log file path (default saved to <span>ansible-navigator.log</span> in the current directory) |
– |
<span>--la</span>, <span>--log-append</span> |
Whether to append to the log file | <span>true</span> |
Related to ansible-runner
| Parameter | Meaning | Default Value |
<span>--rad</span>, <span>--ansible-runner-artifact-dir</span> |
Set the <span>artifact</span> output directory |
Creates a temporary directory under <span>/tmp</span> |
<span>--rac</span>, <span>--ansible-runner-rotate-artifacts-count</span> |
Keep the last number of execution records | No cleanup (default) |
<span>--rt</span>, <span>--ansible-runner-timeout</span> |
Runner execution timeout (seconds) | – |
<span>--rwje</span>, <span>--ansible-runner-write-job-events</span> |
Whether to write job events files | <span>false</span> |
UI and Color Control
| Parameter | Meaning | Default Value |
<span>--dc</span>, <span>--display-color</span> |
Whether to enable color output | <span>true</span> |
<span>--osc4</span>, <span>--osc4</span> |
Whether to support OSC4 color changes in the terminal | <span>true</span> |
Editor Behavior (for <span>doc</span>, <span>lint</span> etc. interactions)
| Parameter | Meaning | Default Value |
<span>--ecmd</span>, <span>--editor-command</span> |
Editor command used when opening files | <span>vi +{line_number} {filename}</span> |
<span>--econ</span>, <span>--editor-console</span> |
Whether the editor is console-based | <span>true</span> |
Collection Document Cache
| Parameter | Meaning | Default Value |
<span>--cdcp</span>, <span>--collection-doc-cache-path</span> |
Collection document cache path | <span>/root/.cache/ansible-navigator/collection_doc_cache.db</span> |
For boolean options, some boolean values require adding
<span>True/False</span>, for example,<span>--log-append false</span>.Some defaults are
<span>false</span>, and to set them to<span>true</span>, just add the option without adding<span>true</span>, for example,<span>--ansible-runner-write-job-events</span>.
Common Options for Ansible-navigator
| Parameter | Meaning | Example |
<span>-m</span>, <span>--mode</span> |
Specify running mode:<span>stdout</span> / <span>interactive</span> |
<span>--mode stdout</span> |
<span>--ee</span> |
Whether to enable execution environment (container) | <span>--ee true</span> |
<span>--eei</span> |
Execution environment image name | <span>--eei quay.io/ansible/awx-ee:24.6.1</span> |
<span>--pa</span> |
Additional parameters when pulling EE images | <span>--pa '--tls-verify=false'</span> |
<span>--pp</span> |
EE image pull policy | <span>--pp always</span> / <span>missing</span> / <span>never</span> / <span>tag</span> |
<span>--ce</span> |
Specify container engine | <span>--ce docker</span> / <span>--ce podman</span> |
<span>--co</span> |
Additional container parameters | <span>--co "--net=host"</span> |
<span>--eev</span> |
Execution environment mount paths (can be used multiple times) | <span>--eev /data:/data:Z</span> |
<span>--penv</span> |
Pass host environment variables | <span>--penv http_proxy</span> |
<span>--senv</span> |
Set new environment variables in EE | <span>--senv ANSIBLE_STDOUT_CALLBACK=debug</span> |
<span>--rad</span> |
Runner artifact output path | <span>--rad ./artifacts</span> |
<span>--ll</span> |
Log level | <span>--ll debug</span> |
<span>--lf</span> |
Log file path | <span>--lf /tmp/navigator.log</span> |
<span>--rad</span> |
Set the <span>artifact</span> output directory |
Creates a temporary directory under <span>/tmp</span> |
<span>--rac</span> |
Keep the last number of execution records | No cleanup (default) |
<span>--rt</span> |
Runner execution timeout (seconds) | – |
<span>--rwje</span> |
Whether to write job events files | <span>false</span> |
Here is an example:
[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}.jsonSome parameters, like
<span>--pa</span>,<span>--co</span>or<span>--eev</span>, are actually options added when starting the container with<span>podman</span><span> (or </span><code><span>Docker</span><span>), so I won't elaborate on them (will verify later).</span>The remaining parameters are not difficult to understand, just test them out, like
<span>--rac</span>or<span>--rad</span>will be discussed later.
Common Operations of Ansible-navigator
I have listed all subcommands and options above, but I don’t use many of them, just these:
- • Set non-interactive mode using
<span>-m stdout</span> - • Set the image used with
<span>--eei</span> - • Set the image pull policy with
<span>--pp</span> - • Set persistent parameters for
<span>ansible-navigator.yml</span> - • Set
<span>ansible-navigator</span>to save events and execution results for playback or troubleshooting - • Common sub-options:
- •
<span>run</span>: Run Playbook - •
<span>exec</span>: Run a single Ansible command - •
<span>settings</span>: View<span>ansible-navigator</span>settings, can also export a default settings file (the above<span>ansible-navigator.yml</span>) - • Use
<span>ansible-builder</span>to build Ansible execution environment container images (<span>ansible-navigator builder</span><span> can also build, but I find it less convenient)</span>