Wednesday, 6 July 2022

Introduction to Ansible Navigator


Ansible Navigator (ansible-navigator), available since Ansible v2, is:
  • A text-based user interface (TUI) for the Red Hat Ansible Automation Platform.
  • command based tool for creating, reviewing, and troubleshooting Ansible content, including inventories, playbooks, and collections.
To install it on a control node running the Ubuntu:

$ sudo apt install python3-pip
$ python3 -m pip install ansible-navigator --user

To check its install location:
$ which ansible-navigator

To make it available in the current shell (terminal):
$ echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.profile
$ source ~/.profile
Let's check out its CLI commands:
$ ansible-navigator --help
Usage: ansible-navigator [options]

Options (global):
 -h     --help                                   Show this help message and exit
 --version                                       Show the application version and exit
 --rad  --ansible-runner-artifact-dir            The directory path to store artifacts generated by ansible-runner
 --rac  --ansible-runner-rotate-artifacts-count  Keep ansible-runner artifact directories, for last n runs, if set to 0 artifact directories won't be deleted
 --rt   --ansible-runner-timeout                 The timeout value after which ansible-runner will forcefully stop the execution
 --cdcp --collection-doc-cache-path              The path to collection doc cache (default: /home/bojan/.cache/ansible-navigator/collection_doc_cache.db)
 --ce   --container-engine                       Specify the container engine (auto=podman then docker) (auto|podman|docker) (default: auto)
 --co   --container-options                      Extra parameters passed to the container engine command
 --dc   --display-color                          Enable the use of color for mode interactive and stdout (true|false) (default: true)
 --ecmd --editor-command                         Specify the editor command (default: vi +{line_number} {filename})
 --econ --editor-console                         Specify if the editor is console based (true|false) (default: true)
 --ee   --execution-environment                  Enable or disable the use of an execution environment (true|false) (default: true)
 --eei  --execution-environment-image            Specify the name of the execution environment image (default:
 --eev  --execution-environment-volume-mounts    Specify volume to be bind mounted within an execution environment (--eev /home/user/test:/home/user/test:Z)
 --la   --log-append                             Specify if log messages should be appended to an existing log file, otherwise a new log file will be created per
                                                 session (true|false) (default: true)
 --lf   --log-file                               Specify the full path for the ansible-navigator log file (default: /home/bojan/dev/github/ansible-demo/ansible-
 --ll   --log-level                              Specify the ansible-navigator log level (debug|info|warning|error|critical) (default: warning)
 -m     --mode                                   Specify the user-interface mode (stdout|interactive) (default: interactive)
 --osc4 --osc4                                   Enable or disable terminal color changing support with OSC 4 (true|false) (default: true)
 --penv --pass-environment-variable              Specify an existing environment variable to be passed through to and set within the execution environment (--penv
 --pa   --pull-arguments                         Specify any additional parameters that should be added to the pull command when pulling an execution environment
                                                 from a container registry. e.g. --pa='--tls-verify=false'
 --pp   --pull-policy                            Specify the image pull policy always:Always pull the image, missing:Pull if not locally available, never:Never
                                                 pull the image, tag:if the image tag is 'latest', always pull the image, otherwise pull if not locally available
                                                 (always|missing|never|tag) (default: tag)
 --senv --set-environment-variable               Specify an environment variable and a value to be set within the execution environment (--senv MY_VAR=42)
 --tz   --time-zone                              Specify the IANA time zone to use or 'local' to use the system time zone (default: utc)

 {subcommand} --help
  builder                                        Build execution environment (container image)
  collections                                    Explore available collections
  config                                         Explore the current ansible configuration
  doc                                            Review documentation for a module or plugin
  exec                                           Run a command within an execution environment
  images                                         Explore execution environment images
  inventory                                      Explore an inventory
  lint                                           Lint a file or directory for common errors and issues
  replay                                         Explore a previous run using a playbook artifact
  run                                            Run a playbook
  settings                                       Review the current ansible-navigator settings
  welcome                                        Start at the welcome page
On the first run it pulls a Docker image which contains a demo material:

$ ansible-navigator
Execution environment image and pull policy overview
Execution environment image name:
Execution environment image tag:      v0.4.2
Execution environment pull arguments: None
Execution environment pull policy:    tag
Execution environment pull needed:    True
Updating the execution environment
Running the command: docker pull
v0.4.2: Pulling from ansible/creator-ee
f0a2109a2528: Pulling fs layer
4ca545ee6d5d: Pull complete
4a7326c2ac2c: Pull complete
Digest: sha256:6b2160c2c4df4fe87a5efe4f33a16c6369228d1e99a0918db517652bd09b71e9
Status: Downloaded newer image for

...and then shows TUI:

 3│Some things you can try from here:
 4│- :collections                                    Explore available collectio
 5│- :config                                         Explore the current ansible
 6│- :doc <plugin>                                   Review documentation for a
 7│- :help                                           Show the main help page
 8│- :images                                         Explore execution environme
 9│- :inventory -i <inventory>                       Explore an inventory
10│- :log                                            Review the application log
11│- :lint <file or directory>                       Lint Ansible/YAML files (ex
12│- :open                                           Open current page in the ed
13│- :replay                                         Explore a previous run usin
14│- :run <playbook> -i <inventory>                  Run a playbook in interacti
15│- :settings                                       Review the current ansible-
16│- :quit                                           Quit the application
18│happy automating,

^b/PgUp page up    ^f/PgDn page down    ↑↓ scroll    esc back    :help help

If we type :images we'll see a list of all Docker images on the current node. Those which are Ansible Execution Environments will be highlighted:

At the bottom we can see the menu:

So, if we type :17 we'll get a menu for the image #17:

Typing :2 will show the version of Ansible core and all collections:


Playbook Linting

Ansible Navigator's subcommand lint checks the playbook for any syntax errors.
$ ansible-navigator lint ./run_locally/hello_world.yaml 

...outputs the following:


No comments: