Network Automation with Red Hat Ansible Automation Platform

A playbook usually begins with a line consisting of three dashes (---) to indicate the start of the document. It might end with three dots (...) to indicate the end of the document, although in practice this is often omitted.

Between those markers, the playbook is defined as a list of plays. Playbooks contain one or more plays. Plays must define, at a minimum, the managed nodes to target and at least one task to execute.

The first line of the previous example playbook starts with a dash and a space, to indicate the start of the list of plays, then the name of the first play is defined. The name line associates a string with the play as a label that identifies the play. Defining the name of a play is optional, but is recommended because it helps to document your playbook and makes playbook output easier to understand. This is especially useful when a playbook contains multiple plays.

---
- name: Network automation example

The next line of the play specifies the hosts on which to run the tasks that are defined in the play. The hosts line takes a host pattern as a value, such as the names of managed nodes or groups in the inventory.

  hosts: ios

After hosts, this play sets gather_facts: false to disable standard fact gathering. This is an example of a directive that affects how the play runs.

The next line contains the tasks keyword, which specifies the list of tasks that this play runs.

Tasks call modules, which perform your desired action. Modules have specific parameters that you can use to specify the action of the module.

This example play has a single task, which runs the cisco.ios.ios_config module with the lines and save_when parameters.

The lines parameter specifies the configuration lines you want to appear in the running configuration. The save_when parameter determines when to copy the running configuration to the startup configuration.

For more information on the available parameters for the cisco.ios.ios_config module, visit https://docs.ansible.com/ansible/latest/collections/cisco/ios/ios_config_module.html.

  tasks:
    - name: Configure a Cisco IOS device
      cisco.ios.ios_config:
        lines:
            - service timestamps debug datetime msec
            - service timestamps log datetime msec localtime
            - service password-encryption
        save_when: changed

The tasks line is the part of the play that lists, in order, the tasks to run against the managed nodes.

If a parameter is set to its default value, you do not have to specify it in the play. Although, you can still specify a parameter for documentation purposes and to clarify the desired outcome of the play for anyone else who reads the playbook.

For example, the following play specifies the match and replace parameters, even though their value is the default value.

  tasks:
    - name: Configure a Cisco IOS device
      cisco.ios.ios_config:
        lines:
            - service timestamps debug datetime msec
            - service timestamps log datetime msec localtime
            - service password-encryption
        match: line
        replace: line
        save_when: changed

The default output provided by the ansible-navigator run command does not provide detailed task execution information. The -v option provides additional information, with up to four levels.

Before executing a playbook, it is good practice to validate its syntax. You can use the ansible-navigator run --syntax-check command to validate the syntax of a playbook.

The following example shows the successful syntax validation of a playbook.

[user@host networkautomation]$ ansible-navigator run \
netautomate.yml -m stdout --syntax-check
playbook: /home/user/networkautomation/netautomate.yml

When syntax validation fails, a syntax error is reported. The output also includes the approximate location of the syntax issue in the playbook. The following example shows the failed syntax validation of a playbook where the space separator is missing after the name attribute for the play.

[user@host networkautomation]$ ansible-navigator run \
netautomate.yml -m stdout --syntax-check
ERROR! We were unable to read either as JSON nor YAML, these are the errors we got from each:
JSON: Expecting value: line 1 column 1 (char 0)

Syntax Error while loading YAML.
  mapping values are not allowed in this context

The error appears to be in '/home/user/networkautomation/netautomate.yml': line 6, column 27, but may
be elsewhere in the file depending on the exact syntax problem.

The offending line appears to be:

    - name:Configure a Cisco IOS device
      cisco.ios.ios_config:
                          ^ here
Please review the log for errors.

You can use the --check option to run a playbook in check mode, which performs a "dry run" of the playbook. This causes Ansible to report what changes would have occurred if the playbook were executed, but does not make any actual changes to managed nodes.

The following example shows the dry run of the example playbook. In this case, the dry run reports that the task would make a change on the managed host.

[user@host networkautomation]$ ansible-navigator run \
netautomate.yml -m stdout --check

PLAY [Network automation example] **********************************************

TASK [Configure a Cisco IOS device] ********************************************
[WARNING]: Skipping command copy running-config startup-config due to
check_mode.  Configuration not copied to non-volatile storage
[WARNING]: To ensure idempotency and correct diff the input configuration lines
should be similar to how they appear if present in the running configuration on
device
changed: [switch1.lab.example.com]
changed: [switch2.lab.example.com]

PLAY RECAP *********************************************************************
switch1.lab.example.com     : ok=0    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
switch2.lab.example.com     : ok=0    changed=1    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

In general, tasks in Ansible Playbooks are idempotent, and it is safe to run a playbook multiple times. If the targeted managed nodes are already in the correct state, no changes should be made.

For example, assume that the playbook from the previous example is run again:

PLAY [Network automation example] **********************************************

TASK [Configure a Cisco IOS device] ********************************************
ok: [switch1.lab.example.com]
ok: [switch2.lab.example.com]

PLAY RECAP *********************************************************************
switch1.lab.example.com     : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
switch2.lab.example.com     : ok=1    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0

This time, all tasks passed with status ok and no changes were reported.