Cisco Nexus 9000 (NX-OS) Upgrade

Overview

Cisco Nexus 9000 (NX-OS) Upgrade is a built-in Versus workflow template (Workflows → Router / Switch category, marked Built-in) that automates a safe, auditable NX-OS software upgrade for a Nexus 9000 switch. It performs the whole sequence a network engineer would run by hand — version and redundancy checks, a config backup, image transfer and hash verification, a compatibility / impact dry-run, install all, and post-upgrade verification — while pausing at two approval gates so a human signs off before anything is staged and again, with the impact result in hand, before the switch is touched.

The workflow is built around three facts specific to the Nexus 9000 platform:

• One unified image. Modern Nexus 9000 switches boot a single nxos….bin image — there is no separate kickstart image to stage and keep in lockstep.
• install all is the upgrade primitive. It validates compatibility, sets the boot variables, saves the running configuration, and (for a disruptive upgrade) reloads the switch — all in one command. Versus never hand-edits boot nxos variables.
• Impact is knowable in advance. show install all impact is a dry run that reports, per module, whether the upgrade is non-disruptive (ISSU) or disruptive (reload) — so the operator approves the install with eyes open.

Two Workflows: Single Switch vs vPC Pair

There are two built-in templates in the Router / Switch category — pick by topology:

• Cisco Nexus 9000 (NX-OS) Upgrade — one switch per run. Use it for a standalone Nexus, or if you prefer to drive each vPC peer as its own separate run.
• Cisco Nexus 9000 vPC Pair Upgrade — select a device group containing both vPC peers and the workflow upgrades them one at a time in a single run, waiting for the vPC to fully recover before it touches the second peer. This is the one to reach for on a vPC pair.

Both share the same underlying steps — the pair workflow simply runs them twice, once per peer, with an order-planning step at the front and an automatic vPC-health gate in the middle. The rest of this page walks the single-switch flow first, then the pair-specific additions.

Prerequisites

