Validating network states with pyATS and Ansible

In this recipe, we will outline how to use Ansible and the Cisco pyATS Python library to execute and parse operational commands on Cisco devices. Using these parsed commands, we can validate various aspects of the network.

Getting ready

This recipe assumes that the network has already been built and configured as outlined in all the previous recipes.

How to do it...

1. Install the Python libraries needed for pyATS:

$ sudo pip3 install pyats genie

2. Create the roles directory and then create the requirements.yml file with the following data:

 $ cat roles/requirements.yml
- src: https://github.com/CiscoDevNet/Ansible-pyats
  scm: git
  name: Ansible-pyats

3. Install the Ansible-pyats role as shown in the following code:

 $ Ansible-galaxy install -r requirements.yml

4. Create a new playbook called pb_validate_pyats.yml and populate it with the following task to collect the ospf neighbor from the wan devices.

---
  - name: Network Validation with pyATS
    hosts: wan
    roles:
      - Ansible-pyats
    vars:
      Ansible_connection: local
    tasks:
      - pyats_parse_command:
          command: show ip ospf neighbor
        register: ospf_output
        vars:
          Ansible_connection: network_cli

5. Update the playbook with the following tasks to extract the data for OSPF peer information:

      - name: "FACT >> Pyats OSPF Info"
        set_fact:
          pyats_ospf_data: "{{ ospf_output.structured.interfaces }}"

      - name: " FACT >> Set OSPF peers"
        set_fact:
          OSPF_PEERS: "{{ wan_l3_links[inventory_hostname] | selectattr('ospf','equalto',true) | list }}"

6. Update the playbook with the following tasks to validate OSPF peers and the OSPF peer state:

      - name: Validate Number of OSPF Peers
        assert:
          that:
            - pyats_ospf_data | length == OSPF_PEERS | length
        loop: "{{ OSPF_PEERS }}"

      - name: Validate All Peers are in Full State
        assert:
          that:
            - pyats_ospf_data[item.name] | json_query('neighbors.*.state') | first == 'FULL/ -'
        loop: "{{ OSPF_PEERS }}"

How it works...

In this recipe, we are exploring how to use the pyATS framework to perform network validation. pyATS is an open source Python library developed by Cisco as a testing framework for network testing. Genie is another Python library that provides parsing capabilities for transforming CLI-based output to Python data structures that we can consume in our automation scripts. Cisco released an Ansible role that uses the pyATS and Genie libraries. Within this role, there are multiple modules that we can use in order to build more robust Ansible validation playbooks to validate the network state. In order to start working with this role, we need to perform the following steps:

1. Install pyats and enie Python packages using python-pip.
2. Install the Ansible-pyats role using Ansible-galaxy.

In this recipe, we are using one of the modules within the Ansible-pyats role, which is pyats_parse_command. This module executes an operational command on the remote managed device and returns both the CLI output for this command and the parsed structured output for this command. The following code snippet outlines the structured data returned by this module for ip ospf neigbor on the wan01 device:

"structured": {
  "interfaces": {
    "GigabitEthernet2": {
      "neighbors": {
        "10.100.1.1": {
          "address": "10.3.1.1",
          "dead_time": "00:00:37",
          "priority": 0,
          "state": "FULL/ -"
        }
      }
    }
  }
}

We save the data returned by this module to the ospf_output variable and we use the set_fact module to capture the structured data returned by this module, before saving it to a new variable – pyats_ospf_data. Then, we use the set_fact module to filter the links defined in wan_l3_interfaces to just the ports that are enabled for OSPF.

Using the structured data returned by pyats_parse_command, we can validate this data and compare it with our OSPF peer definition using the assert module so as to validate the correct number of OSPF peers and their states.

To extract the OSPF peer state, we use the json_query filter to filter the returned data and provide just the OSPF state for each neighbor.

We are setting Ansible_connection to local on the play level, and setting it to network_cli on the pyats_parse_command task level, since we only need to connect to the device in this task. All the other tasks can run locally on the Ansible machine.

See also...

For more information regarding the PyATS and Genie libraries and how to use them for network testing, please consult the following URL:

https://developer.cisco.com/docs/pyats/#!introduction/pyats-genie

For more information regarding json_query and its syntax, please consult the following URLs:

https://docs.Ansible.com/Ansible/latest/user_guide/playbooks_filters.html#json-query-filter
http://jmespath.org/tutorial.html