Cisco pyATS Tutorial for Beginners

pyATS Genie

What is pyATS framework? pyATS meaning

pyATS was (and still is) an in-house Cisco Python testing framework that was developed for internal Cisco engineering use and has now been made open source and is available for you to perform your network testing. It is primarily a foundation-layer test framework.

Cisco currently run over 2 million test runs per month using the pyATS framework.

pyATS stands for Python Automation Test System

It was released to Devnet in 2017.

Genie is the library that contains all the knowledge of network operations, which works on top of pyATS.

Pyats and Genie are often talked about together and make up a very powerful network testing application.

When you start using Pyats you will see a lot of the commands use Pyats and a lot use Genie.

pyATS and Genie is not Cisco specific and will run with most network platforms.

1. How to install pyATS

pyATS is a Python package which can be installed using pip install pyats

I would also recommend adding [full] to get all the optional extras.

Full install command:

pip install “pyats[full]”

Install pyATS using Python Virtual Environment

I would also advise you use a virtual environemnt (venv)

If you are unsure what a virtual environment is, check my tutorial below

Python Virtual Environment Tutorial

Create a new directory for pyats

$ mkdir pyats 

Go into your new directory

$ cd pyats

Initialise your virtual environment

$ python3 -m venv .

Now activate

$ source bin/activate .

You should now see your prompt change to the name of your virtual environment

(pyats) roger@ubuntu:~/pyats$ 

You can now install pyats into this venv

pip install "pyats[full]"

Check the version of Pyats and verify a correct installation

pyats version check

At the time of writing I have installed version 20.7

2. Setup your testbed file

pyATS uses a concept of a testbed to describe the network devices you want to test. This is a YAML file that can either be imported or created. In this example we are going to create our testbed yaml file from scratch.

To do this you need to run the command

genie create testbed interactive --output testbed1.yml

NOTE: tesbed1.yml is the name of your testbed file and can be any name you want.

You will be prompted to enter your username and password and IP details for your network devices.

What is created is a standard YAML file like this.

You only really need to do one device so you can get the format of the file and it’s much quicker to copy this and add more devices!

This is the topology that I will be testing with pyATS / Genie and so far I have put CSR-1 and CSR-2 into the testbed file

So I have now defined CSR-1 and CSR-2 and I have enabled OSPF between the two devices.

3. Running your first pyATS / Genie test.

The beauty of pyATS / Genie is that is has a lot of built in knowledge of how networks operate. So we are just going to tell pyATS to learn everything about the OSFP topology. You do this with the command.

$ genie learn ospf --testbed-file testbed1.yml --output ospf1

This is telling pyATS to learn everything about OSPF on the devices defined in the testbed1.yml file and send the output to a folder called ospf1.

This folder will get created if it does not exist.

Once this runs, you will now have a folder that contains a lot of information about everything related to OSPF.

Too much information for you to go through by hand.

The real benefit of pyATS is that you can run this baseline test and then if you get an issue with OSPF or are experiencing network issues, you can run this test again and specify a different output folder and then compare the two files.

So now we have our baseline file ospf1. Let’s disable an interface

CSR-1#conf t
Enter configuration commands, one per line.  End with CNTL/Z.
CSR-1(config)#int Gi1 
CSR-1(config-if)#no ip ospf 10 area 0 
CSR-1(config-if)#

We will now run the genie learn command again but specify a different output folder

$ genie learn ospf --testbed-file testbed1.yml --output ospf2

A folder is now created called ospf2 containing all the information about current state of ospf.

All we have to do now is to compare the baseline folder to the folder when the issue occured.

To do this issue the command

$ pyats diff ospf1 ospf2

Pyats will now give you a diff file which you can go into and see what differences there are on the network.

pyATS Genie Parsers

To see a full list of all the parsers available check this link

https://pubhub.devnetcloud.com/media/genie-feature-browser/docs/#/parsers

For more information check the Cisco Documentation:

https://developer.cisco.com/pyats/

pyATS is 100% fully developed and implemented using Python, and is designed to be usable independent of any other existing infrastructures. It is engineered to be suitable for Agile, rapid development iterations, with the ability to handle a wide variety of testing scenarios and requirements, from white-box unit-testing, to black-box, feature, performance/scale testing & beyond.
https://pubhub.devnetcloud.com/media/pyats/docs/overview/introduction.html

pyATS will change the way network engineers perform network test automation, check out this video below for more information.

pyATS Book

Since writing this post a few years back there has now been quite a book written on the subject of pyATS – you can get the book here
https://www.amazon.co.uk/Cisco-pyATS_Network-Test-Automation-Solution/dp/0138031673/

Netdevops Live Video

pyATS Conclusions:

Cisco pyATS, also known as the Python Automated Test System, is a powerful tool for network engineers for several reasons:

1. Network Validation: pyATS is used for validating the state of a network – whether the network is working as it should. It does this by enabling engineers to parse the outputs of commands that have been run on their devices.
2. Automation: pyATS provides a framework for network test automation, allowing network engineers to automate repetitive tasks, saving time and reducing the potential for errors. This automation can be used for a wide variety of tasks, from simple device configuration changes to complex network health checks.
3. Testing: pyATS was originally designed for testing. It can simulate network topologies, automate test cases, and provide detailed reports on their results. This makes it a valuable tool for network engineers who want to thoroughly test new configurations or software versions before deploying them to production networks.
4. Interoperability: pyATS supports a variety of network devices and operating systems, making it versatile for use in different network environments.
5. Modularity: pyATS is built on a modular design which allows for easy extension and customization. Engineers can add their own libraries or modules to meet their specific network requirements.
6. Part of Cisco’s DevNet: pyATS is part of Cisco’s DevNet platform, and Cisco provides resources and community support for engineers working with this tool. It’s a part of an ecosystem that Cisco is building to promote network programmability and automation.

Therefore, pyATS is a powerful and flexible tool that can help network engineers ensure their networks are operating as expected, automate tasks, and run tests to prevent future issues.

pyATS use cases

1. Network Health Check Automation: A network engineer needs to perform regular health checks on the network to ensure its optimal performance. Instead of manually logging into each device and running commands, PyATS can be used to automate these tasks. With PyATS, the network engineer can write a Python script that logs into each device, runs the necessary commands, and parses the results. This script can then be scheduled to run at regular intervals, providing a continuous, automated health check for the network.The PyATS script could collect various pieces of information such as interface statuses, routing information, CPU usage, memory usage, etc. Any unexpected or abnormal results can be flagged for further investigation. This ensures that potential issues are detected and addressed early, helping to maintain the overall health and performance of the network.
2. Pre and Post Network Upgrade Validation: Suppose a network engineer has to perform an upgrade on the network devices – for example, to install a new version of the IOS software. Before performing the upgrade, the network engineer can use PyATS to capture the current state of the network – things like routing tables, interface statuses, and other important information.After performing the upgrade, the engineer can then use PyATS to capture the state of the network again, and compare it with the pre-upgrade state. This can help to ensure that the upgrade has not unintentionally affected the operation of the network. If any differences are detected, the engineer can investigate and address them before they cause any issues.

These use cases show how PyATS can be used to automate tasks, validate network states, and help detect and prevent issues, making it a very valuable tool for network engineers.

This is just the tip of the iceberg of what can be achieved with pyATS. I will be digging deeper into this amazing tool very soon. You can integrate pyATS with Ansible and Nornir and take your network automation to the next level!

It’s used by Cisco to do all the testing on their network before and after deploying and code so it’s battle tested and updated regularly.

Read more of my Python Network Automation posts

Frequently asked questions