Red Hat Ansible for Network Automation

Consult the command invocation help with the --help option for the ansible-doc command. This is a reliable place to start whenever you are interested in learning more about a relatively unfamiliar command.

[student@workstation ~]$ ansible-doc --help
Usage: ansible-doc [-l|-F|-s] [options] [-t <plugin type> [plugin]

plugin documentation tool

Options:
  -a, --all             **For internal testing only** Show documentation for
                        all plugins.
  -h, --help            show this help message and exit
  -l, --list            List available plugins
  -F, --list_files      Show plugin names and their source files without
                        summaries (implies --list)
  -M MODULE_PATH, --module-path=MODULE_PATH
                        prepend colon-separated path(s) to module library
                        (default=[u'/root/.ansible/plugins/modules',
                        u'/usr/share/ansible/plugins/modules'])
  -s, --snippet         Show playbook snippet for specified plugin(s)
  -t TYPE, --type=TYPE  Choose which plugin type (defaults to "module")
  -v, --verbose         verbose mode (-vvv for more, -vvvv to enable
                        connection debugging)
  --version             show program's version number and exit

See man pages for Ansible CLI options or website for tutorials
https://docs.ansible.com

From the --help option, you can find out which options are available to explore. What do you think the --snippet option would show you? If you try it with no arguments, it says "ERROR! Incorrect options passed," because it is expecting the name of a plug-in.

Use --list (-l) to get a list of available plug-ins. The --type=TYPE (-t TYPE) option displays a list of plug-ins of a given type. What types of plug-ins are there? You see from the "Developing Plug-ins" page at the Ansible Documentation website that the list includes callback, connection, inventory, lookup, vars, filter, and test as different types of plug-ins. Fortunately, if you try to use invalid data, the ansible-doc command provides more information.

[student@workstation ~]$ ansible-doc -t filter vyos_command
Usage: ansible-doc [-l|-F|-s] [options] [-t  <plugin type> [plugin]

ansible-doc: error: option -t: invalid choice: u'filter' (choose from 'cache', 'callback', 'connection', 'inventory', 'lookup', 'shell', 'module', 'strategy', 'vars')

Type ansible-doc network_cli.

[student@workstation ~]$ ansible-doc network_cli
 [WARNING]: module network_cli not found in:
/home/student/.ansible/plugins/modules:/usr/share/ansible/plugins/modules:/usr/lib/python2.7/site-packages/ansible/modules

That seems disappointing. Is there no information available from ansible-doc about network_cli? This is because ansible-doc looks up documentation for modules by default, and network_cli is a connection plug-in.

Type ansible-doc -t connection network_cli.

[student@workstation ~]$ ansible-doc -t connection network_cli
> NETWORK_CLI (/usr/lib/python2.7/site-packages/ansible/plugins/connection/network_cli.py)

        This connection plugin provides a connection to remote devices over
        the SSH and implements a CLI shell. This connection plugin is typically
        used by network devices for sending and receiving CLI commands to network
        devices.
...output omitted...

Scroll down using the space bar to view more information. Press q to end the session. There is a lot of information listed here, for instance, describing potentially useful options and how to set them (shown under set_via).

How did you get access to all of this information? It was the -t TYPE option (--type=TYPE). How can you get more information about which plug-ins of a particular type exist? The -t option, fortunately, can be combined with the -l one (--list).

What do you think strategy plug-ins are? Type ansible-doc -t strategy -l.

[student@workstation ~]$ ansible-doc -t strategy -l
debug   Executes tasks in interactive debug session.
free    Executes tasks on each host independently
linear  Executes tasks in a linear fashion

Type ansible-doc -t connection -l. This is the list of plug-ins of type connection. Because netconf appears in this list, for instance, you know you can type ansible-doc -t connection netconf to view information about the netconf connection plug-in.

[student@workstation ~]$ ansible-doc -t connection -l
buildah      Interact with an existing buildah container
chroot       Interact with local chroot
docker       Run tasks in docker containers
funcd        Use funcd to connect to target
iocage       Run tasks in iocage jails
jail         Run tasks in jails
kubectl      Execute tasks in pods running on Kubernetes.
libvirt_lxc  Run tasks in lxc containers via libvirt
local        execute on controller
lxc          Run tasks in lxc containers via lxc python library
lxd          Run tasks in lxc containers via lxc CLI
netconf      Provides a persistent connection using the netconf protocol
network_cli  Use network_cli to run command on network appliances
oc           Execute tasks in pods running on OpenShift.
paramiko_ssh Run tasks via python ssh (paramiko)
persistent   Use a persistent unix socket for connection
saltstack    Allow ansible to piggyback on salt minions
ssh          connect via ssh client binary
winrm        Run tasks over Microsoft's WinRM
zone         Run tasks in a zone instance

Type ansible-doc -t inventory -l. This displays a list of plug-ins that can be used to obtain or construct inventory information from a particular source or source format, or return inventory information in a particular format.

[student@workstation ~]$ ansible-doc -t inventory -l
advanced_host_list Parses a 'host list' with ranges
auto               Loads and executes an inventory plugin specified in a YAML
                   config
aws_ec2            ec2 inventory source
constructed        Uses Jinja2 to construct vars and groups based on existing
                   inventory.
host_list          Parses a 'host list' string
ini                Uses an Ansible INI file as inventory source.
k8s                Kubernetes (K8s) inventory source
openshift          OpenShift inventory source
openstack          OpenStack inventory source
script             Executes an inventory script that returns JSON
virtualbox         virtualbox inventory source
yaml               Uses a specifically YAML file as inventory source.

Type man ansible-doc and see if it reports who originally wrote Ansible.

[student@workstation ~]$ man ansible-doc
...output omitted...
AUTHOR
        Ansible was originally written by Michael DeHaan.