• The Nexus switch already present in Versus Device Inventory (Inventory) as vendor Cisco Nexus Switch (NX-OS), with working SSH credentials — the upgrade drives the device entirely over SSH.
• Reachability from Versus to the switch management address. For a switch on a private site network, add it to a Collector-managed site; the SSH session is tunneled through the on-site collector automatically — no direct cloud-to-device path is required.
• The target NX-OS image, from either source (see Image source): a Firmware Library image (Versus pushes it to the switch), or an Image Source URLthe switch pulls from (scp://, sftp://, ftp://, tftp://, http://). To push from the library, the switch needs feature scp-server enabled (or feature sftp-server for a collector-local copy).
• The expected SHA-512 of the image (from the Cisco software download page) — optional but strongly recommended, so Versus can prove the staged image is intact before installing it.
• A maintenance window sized for the impact the switch reports. Treat every upgrade as potentially disruptive until the impact check says otherwise.

HA Model: vPC Is Not "Standby-First, Then Failover"

If you've run the F5 BIG-IP upgrade workflow, it upgrades the standby unit first, fails traffic over to it, then upgrades the former active and fails back. That sequence exists because an F5 HA pair is active/standby — exactly one unit holds the traffic role at any moment, and there is a real failover command that moves it.

A Nexus 9000 vPC pair is different: it is active/active. Both switches forward traffic at the same time — dual-homed hosts and downstream switches connect to both peers over a single port-channel (the vPC), with both member links live. The vPC "primary / secondary" role is only a control-plane tie-breaker (which peer suspends its vPC member ports if the peer-link fails); it is not a traffic active/standby distinction. That changes the upgrade approach in two ways:

• There is nothing to fail over. When you reload one peer, dual-homed hosts simply lose one member link of their port-channel and keep forwarding through the surviving peer. There is no failover command to issue, so this workflow doesn't have (or need) a failover step.
• You upgrade one peer at a time. Upgrade the first peer, let it reload and rejoin, verify the vPC is healthy again (show vpc — peer adjacency formed, consistency OK, roles settled), and only then upgrade the second. Never reload both peers in the same window — that drops the whole vPC. The vPC Pair Upgrade workflow does exactly this sequencing for you in a single run (below); the single-switch workflow leaves you to run it once per peer.

Only orphan ports and any single-homed devices on the peer being reloaded actually lose connectivity during a disruptive upgrade; dual-homed traffic rides through the other peer. And when the impact check finds an ISSU (non-disruptive) path, that peer may not reload at all.

For a standalone Nexus (no vPC), none of this applies — it is a single switch, the upgrade is typically a disruptive reload, and there is no peer to sequence.

The vPC Pair Upgrade Workflow (Both Peers, One Run)

Cisco Nexus 9000 vPC Pair Upgrade takes a device group containing both peers and does the whole sequence in a single run, with the one-at-a-time safety built in. Its run form adds two fields to the single-switch inputs:

• Nexus vPC Pair (Device Group) — must contain exactly the two peers. The image URL, filename, target version, and optional SHA-512 are the same as the single-switch form, and the image is staged to both peers.
• Which peer to upgrade first — how Versus decides the order:
  • Auto (recommended) — upgrade the vPC secondary first. Reloading the secondary first leaves the primary holding orphan-port authority for as long as possible; when the primary is later reloaded, the already-upgraded secondary takes over.
  • vPC secondary first / vPC primary first — force the order explicitly by role.
  • By name — type a name, hostname, or management IP and Versus upgrades that peer first.

Versus reads each peer's vPC role over SSH (show vpc) to resolve the order; if a role can't be read (for example the switches aren't actually in a vPC), it falls back to a deterministic order by management IP so the run is still repeatable.

What the pair run does, end to end:

1. Determine order and run pre-checks (version + bootflash: space) on both peers, and save each running config.
2. Approve Image Staging, then stage and SHA-512-verify the image and run the impact check on the first peer.
3. Approve Install (impact-aware), then upgrade the first peer and verify its version and boot variables.
4. vPC health gate — Versus polls show vpc until peer adjacency is formed, the keep-alive peer is alive, and there are no consistency failures. If the vPC does not recover within the timeout, the run stops here — the second peer is never reloaded while the first is still rejoining.
5. Upgrade the second peer — stage, verify, impact-check, install, and verify — then a final check that both peers are on the target version and the vPC is healthy.

The two approval gates are the only pauses; everything between them, including the health gate, is automatic. So a vPC pair is one run with two approvals, not two separate runs.

Finding and Running the Workflow

Go to Workflows and find Cisco Nexus 9000 (NX-OS) Upgrade in the Router / Switch section, alongside the other built-in Cisco templates (IOS / IOS-XE Bundle, IOS-XE Install Mode, IOS XR). Built-in workflows are read-only — you run them directly rather than editing the canvas. Click Run to open the run form, which asks for:

• Nexus 9000 Device Group — the switch to upgrade (one switch, or one vPC peer, per run).
• Target NX-OS Version — e.g. 10.3(4a) or 9.3(12). Used to detect "already upgraded" and to verify the result afterward. NX-OS version strings are compared loosely, so 10.3(4a) and 10.3.4a both match.
• Firmware Image from Library — pick an NX-OS image already in the Versus Firmware Library and Versus pushes it to the switch. Or leave it blank and use the URL below. See Image source.
• Image Source URL (if not using the library) — where the switch pulls the image from, e.g. scp://[email protected]/images/nxos64-cs.10.3.4a.M.bin, plus the Image Filename to save as.
• Expected SHA-512 (optional, recommended) — paste it to have Versus verify image integrity on the switch before installing.
• EPLD Image Filename (optional, advanced) — leave blank unless the release notes require an EPLD update. See the EPLD section below.

Image Source: Push from the Library, or Pull from a URL

There are two ways to get the NX-OS image onto bootflash:, and you choose per run:

• Push from the Versus Firmware Library (recommended). Pick an image from the library and Versus sends it to the switch — no external file server to stand up. For a cloud image, Versus writes it straight to bootflash: over SCP (for a site device this rides the collector tunnel). For an image registered collector-local, the on-site collector copies it to the switch over the LAN, so a multi-GB image never transits the cloud — the same model as Collector-Local Firmware. The switch must have feature scp-server enabled to accept an SCP push (or feature sftp-server for the collector copy). Versus skips the transfer if the image is already on bootflash:.
• Pull from a URL. Leave the library field blank and give an Image Source URL(scp://, sftp://, ftp://, tftp://, http://) plus the filename to save as. The switch pulls the image itself over the management VRF — no feature scp-server needed, but you supply the file server.

Before anything is staged, the workflow runs read-only checks and a config backup against the switch:

• Check Running NX-OS Version — show version; records the running version and chassis model, and flags if the switch is already on the target.
• Check vPC / HA Redundancy — show vpc and show system redundancy status; reports the vPC role and whether the chassis has dual supervisors (an ISSU candidate), and reminds you to upgrade one vPC peer at a time.
• Validate Modules & FEX — show module confirms every module is healthy (active / ok / standby) and fails the run if any is powered-down, failed, or absent — you never want to run install all against a degraded chassis. show fex lists attached Fabric Extenders and their state (their image compatibility with the target is validated by the impact check).
• Check bootflash: Free Space — dir bootflash:; fails the run early if there isn't enough room for the image (NX-OS images run roughly 1.5–2 GB), with guidance to delete inactive images.
• Save Running Config — copy running-config startup-config, so the switch has a clean startup config before the upgrade touches boot variables.

If any check fails, the run halts here — nothing has been transferred, installed, or reloaded.

With staging approved, the image is pulled onto the switch and proven intact:

• Stage Image to bootflash: — either Versus pushes a library image to bootflash: over SCP (or the collector copies a collector-local image over the LAN), or, for a URL, the switch pulls it with copy <source-url> bootflash: vrf management. The step handles the prompts, logs transfer progress, skips the copy if the image is already present, and allows up to 40 minutes for a large image.
• Verify Image Hash / Integrity — show file bootflash:<image> sha512sum (SHA-256 / MD5 also selectable). If you supplied an expected hash, a mismatch fails the run so a corrupt image can never be installed. Versus also runs show version image bootflash:<image> to confirm NX-OS recognizes it as a bootable image and reads back its version.

Versus runs show install all impact nxos bootflash:<image> — a dry run that touches nothing but tells you exactly what the real install will do:

• Compatibility / upgrade path — if the check does not pass (for example the running version is too old to jump straight to the target and an intermediate hop is required), the run fails here, before any install, with the impact output for review. Otherwise Versus records whether the upgrade is non-disruptive (ISSU) or disruptive (reload) and carries that into the install step.
• Module support — Versus reads the per-module impact table and fails on any module flagged unsupported/incompatible for the target version, and lists the modules whose NX-OS image will change.
• BIOS upgrade — flags whether a supervisor/module BIOS (loader) upgrade will run. install all performs it automatically; the run notes it so you know not to interrupt power during the install.
• FEX compatibility — any attached Fabric Extenders that appear in the impact table are compatible and will be upgraded with the switch (disruptive to FEX-attached hosts); the run reports them.

Versus issues install all nxos bootflash:<image>, choosing the mode from the impact result (you can override to force disruptive or ISSU from the step config):

• Non-disruptive (ISSU) — the command is issued with the non-disruptive keyword and Versus polls show install all status until the in-service upgrade reports success. The management session normally survives and the data plane keeps forwarding.
• Disruptive — Versus issues the install, the switch reloads onto the new image, and Versus waits for it to come back and re-establishes SSH before continuing (reload window is configurable; the default allows up to 30 minutes).

In both cases install all — not Versus — sets the boot variables and saves the configuration, which is why the workflow never edits boot nxos by hand.

Once the switch is back (or the ISSU completes), Versus confirms the upgrade landed:

• Verify Post-Upgrade Version — show version on every device in the group; the run fails if any switch is not on the target version.
• Verify Boot Variables — show boot to confirm the boot nxos variable points at the new image, so the switch stays on it across a future reload.

Optional: EPLD Upgrade

The final section runs Install EPLD only if you supplied an EPLD Image Filenamein the run form — otherwise it is skipped. EPLD (Electronic Programmable Logic Device) images update module firmware and are disruptive: install epld bootflash:<image> module allpower-cycles the modules. Only run it when the target release's notes explicitly call for an EPLD update, and stage the EPLD image to bootflash: beforehand.

If a Step Fails: Resume or Back Out

A failed step pauses the run rather than continuing blind. From the run detail page you can:

• Resume Workflow — retry from the failed step once the underlying issue (reachability, disk space, a bad image, a compatibility gap) is fixed. Because the pre-install steps are read-only or idempotent, resuming after a staging or impact failure is safe.
• Fix and re-run — for a compatibility failure (no direct upgrade path), re-run targeting a supported intermediate version first, then run the workflow again to the final target.

NX-OS itself provides the deepest safety net: the previous image remains on bootflash:, so a manual rollback is a matter of pointing the boot variables back at it (install all nxos bootflash:<old-image>) and reloading. Because the workflow saves the startup config before staging and lets install allmanage the boot variables, the switch is never left in a half-configured boot state by Versus.