simple-upgrade

A modular, profile-driven Python orchestrator for network device firmware upgrades. Built for Cisco IOS-XE with a dynamic JSON device-profile architecture that eliminates hardcoded CLI strings.

Architecture Overview

┌─────────────────────────────────────────────────┐
│                 UpgradePackage                   │
│  (Orchestrator — runs stages sequentially)       │
├──────────┬──────────┬───────────┬───────────────┤
│   sync   │readiness │ pre_check │  distribute   │
│          │          │           │               │
│ activate │post_acti-│post_check │ verification  │
│          │vation_wait│          │     diff      │
├──────────┴──────────┴───────────┴───────────────┤
│              ExecutionContext (ctx)               │
│  Carries: device_info, golden_image, file_server │
│           device_profile, stage_results          │
├─────────────────────────────────────────────────┤
│  Device Profiles (JSON)    │   TaskRegistry      │
│  groups/ → inheritance     │   @register_stage   │
│  models → regex matching   │   manufacturer map  │
└─────────────────────────────────────────────────┘

Key Features

• Profile-Driven Execution — All CLI commands (show, copy, verify, install, boot) are defined in JSON device profiles, not hardcoded in Python
• Group Inheritance — Device profiles inherit commands from shared group templates (e.g. install_mode.json)
• Automatic Profile Matching — Hardware model detected via show version is regex-matched to the correct JSON profile
• Configuration Integrity Validation — JSON profiles are statically linted at startup for schema errors and overlapping model patterns
• Smart Download — Skips re-download if file already exists with matching size and MD5
• Flash Cleanup — Automatically runs install remove inactive before file transfer
• TCP Socket Polling — Post-reload wait uses intelligent SSH port probing instead of blind sleep timers
• Dual Logging — Structured JSON execution log + timestamped CLI text log capturing all Unicon/Scrapli output
• Diagnostic Bundling — Pre/post check diffs packaged into a ZIP archive for audit

Pipeline Stages

Installation

pip install simple-upgrade

Quick Start

from simple_upgrade import UpgradePackage

pkg = UpgradePackage(
    # ── Required Parameters ──
    host="172.20.20.11",
    username="admin",
    password="admin",
    platform="cisco_iosxe",

    # ── Optional Parameters ──
    port=22,                                    # SSH port (default: 22)
    manufacturer="cisco",                       # Manufacturer key (default: "cisco")
    connection_mode="normal",                   # "normal" | "mock" | "dry_run"
    enable_password="admin",                    # Enable/privilege-exec secret
    source_interface="GigabitEthernet0/0",      # Source interface for file transfers
    source_vrf="Mgmt-vrf",                      # VRF for routing file transfers

    # ── Post-Activation Wait Timers ──
    post_wait_delay=30,                         # Seconds before starting SSH probe (default: 600)
    post_wait_retries=60,                       # Max SSH probe attempts at 15s intervals (default: 120)
    post_wait_convergence=60,                   # STP/routing settle time after SSH returns (default: 30)

    # ── Golden Image ──
    golden_image={
        "version": "17.13.1",                   # Target software version
        "image_name": "cat9k_iosxe.17.13.01.SPA.bin",  # Filename (no flash: prefix)
        "image_size": 1234567890,               # Expected file size in bytes
        "md5": "abc123def456...",                # Expected MD5 checksum
        "sha256": "def456ghi789...",             # Optional SHA-256 checksum
    },

    # ── File Server ──
    file_server={
        "protocol": "http",                     # http | https | tftp | ftp | scp
        "ip": "192.168.29.73",                  # File server IP
        "port": 80,                             # Server port (optional)
        "base_path": "/Cisco/C9XXX/",           # URL path on server
        "username": "ftpuser",                  # FTP/SCP username (optional)
        "password": "ftppassword",              # FTP/SCP password (optional)
    }
)

# Run all stages interactively
for stage in pkg.STAGES:
    result = pkg.run_stage(stage)
    print(f"{stage}: {'✓' if result.success else '✗'} — {result.message}")

# Or run the full pipeline automatically
# results = pkg.execute()

Constructor Parameters

Required

Optional

golden_image Dictionary

file_server Dictionary

Note: source_interface and source_vrf can be specified either as top-level parameters or inside file_server. Top-level values take priority.

Connection Modes

Device Profile Architecture

Device profiles are JSON files in device_profiles/cisco/ that define all commands the orchestrator will execute. No CLI strings are hardcoded in Python.

Structure

device_profiles/
└── cisco/
    ├── groups/
    │   ├── install_mode.json      # Shared template for install-mode devices
    │   └── lab_vios.json          # Lab-specific overrides
    ├── catalyst_9300x.json        # Device profile → inherits from install_mode
    └── catalyst_VIOS.json         # Device profile → inherits from lab_vios

Profile Fields

Template Placeholders

The upgrade_commands block supports dynamic placeholders:

Output Files

After execution, the following files are generated in output/<hostname>/:

Supported Devices

Additional profiles can be added by creating a new JSON file in device_profiles/cisco/ with appropriate models regex patterns and an optional group reference.

Requirements

• Python 3.12+
• scrapli — SSH connections (readiness, checks, verification)
• genie / pyats / unicon — File distribution and activation (interactive dialogs)
• netutils — Version comparison utilities
• pydantic — Data model validation

License

Apache License 2.0

Author

Tarani Debnath