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

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

Latest posts

Gineesh 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. Required fields are marked *

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