Ansible Navigator Cheat Sheet
ansible-navigator is the new command line utility (CLI) introduced in Ansible Automation Platform 2, for running and developing Ansible automation content. ansible-navigator can be used to execute a playbook as follows.
$ ansible-navigator run site.yaml -m stdoutNew to Ansible Automation Platform 2 ? Read Introducing Red Hat Ansible Automation Platform 2.1 for more details.
ansible-navigator also has the Text User Interface (TUI) which will help you to visualize the Ansible execution better than the ansible-playbook command.
$ ansible-navigator run site.yamlAnsible navigator can be installed using multiple methods as follows.
## Using Python
$ python3 -m pip install ansible-navigator --user
## Using package manager on RHEL
## A subscription is required
$ dnf install \
--enablerepo=ansible-automation-platform-2.2-for-rhel-8-x86_64-rpms \
ansible-navigatorRefer to the navigator installation document or the Red Hat documentation to learn more.
The changes are very easy to adopt and commands are self-explanatory subsets.
| Old individual commands | ansible-navigator subcommands |
|---|---|
ansible | ansible-navigator exec -- ansible |
ansible-playbook | ansible-navigator run |
ansible-doc | ansible-navigator doc |
ansible-config | ansible-navigator config |
ansible-inventory | ansible-navigator inventory |
ansible-inventory | ansible-navigator inventory |
ansible-builder | ansible-navigator builder |
ansible-galaxy | ansible-navigator exec -- ansible-galaxy … |
ansible-lint | ansible-navigator lint |
ansible-test | ansible-navigator exec -- ansible-test … |
ansible-vault | ansible-navigator exec -- ansible-vault … |
ansible-navigator --help will show the details help page of ansible-navigator utility including the options, arguments and subcommands to available.
$ ansible-navigator --help
usage: ansible-navigator [-h] [--version] [--rad ANSIBLE_RUNNER_ARTIFACT_DIR] [--rac ANSIBLE_RUNNER_ROTATE_ARTIFACTS_COUNT] [--rt ANSIBLE_RUNNER_TIMEOUT]
[--cdcp COLLECTION_DOC_CACHE_PATH] [--ce CONTAINER_ENGINE] [--dc DISPLAY_COLOR] [--ecmd EDITOR_COMMAND] [--econ EDITOR_CONSOLE]
[--ee EXECUTION_ENVIRONMENT] [--eei EXECUTION_ENVIRONMENT_IMAGE]
[--eev EXECUTION_ENVIRONMENT_VOLUME_MOUNTS [EXECUTION_ENVIRONMENT_VOLUME_MOUNTS ...]] [--la LOG_APPEND] [--lf LOG_FILE] [--ll LOG_LEVEL] [-m MODE]
[--osc4 OSC4] [--penv PASS_ENVIRONMENT_VARIABLE [PASS_ENVIRONMENT_VARIABLE ...]] [--pp PULL_POLICY]
[--senv SET_ENVIRONMENT_VARIABLE [SET_ENVIRONMENT_VARIABLE ...]]
{subcommand} --help ...
optional arguments:
-h, --help show this help message and exit
...output omitted...
ansible-navigator welcome will show the text user interface (TUI) of Ansible Navigator with instructions and subcommands. (You will get the same interface when you execute ansible-navigator without any arguments)
You can execute the subcommands from the same TUI like a dashboard.
:doc -Checking documentation
:doc dnfIt will load the result in the same TUI interface.
DNF (MODULE)
0│---
1│doc:
2│ author:
3│ - Igor Gnatenko (@ignatenkobrain) <[email protected]>
4│ - Cristian van Ee (@DJMuggs) <cristian at cvee.org>
5│ - Berend De Schouwer (@berenddeschouwer)
6│ - Adam Miller (@maxamillion) <[email protected]>
7│ collection: ansible.builtin
8│ description:
9│ - Installs, upgrade, removes, and lists packages and groups with the I(dnf) package
10│ manager.
11│ filename: /usr/lib/python3.8/site-packages/ansible/modules/dnf.py
12│ has_action: false
13│ module: dnf
14│ notes:
15│ - When used with a `loop:` each package will be processed individually, it is much
16│ more efficient to pass the list directly to the `name` option.
17│ - Group removal doesn't work if the group was installed with Ansible because upstream
18│ dnf's API doesn't properly mark groups as installed, therefore upon removal the
19│ module is unable to detect that the group is installed (https://bugzilla.redhat.com/show_bug.cgi?id=1620324
...output omitted... We can also use the execution environment here and see the documentation from included content as follows.
$ ansible-navigator doc -l -eei ee-supported-rhel8 -:run – Execute the playbook
:run site.ymlYou can go back to the previous window at any time by pressing the Esc button. You can exit from the TUI at any time by Esc followed by :q (or :quit)
Subcommands are available to use and replace old ansible-* utilities (eg: ansible-playbook, ansible-config etc).
Subcommands:
{subcommand} --help
collections Explore available collections
config Explore the current ansible configuration
doc Review documentation for a module or plugin
images Explore execution environment images
inventory Explore an inventory
replay Explore a previous run using a playbook artifact
run Run a playbook
welcome Start at the welcome pageList and explore the current ansible configuration.
$ ansible-navigator config OPTION DEFAULT SOURCE VIA CURRENT VALUE
0│ACTION_WARNINGS True default default True
1│AGNOSTIC_BECOME_PROMPT True default default True
2│ALLOW_WORLD_READABLE_TMPFILES True default default False
3│ANSIBLE_CONNECTION_PATH True default default None
4│ANSIBLE_COW_ACCEPTLIST True default default ['bud-frogs', 'bunny', 'cheese', 'daemon', 'default', 'd
5│ANSIBLE_COW_PATH True default default None
6│ANSIBLE_COW_SELECTION True default default default
7│ANSIBLE_FORCE_COLOR True default default False
8│ANSIBLE_NOCOLOR True default default False
9│ANSIBLE_NOCOWS True default default False
10│ANSIBLE_PIPELINING True default default False
11│ANY_ERRORS_FATAL True default default False
12│BECOME_ALLOW_SAME_USER True default default False
^f/PgUp page up ^b/PgDn page down ↑↓ scroll esc back [0-9] goto :help helpExplore the ansible documentation for modules and plugins.
$ ansible-navigator doc ping
List and explore container images for the Ansible execution environment.
$ ansible-navigator images
List and explore available collections.
$ ansible-navigator collections
Execute the playbook with a more summarised output instead of logs and details.
$ ansible-navigator run site.yml -m stdout
If you want to get the standard output the same as the ansible-playbook command, then add -m stdout at the end of your ansible-navigator run command as below.
$ ansible-navigator run site.yml -m stdoutRun a command within an execution environment
# Check Ansible version inside the Execution Environment
$ ansible-navigator exec -- ansible --version
ansible [core 2.15.3]
config file = /home/iamgini/ansible-bau/ansible-jboss-automation/ansible.cfg
configured module search path = ['/home/runner/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
ansible python module location = /usr/lib/python3.9/site-packages/ansible
ansible collection location = /home/iamgini/ansible-bau/ansible-jboss-automation/collections:/home/runner/.ansible/collections/ansible_collections:/usr/share/ansible/collections/ansible_collections
executable location = /usr/bin/ansible
python version = 3.9.16 (main, May 31 2023, 12:21:58) [GCC 8.5.0 20210514 (Red Hat 8.5.0-18)] (/usr/bin/python3.9)
jinja version = 3.1.2
libyaml = True
# Execute an adhoc command
$ ansible-navigator exec -- ansible all -m ping
localhost | SUCCESS => {
"ansible_facts": {
"discovered_interpreter_python": "/usr/libexec/platform-python"
},
"changed": false,
"ping": "pong"
}
rhel8-jboss | SUCCESS => {
"ansible_facts": {
"discovered_interpreter_python": "/usr/libexec/platform-python"
},
"changed": false,
"ping": "pong"
}You can replay the execution by using the artefacts from the previous run but you need to enable the saving of artefacts in the ansible-navigator.yml configurations.
---
ansible-navigator:
playbook-artifact:
enable: True
replay: artifacts/ansible_artifact.json
save-as: artifacts/ansible_artifact.jsonlWhen you execute the ansible-navigator run artefacts will be saved in the location.
$ ls -l artifacts/
total 36
-rw-rw-r--. 1 rhel rhel 36560 Dec 12 07:53 ansible_artifact.jsonlNow you can use this artefact to replay the execution and see the details.
$ ansible-navigator replay artifacts/ansible_artifact.jsonl List and explore the inventory details.
Review the current ansible-navigator settings and list sample settings file.
$ ansible-navigator settings --sample
---
ansible-navigator:
# ansible:
# config:
# # Help options for ansible-config command in stdout mode
# help: False
# # Specify the path to the ansible configuration file
# path: ./ansible.cfg
# # Extra parameters passed to the corresponding command
# cmdline: "--forks 15"
...<omitted for brevity>...
# settings:
# # Show the effective settings. Defaults, CLI parameters, environment
# # variables, and the settings file will be combined
# effective: False
# # Generate a sample settings file
# sample: False
# # Generate a schema for the settings file ('json'= draft-07 JSON Schema)
# schema: json
# # Show the source of each current settings entry
# sources: False
# # Specify the IANA time zone to use or 'local' to use the system time
# # zone
# time-zone: UTCYou can configure ansible-navigator on the project level by configuring ansible-navigator.yml in the project directory (same as ansible.cfg for project-specific configuration). For the ansible-navigator configurations, currently the following are checked and the first match is used:
ANSIBLE_NAVIGATOR_CONFIG(settings file path environment variable if set)./ansible-navigator(project directory)~/.ansible-navigator(home directory)
The settings file can be in JSON or YAML format.
You can configure the execution environments, development styles, and even the code editor details.
$ cat ansible-navigator.yml
---
ansible-navigator:
execution-environment:
container-engine: podman
image: ee-supported-rhel8:2.0.0
enabled: false
playbook-artifact:
save-as: /home/devops/playbook-artifacts/{playbook_name}-artifact-{ts_utc}.json
logging:
level: debug
editor:
command: code-server {filename}
console: false
playbook-artifact:
enable: True
replay: artifacts/ansible_artifact.json
save-as: artifacts/ansible_artifact.jsonlYou can configure the file as per your project and development requirements. Eg: here the editor -> code-server helps to open the playbook in VSCode editor (Learn more about code server) instead of editing the playbook in vim or nano.
$ code-server site.ymlResources
- Check ansible-navigator GitHub repo and documentation for more details.
- Ansible Navigator Creator Guide
- Ansible Builder Guide
- What’s new in Ansible Automation Platform 2: automation content navigator (Ansible Blog)
Disclaimer:
The views expressed and the content shared in all published articles on this website are solely those of the respective authors, and they do not necessarily reflect the views of the author’s employer or the techbeatly platform. We strive to ensure the accuracy and validity of the content published on our website. However, we cannot guarantee the absolute correctness or completeness of the information provided. It is the responsibility of the readers and users of this website to verify the accuracy and appropriateness of any information or opinions expressed within the articles. If you come across any content that you believe to be incorrect or invalid, please contact us immediately so that we can address the issue promptly.
Tags:
Latest posts
Comments
5 Responses
Leave a Reply
[…] Also check the Ansible Navigator cheatsheet. […]
I am combing through as much documentation as I can find on the Ansible-Navigator TUI and it seems like there is one critical feature missing… No search utility at all??? No way to search the module documentation for phrases of interest!? Man… For a massive organization that knows how to build unreasonably sophisticated enterprise tools, they sure know how to drop the ball!
What kind of information you want to search?
You can see the modules and collection inside a container image or localhost.
ansible-navigator doc -lstill works!Could you please explain what are you looking for?
Hi, how can you then search for example in the junipernetworks.junos.junos_snmp_server documentation? I can not found solution for that. Can you say for that the exact example? Thanks
You can use the command as follows
ansible-navigator doc ansible.builtin.dnfIf you cannot find module means, you haven’t installed it in your system.
If you have already installed, then make sure your ansible.cfg is configured to detect the collection path.
Read: https://www.techbeatly.com/getting-started-with-ansible-collections/