Lab Guide: Exploring the ansible-navigator Interface

A guide to exploring the ansible-navigator Textual User Interface (TUI) and its features.

Introduction

In this challenge, you will explore the ansible-navigator interface and highlight some of its key features for developing and testing Ansible automation. ansible-navigator provides a context-aware TUI that integrates with documentation and improves the experience of navigating playbook outputs.

Task: Navigating the TUI and Running Playbooks

Let’s dive into the ansible-navigator TUI and try out some commands.

  1. Launch ansible-navigator by running the command with no options in the integrated terminal:

    ansible-navigator

    You are now in the ansible-navigator TUI. By default, it shows the :welcome screen, providing a quick overview of available subcommands. Type :help and press Enter for more detailed information.

  2. View module documentation. Try displaying the documentation for the ping module by typing the following subcommand and pressing Enter:

    :doc ping

    You can scroll through the documentation using the arrow keys. To exit the documentation view (and return to the previous screen), press the Esc key. To exit the TUI completely, type :quit and press Enter.

  3. Run a playbook in TUI mode. Run your simple test.yml playbook again, but this time omit the -m stdout option to use the default TUI mode:

    ansible-navigator run ./test.yml
    You can also run playbooks from within the TUI by typing :run ./test.yml and pressing Enter.

  4. Explore the playbook results. The TUI displays the results of the playbook run. You navigate by using the number keys corresponding to lines on the screen and the Esc key to go back. Press the number corresponding to the play ([this is just a test]) to drill down into its tasks. You will see a list of tasks that ran.

  5. Inspect task details and documentation. Now, press the number corresponding to the Gathering Facts task (usually 0). This shows the details for that specific task. From here, you can quickly access the documentation for the module used in the task. Type the subcommand :doc and press Enter to view the documentation for the setup module (which is used by gather_facts). Press Esc twice to return to the list of tasks, and Esc again to return to the list of plays.

Wondering how to select a line number greater than 9? Simply prepend the number with a colon (e.g., :15 selects line 15).

  1. Run subcommands directly from the command line. You don’t always need to enter the TUI first. You can pass subcommands directly. For example, to view the documentation for the setup module directly from your shell prompt, exit the TUI (Esc until you exit, or :quit) and run:

    ansible-navigator doc setup

Remember, if you ever get lost within the ansible-navigator TUI, pressing Esc will always take you back to the previous screen. Pressing Esc on the main screen will exit the application.

Next Steps

You have now explored the basic navigation and features of ansible-navigator. Press the Next button below to proceed to the next challenge.

Troubleshooting

If you have encountered an issue or have noticed something not quite right, please open an issue on GitHub.