Skip to content

Ansible Navigator Cheat Sheet

Avatar photo

https://www.linkedin.com/in/gineesh/ https://twitter.com/GiniGangadharan

What is ansible-navigator

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 stdout

New 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.yaml

Installing ansible-navigator

Ansible 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-navigator

Refer to the navigator installation document or the Red Hat documentation to learn more.

ansible-playbook to ansible-navigator

The changes are very easy to adopt and commands are self-explanatory subsets.

Old individual commandsansible-navigator subcommands
ansibleansible-navigator exec -- ansible
ansible-playbookansible-navigator run
ansible-docansible-navigator doc
ansible-configansible-navigator config
ansible-inventoryansible-navigator inventory
ansible-inventoryansible-navigator inventory
ansible-builderansible-navigator builder
ansible-galaxyansible-navigator exec -- ansible-galaxy …
ansible-lintansible-navigator lint
ansible-testansible-navigator exec -- ansible-test …
ansible-vaultansible-navigator exec -- ansible-vault …
ansible-playbook -> ansible-navigator

ansible-navigator –help

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 -The TUI Dashboard

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 dnf

It 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.yml

:quit – Exit from ansible-navigator

You 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)

ansible-navigator Subcommands

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 page

ansible-navigator config

List 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 help

ansible-navigator doc

Explore the ansible documentation for modules and plugins.

$ ansible-navigator doc ping

ansible-navigator images

List and explore container images for the Ansible execution environment.

$ ansible-navigator images

ansible-navigator collections

List and explore available collections.

$ ansible-navigator collections

ansible-navigator run

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 stdout

ansible-navigator exec

Run 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"
}

ansible-navigator replay

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.jsonl

When 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.jsonl

Now you can use this artefact to replay the execution and see the details.

$ ansible-navigator replay artifacts/ansible_artifact.jsonl 

ansible-navigator inventory

List and explore the inventory details.

ansible-navigator settings

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: UTC

Configure ansible-navigator

You 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.jsonl

You 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.yml

Resources

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.

Avatar photo


https://www.linkedin.com/in/gineesh/ https://twitter.com/GiniGangadharan
Gineesh Madapparambath is the founder of techbeatly and he is the co-author of The Kubernetes Bible, Second Edition. and the author of 𝗔𝗻𝘀𝗶𝗯𝗹𝗲 𝗳𝗼𝗿 𝗥𝗲𝗮𝗹-𝗟𝗶𝗳𝗲 𝗔𝘂𝘁𝗼𝗺𝗮𝘁𝗶𝗼𝗻. He has worked as a Systems Engineer, Automation Specialist, and content author. His primary focus is on Ansible Automation, Containerisation (OpenShift & Kubernetes), and Infrastructure as Code (Terraform). (aka Gini Gangadharan - iamgini.com)

Comments

5 Responses

  1. […] Also check the Ansible Navigator cheatsheet. […]

  2. Taylor Forest says:

    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 -l still works!

      Could you please explain what are you looking for?

  3. Akos Ovari says:

    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

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.