Using the App

This document describes common use-cases and scenarios for this App.

General Usage

Leveraging Nautobot to perform automated software upgrades on networking equipment.

Use-cases and common workflows

This app provides composable jobs that can be used individually as needed to perform the following tasks:

• Using Jobs to transfer software to a network device from a central software repository (HTTP(S), FTP, SFTP, etc).
• Using Jobs to save the running configuration of a device.
• Using Jobs to reboot a network device.
• Manage the lifecycle of software on a network device with a workflow execution to upgrade a device.

Individual Jobs for Custom Workflows

Each step of the upgrade process is implemented as a separate Nautobot Job that can be run independently:

Job	Description
Transfer Software Image to Device	Transfers one or more software image files to a device from a remote URL.
Save Device Configuration	Saves the running configuration to the startup-config or an alternative file.
Install OS on Device	Installs the new OS image and reboots the device.
Reboot Device	Reboots a network device with an optional wait for reload.
Update Device Software Version	Updates the Software Version association on the device in Nautobot.
Execute OS Upgrade Workflow	Orchestrates all of the above jobs in sequence with a custom results view.

Because each job can be run on its own, you can use an external orchestrator (such as Nautobot Job Hooks, an external workflow engine, or a CI/CD pipeline) to build custom upgrade workflows that fit your operational requirements. For example, you might run the file transfer job across an entire fleet in advance, then execute the install and reboot jobs during a maintenance window on a per-device basis.

Platform-Specific Reboot Behavior

The standalone Install OS on Device job exposes a Reboot toggle that controls whether the device is rebooted after the install. On most supported platforms, unchecking the toggle skips the post-install reboot. The platforms below behave differently — set expectations accordingly when planning a maintenance window. The Execute OS Upgrade Workflow job always reboots as part of its sequence.

Platform	Reboot Behavior
Cisco IOS	Forces a reboot when Install Mode is enabled. If Install Mode is checked and Reboot is unchecked, the upgrade task will fail.

File Size Validation

The Transfer Software Image to Device and Execute OS Upgrade Workflow jobs both accept a Skip File Size Check toggle (disabled by default). The toggle is the master switch: by default, the job validates the image size against the target device's available disk space before starting the transfer. Check the toggle to bypass that validation.

By default (toggle unchecked):

1. If the selected Software Image File has image_file_size populated, that value is forwarded to pyntc.
2. If image_file_size is empty and the download URL is HTTP(S), the job issues a HEAD request with Accept-Encoding: identity and uses the response's Content-Length. If Content-Length is not returned, it falls back to a cancelled GET. If neither yields a size, the job fails before starting the transfer.
3. If image_file_size is empty and the download URL is not HTTP(S), the job fails with a message asking you to populate image_file_size or check the Skip File Size Check toggle.
4. pyntc then checks the target device's available disk space against the resolved size before starting the transfer. If the device lacks room, pyntc raises NotEnoughFreeSpaceError and the job surfaces this as an explicit "Insufficient disk space on device" error so the cause is distinguishable from checksum or generic transfer failures.

When the toggle is checked, the size path is skipped entirely — no HEAD probe, no pyntc free-space check. Check it when your image source does not report Content-Length and you have not populated image_file_size on the Software Image File, or when you otherwise need to bypass the validation.

Operational Compliance Integration

When the Nautobot Operational Compliance app is installed alongside OS Upgrades, the Execute OS Upgrade Workflow job automatically expands to include pre-change and post-change operational state checks. This provides a built-in mechanism for validating that network devices are healthy before and after an upgrade.

How It Works

With Operational Compliance enabled, the upgrade workflow chain expands from:

Upload Image → Save Configuration → Install OS → Assign New Software

to:

Pre Check → Upload Image → Save Configuration → Install OS → Post Check → Upgrade Validation → Assign New Software

• Pre Check — Collects command output from devices before the upgrade begins using the Operational Compliance CollectCommandOutput job. This captures the baseline operational state.
• Post Check — Collects the same command output after the OS install and reboot, capturing the post-upgrade operational state.
• Upgrade Validation — Runs the Operational Compliance CompareCommandOutput job to compare pre and post check results against the selected validation rules, highlighting any unexpected changes.

Selecting Validation Rules

When Operational Compliance is installed, the Execute OS Upgrade Workflow job form will display additional input fields:

• Validation Rules — Select individual validation rules to run during pre/post checks.
• Validation Rule Groups — Select validation rule groups to run during pre/post checks.
• Fail Fast — When enabled (default), the upgrade validation will stop on the first error encountered.

If no validation rules or validation rule groups are selected, the Pre Check, Post Check, and Upgrade Validation steps are automatically skipped.

Viewing Results

The custom job results view reflects the expanded workflow, showing the status of each step including the compliance checks:

Each step in the workflow displays one of the following statuses: pending, started, finished, skipped, or failure.