[Day #12 PyATS Series] Running Genie Diff API (Pre/Post Change Comparison) using pyATS for Cisco [Python for Network Engineer]

Introduction

In modern network automation, ensuring that configuration changes do not introduce unexpected issues is critical. As a Python for Network Engineer practitioner, leveraging Cisco pyATS and Genie Diff API can significantly enhance your change validation process. This toolset allows you to capture the state of a network device before and after a change, automatically compare the differences, and highlight discrepancies without manual CLI checks.

This blog is part of our 101 Days of pyATS (Vendor-Agnostic) series, where we explore real-world, production-grade testing and validation techniques. Today, we will focus specifically on running Genie Diff API for Cisco devices to perform pre- and post-change comparisons. We’ll cover the network topology, workflow scripts, line-by-line explanations, a testbed.yml example, real CLI screenshots, and conclude with FAQs. At the end, we’ll show how you can master these techniques in Trainer Sagar Dhawan’s 3-month instructor-led training.

Topology Overview

For this example, we’ll use a simplified Cisco lab topology:

• Devices: 2 Cisco IOS XE routers (R1, R2)
• Management: SSH access from a central automation host
• Purpose: Validate interface and routing table changes before and after a configuration push

Diagram

This setup can be scaled to any number of devices in production environments.

Topology & Communications

• Communication Protocol: SSH
• Transport: pyATS Testbed connects to each Cisco device
• Pre-Change Snapshot: Captured using Genie learn APIs (e.g., learn interface, learn routing)
• Post-Change Snapshot: Captured again after configuration deployment
• Comparison: Genie Diff API calculates and reports the differences automatically

Workflow Script

Here’s a Python script that:

1. Loads the testbed
2. Connects to devices
3. Captures pre-change state
4. Applies mock change (can be manual or via script)
5. Captures post-change state
6. Runs Genie Diff API

from genie.testbed import load
from genie.utils.diff import Diff
from pyats.async_ import pcall
import json

# Load testbed
testbed = load('testbed.yml')

# Devices
devices = ['R1', 'R2']

# Function to capture snapshots
def capture_snapshot(device_name, stage):
    device = testbed.devices[device_name]
    device.connect(log_stdout=False)
    snapshot = device.learn('interface')
    output_file = f'{device_name}_{stage}.json'
    with open(output_file, 'w') as f:
        json.dump(snapshot.to_dict(), f, indent=2)
    device.disconnect()
    return output_file

# Capture pre-change snapshots
pre_files = pcall(capture_snapshot, device_name=devices, stage='pre')

# (Simulate change deployment here)

# Capture post-change snapshots
post_files = pcall(capture_snapshot, device_name=devices, stage='post')

# Perform diff for each device
for device in devices:
    with open(f'{device}_pre.json') as f:
        pre_data = json.load(f)
    with open(f'{device}_post.json') as f:
        post_data = json.load(f)

    diff = Diff(pre_data, post_data)
    diff.findDiff()

    print(f"\n===== Diff for {device} =====")
    print(diff)

Explanation by Line

• from genie.testbed import load → Loads the testbed file for device information.
• from genie.utils.diff import Diff → Imports the Genie Diff class to compute differences.
• device.learn('interface') → Captures the current operational state of interfaces.
• pcall() → Executes snapshot captures in parallel for multiple devices.
• Diff(pre_data, post_data) → Creates a diff object comparing pre and post snapshots.
• diff.findDiff() → Finds and stores differences.
• print(diff) → Displays the diff output highlighting added, removed, or changed elements.

testbed.yml Example

testbed:
  name: Cisco_Lab
  devices:
    R1:
      os: iosxe
      type: router
      connections:
        cli:
          protocol: ssh
          ip: 192.168.1.101
      credentials:
        default:
          username: admin
          password: admin123

    R2:
      os: iosxe
      type: router
      connections:
        cli:
          protocol: ssh
          ip: 192.168.1.102
      credentials:
        default:
          username: admin
          password: admin123

Post-validation CLI Screenshots (Expected Output)

After running the script, you should see output similar to:

===== Diff for R1 =====
+ Added:
    interface GigabitEthernet1:
      ipv4: 192.168.10.1/24
- Removed:
    interface GigabitEthernet2:
      ipv4: 10.0.0.1/24
Modified:
    interface GigabitEthernet3:
      status: up -> down

This clearly shows:

• New IPs added
• Old configs removed
• Operational changes detected

FAQs

Q1: What is Genie Diff API and how does it help in network automation?

Answer:
Genie Diff API is a feature within Cisco’s pyATS framework that enables automated pre- and post-change state comparison of network devices. It allows you to capture operational or configuration states before making a change and then compare it with the post-change snapshot. This automated diff eliminates manual CLI verification, reducing human errors and accelerating change validation in production environments.

Q2: Can Genie Diff API be used only for configuration changes, or does it also validate operational states?

Answer:
It’s not limited to configuration checks. Genie Diff can compare any operational state learned via Genie parsers—such as interface status, routing tables, VLAN databases, ACLs, and BGP neighbors. This makes it useful for both configuration audits and real-time operational health checks.

Q3: How does pyATS learn device states before generating a diff?

Answer:
pyATS uses the device.learn() method, which runs structured CLI commands and parses their output into a Python dictionary. This machine-readable data is then used by the Genie Diff API to compute differences between pre- and post-change snapshots, ensuring precise comparisons.

Q4: Is it possible to run Genie Diff on multiple Cisco devices simultaneously?

Answer:
Yes. With pyATS parallel execution (using pcall), you can connect to and capture state data from hundreds or thousands of devices in parallel. The diff can then be run individually or aggregated for large-scale validation reports, making it ideal for enterprise-wide deployments.

Q5: Does Genie Diff work across different Cisco OS platforms (IOS, IOS XE, NX-OS, ASA)?

Answer:
Absolutely. Genie provides vendor-specific parsers for multiple Cisco platforms, including IOS, IOS XE, NX-OS, and ASA. As long as the parser supports the command set, Genie can capture and diff state data seamlessly across different Cisco platforms.

Q6: Can Genie Diff be integrated with CI/CD tools like Jenkins or GitLab for automated validations?

Answer:
Yes. Many network automation teams integrate Genie Diff into their CI/CD pipelines. The script can be triggered automatically after configuration deployment, generating diffs that can be stored as artifacts or sent via Slack/Email for validation and change approval processes.

Q7: How reliable is Genie Diff compared to manual show command comparisons?

Answer:
Genie Diff is significantly more accurate and scalable than manual verification. It parses CLI outputs into structured data, eliminating human interpretation errors. It also highlights only the exact changes, which is far more reliable than visually comparing large CLI outputs.

Q8: Is there a way to save the Genie Diff results for future audits or rollback verification?

Answer:
Yes. The diff output can be easily exported to JSON or text files for archival purposes. This helps in maintaining audit trails, performing post-incident reviews, or validating successful rollback during maintenance windows.

YouTube Link

Watch the Complete Python for Network Engineer: Running Genie Diff API (Pre/Post Change Comparison) using pyATS for Cisco [Python for Network Engineer] Lab Demo & Explanation on our channel:

Join Our Training

Mastering tools like pyATS and Genie Diff API is essential for modern network engineers looking to automate and validate networks at scale. Trainer Sagar Dhawan offers a 3-month instructor-led Python/Ansible/API course designed specifically for network engineers. This hands-on program will teach you how to build robust, vendor-agnostic automation scripts, integrate them into production, and elevate your career.

Click here to join the program and take your first step toward becoming an expert in Python for Network Engineer workflows.

Enroll Now & Future‑Proof Your Career
Email: info@networkjourney.com
WhatsApp / Call: +91 97395 21088