Hello everyone and welcome back to our NetDevOps blog series. Starting with this post I will cover one of the most interesting building blocks we used in our CI/CD demo: pyATS & Genie. It is used internally at Cisco to test new software versions / products, and now it is also available for free to our customers and partners for their own testing and verification, how cool is that?

JulioG_pyATS demos pic1

pyATS is an Automation Test System written in Python. It provides the core infrastructure to define topologies, connect to network devices and run the required tests.


Julio G pyATS pic2

Genie builds on top of pyATS and it is fully integrated to provide model automation tests. It focuses on test cases for features (ie. BGP, HSRP, OSPF), and abstracts how this information is obtained from underlying devices.

pyATS and Genie together enable you to create network test cases that provide stateful validation of devices operational status. You can use them to validate how a new feature or product will affect your network, compare the status of your network before/after a change, customize your network monitoring based on your own business drivers.

The solution provides visibility on network devices health, by focusing not only on the configurational state, but also on the operational status. It is agnostic and extensible, so any type of system could potentially be included by developing the right set of libraries.

As you saw in our previous demos, it can be integrated into CI/CD pipelines (implemented via integration servers like GitLab or Jenkins), other frameworks (like Robot, for almost-natural language stateful tests definition), or even interact with ChatBots (ChatOps). It also integrates beautifully with VIRL topologies, and we will show you how to do it so you can focus only on what you want to test in your network.

For your reference all pyATS Documentation can be found here.

The network topology you will use during testing is called the testbed, and it includes your devices and links. It is defined in a YAML file, and as long as pyATS is implemented in Python, everything is an object… including the testbed.

Your network devices are also objects in pyATS, so you can perform operations on them using methods, like the following:

  • connect()
  • ping(destination)
  • execute(‘show version’)
  • configure(‘no ip domain lookup’)

The output from these commands will be parsed into structured data, so your systems can easily extract business-relevant data from them.

OK, let’s see it working.

The first thing you need to decide is how you want to run pyATS: natively in your own system, or in a Docker container. For the first option you should use a Python 3.X virtual environment (time to leave 2.7 behind, huh?), so you don’t clog your system, and then install the required tools (see this doc).

I heart containers

However I find it easier to run pyATS in a Docker container, as the available image includes all required software, libraries, dependencies and a ton of examples you can use to get started. So we will use containers for our demos.

If you don’t have infrastructure to attack with your tests, don’t worry. We got you covered. The sandbox you reserved in our previous demos includes a big VIRL server, so we will use it to run some simulated devices for our demos. You may reserve it here.

This sandbox also includes a devbox with all required utilities already pre-configured. At this point you could decide to use the devbox included in your sandbox to execute the demos, or rather configure your own system so you can continue using it later. If you decide to use the sandbox devbox you can connect to it by running: ssh developer@, and use password C1sco12345.

Julio Gomez VIRL logo

In order to easily manage our sandbox VIRL server we will use a very handy utility called virlutils. You will only need to install virlutils if you decide to use your own local workstation for the demos (no need to do it if you will be using the sandbox devbox).

$ pip install virlutils

Once done, please create a VIRL init file (again, no need to do this step if you will be using the sandbox devbox)…

$ vi ~/.virlrc

… and define the required VIRL credentials:


Then start a new terminal window in your workstation, so that it reads the new VIRL init file configuration. Now you should be able to search for some example pre-defined simulated topologies that could be useful for testing (you can find some more here).

$ virl search

You may even filter those examples: ie. look for the ones including IOS in their name.

$ virl search ios
Displaying 1 Results For ios

│ Name │ Stars │ Description │
│ virlfiles/2-ios-router │ 0 │ hello world virlfile │

That is a simple template for a 2 IOS-routers simulation (kind of like a hello-world for virlutils).

Make sure you are connected to your sandbox VPN and then download the VIRL topology specified below, so that you can start it in your server.

$ mkdir tests
$ cd tests
$ virl pull virlfiles/genie_learning_lab
Pulling from virlfiles/genie_learning_lab
Saved topology as topology.virl
$ virl up
Creating default environment from topology.virl
Localizing {{ gateway }} with:

Now you have your VIRL simulation running in the sandbox server.

$ virl ls
Running Simulations
│ Simulation │ Status │ Launched │ Expires │
│ netdevops_default_oAmstu │ ACTIVE │ 2019-04-03T10:54:44.416113 │ │

Julio Gomez plug

You can also see the status of its included nodes.

$ virl nodes
Here is a list of all the running nodes
│ Node │ Type │ State │ Reachable │ Protocol │ Management Address │ External Address │
│ csr1000v-1 │ CSR1000v │ ACTIVE │ REACHABLE │ telnet │ │ N/A │
│ nx-osv-1 │ NX-OSv │ ACTIVE │ REACHABLE │ telnet │ │ N/A │

Once a node shows up as ACTIVE and REACHABLE you can connect to it (use password cisco) with:

$ virl ssh nx-osv-1

Please note that during the connection process you will need to confirm you want to add its IP address to the list of known hosts.

One of the fantastic features that virlutils includes is that it can generate inventories to be used by other systems, using the command: virl generate [ pyats | nso | ansible ]

For our demos we will use the pyATS one, so try it once that all nodes in your simulation are REACHABLE.

$ virl generate pyats -o default_testbed.yaml
Writing default_testbed.yaml

With just a single command you have now a YAML file that defines your VIRL environment as a testbed to be used by pyATS straight away!

That pyATS testbed definition file will need some variables to define the enable password and login user/password. The most convenient way to use them later is to have them stored in a file, so please go ahead and download it. And while we are at it let’s download other files we will also need for our demos.

$ curl -L https://raw.githubusercontent.com/juliogomez/netdevops/master/pyats/env.list -o env.list
$ curl -L https://raw.githubusercontent.com/juliogomez/netdevops/master/pyats/1-pyats-intro.py -o 1-pyats-intro.py
$ curl -L https://raw.githubusercontent.com/juliogomez/netdevops/master/pyats/2-genie-intro.py -o 2-genie-intro.py
$ curl -L https://raw.githubusercontent.com/juliogomez/netdevops/master/pyats/initial_snapshot.robot -o initial_snapshot.robot
$ curl -L https://raw.githubusercontent.com/juliogomez/netdevops/master/pyats/compare_snapshot.robot -o compare_snapshot.robot

As the final preparation step before starting, please make sure to obtain the latest pyATS Docker image.

$ docker pull ciscotestautomation/pyats:latest

We are now all set and READY to start our tests!

See you in a couple of weeks for our first set of pyATS demos, stay tuned.

Any questions or comments please let me know in the comments section below, Twitter or LinkedIn.

For an excellent video introduction to pyATS and Genie, Check out this recording from Cisco Live in Barcelona by Siming Yuan, technical leader in Cisco Engineering for pyATS and Genie.

We’d love to hear what you think. Ask a question or leave a comment below.
And stay connected with Cisco DevNet on social!

Twitter @CiscoDevNet | Facebook | LinkedIn

Visit the new Developer Video Channel


Julio Gomez

Programmability Lead, EMEAR

Systems Engineers