Skip to content

Ansible Navigator Cheat Sheet


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 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 ansible-playbook command.

$ ansible-navigator run site.yaml

ansible-playbook to ansible-navigator

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

Old individual commandsansible-navigator subcommands
ansible-playbookansible-navigator run
ansible-docansible-navigator doc
ansible-configansible-navigator config
ansible-inventoryansible-navigator inventory

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

: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 Esc button. You can exit from the TUI at anytime 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 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 same like 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 replay

You can replay the execution by using the artifacts from previous run but you need to enable the saving of artifacts 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 the artifacts 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 artifact to replay the execution and see the details.

$ ansible-navigator replay artifacts/ansible_artifact.jsonl 

ansible-navigator inventory

List and explore the inventory details.

Configure ansible-navigator

You can configure ansible-navigator for on project level by configuring ansible-navigator.yml in the project directory (same like ansible.cfg for project specific configuration). You can configure the execution environments, development styles, 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 are those of the author and do not reflect the views of the author’s employer or techbeatly platform.

Gineesh Madapparambath is the author of the book - 𝗔𝗻𝘀𝗶𝗯𝗹𝗲 𝗳𝗼𝗿 𝗥𝗲𝗮𝗹-𝗟𝗶𝗳𝗲 𝗔𝘂𝘁𝗼𝗺𝗮𝘁𝗶𝗼𝗻. 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

Leave a Reply

Your email address will not be published.

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