Network Automation with Red Hat Ansible Automation Platform

To display a list of the collections and modules available in your current automation execution environment, run the ansible-navigator doc -l command.

[user@host ~]$ ansible-navigator doc -l
...output omitted...
ansible.builtin.copy                      Copy files to remote locations
...output omitted...
cisco.ios.ios_config                      Module to manage configuration sectio...
...output omitted...
cisco.nxos.nxos_command                   Run arbitrary command on Cisco NXOS d...
...output omitted...
junipernetworks.junos.junos_interfaces    Junos Interfaces resource module
...output omitted...

Search the output of this command by typing a slash (/) at the colon prompt followed by the keyword, and then pressing Enter.

As an alternative to running the ansible-navigator collections command in interactive mode, you can use the ansible-navigator doc module_name command to display detailed documentation for a module.

If you specify the -m stdout option, formatted documentation is displayed to your terminal. If you do not specify that option, leaving ansible-navigator in interactive mode, then you can scroll through the documentation in YAML format.

Module documentation includes a description of what the module is for, a list of the attributes that you can use to control the module in a task, examples of how to use the module, and other metadata.

You can also view a summary of all the options you can use with a module by running the ansible-navigator -s doc module_name command:

[user@host ~]$ ansible-navigator -s doc cisco.ios.ios_config
- name: Module to manage configuration sections.
  ios_config:
      after:                 # The ordered set of commands to append to the ...
      backup:                # This argument will cause the module to create...
      backup_options:        # This is a dict object containing configurable...
      before:                # The ordered set of commands to push on to the...
      defaults:              # This argument specifies whether or not to col...
...output omitted...

You can also use comments to aid readability. In YAML, everything to the right of the number sign (#) is a comment. If there is content to the left of the comment, precede the number sign with a space.

# This is a YAML comment

some data # This is also a YAML comment

Strings in YAML do not normally need to be put in quotation marks even if the string contains spaces.

this is a string

You must enclose strings in either double or single quotation marks if the string includes a colon character followed by a space.

Escape characters are not parsed in strings enclosed in single quotation marks. You must enclose strings in double quotation marks to parse escape characters such as the newline character (\n).

'Play 1: Configure SNMP settings'

"This is a private system\nUnauthorized use of this system is prohibited"

You can write multiline strings in either of two ways; using the vertical bar (|) character or the greater-than (>) character.

Use the vertical bar (|) character to denote that newline characters within the string are to be preserved.

banner_variable: |
  This system is restricted to authorized users.
  Unauthorized access is prohibited.
  If you are unauthorized, terminate access now.

A newline character is also added to the end of the string. Use (|-) if you do not want a newline character added to the end of the string.

Use the greater-than (>) character to indicate that newline characters are to be converted to spaces and that leading white spaces in the lines are to be removed. This method is often used to break long strings at space characters so that they can span multiple lines for better readability.

config_line: >
  description "This interface connects
  to interface1 on switch2 in the top
  of rack 10 in datacenter 4"

A newline character is still added to the end of the string. Use a greater-than symbol followed by a dash (>-) if you do not want a newline character added to the end of the string.

Dictionary key-value pairs are typically written as an indented block, as follows:

  name: svcrole
  svcservice: httpd
  svcport: 80

Dictionary key-value pairs can also be written in an inline block format inside braces, as follows:

  {name: svcrole, svcservice: httpd, svcport: 80}

Avoid the inline block format because it is harder to read. However, this format is sometimes used with Ansible roles. When a playbook includes a list of roles, it is more common to use this syntax to make it easier to distinguish roles included in a play from the variables being passed to a role.

Lists are typically written with the normal single-dash syntax:

  hosts:
    - router1
    - router2
    - router3

Lists can also be written in an inline format in square braces, as follows:

hosts: [router1, router2, router3]

You should avoid this syntax because it is usually harder to read.

Some playbooks might use an earlier shorthand method to define tasks by putting the key-value pairs for the module on the same line as the module name. For example, you might see this syntax:

  tasks:
    - name: Shorthand form
      ansible.builtin.service: name=httpd enabled=true state=started

Normally you would write the same task as follows:

  tasks:
    - name: Normal form
      ansible.builtin.service:
        name: httpd
        enabled: true
        state: started

You should generally avoid the shorthand form and use the normal form. Syntax highlighting tools in text editors such as VS Code can help you more effectively if you use the normal format than if you use the shorthand format.