Software upgrades¶

StratoWeave upgrades the software of each device on its own. You set the release a device should run, and the device's software manager moves the device to it. Which devices to upgrade, and when is decided by fleetmgr.

A release is one name per device, for example 17.18.03a. Platforms that version parts of their software separately are not supported yet.

Parts¶

Every DeviceMgr owns one SoftwareManager. A device type names its adapter with software_adapter_type. A device type without one gets NoSoftwareAdapter, so its upgrades fail with "device type has no software adapter".

Configuration¶

Set under stratoweave-rfs:device=<name>/software:

Upgrade steps¶

check ──> already on target ──> up-to-date
  │
  └─> prepare ─> pre-checks ─> install ─> post-checks ─> commit ─> succeeded
         │           │            │            │            │
         └───────────┴────────────┴─> failed   └────────────┴─> rollback ─> rolled-back

Rules:

• An error in prepare or install ends with failed. A failed install does not roll back.
• A failed commit starts a rollback. A failed rollback ends with failed.
• If the device does not run the target after the commit, the run ends with failed. This happens when the device went back on its own before the commit arrived.
• Post-checks get 15 minutes. When the platform goes back on its own after a set time (IOS XE does), the limit is cut so the commit is sent at least 2 minutes before that. With less than 2 minutes left, the manager rolls back at once.
• A device runs one upgrade at a time.
• Run state lives in memory. A failed run is not remembered: the next config change for the device starts a new run if the target still differs. After a restart, the stored config can start a new run.

Checks¶

Applications add checks by name. Every check must pass.

def precheck(done: action(bool, str) -> None) -> None:
    if peer_is_up:
        done(True, "peer up")
    else:
        done(False, "redundant peer is down")

swmgr = dev.get_swmgr()
swmgr.add_precheck("my-app", precheck)
swmgr.add_postcheck("my-app", postcheck)

A check gets a done action and calls it once it has decided, so it can do other work first. The manager passes it no device data; the check reads the device itself. A check added during a run counts from the next run. remove_precheck and remove_postcheck take a check out, also during a run. An answer that arrives after its round has ended is ignored.

The BGP device-health check in fleetmgr/src/flotilla/rfs.act is a working example.

State¶

Published under stratoweave-rfs:device=<name>/software/state:

Every change goes into the device's operational data, so reads and oper subscriptions see it right away. A new run removes reason and sets both verdicts back to not-run. State is not saved; after a restart it is unknown. The model also has upgrade-needed and a job list, which the manager does not set.

Adapter API¶

A platform adapter is a subclass of SoftwareAdapter in src/device.act.

Jobs report through done. The error message becomes the run's reason, so it should name the operation and the device's cause, for example add failed: install-verify-pkg-fail.

IOS XE¶

IosXeSoftwareAdapter in src/adapters/software_iosxe.act uses these NETCONF RPCs:

• An <ok/> reply only means the device accepted the RPC. The adapter then reads install-oper-data for the records with its UUID until the operation ends.
• activate names the image by the version the device gave it during the add, for example 17.18.03a.0.5540.
• The device reboots after activate and after abort. Read errors during the reboot are expected. The adapter reads the running release until it is the one it waits for.
• Without install-commit within 30 minutes of activate, the device goes back to the old release on its own. 30 is the lowest value IOS XE accepts.
• The running release comes from the software-version banner in Cisco-IOS-XE-device-hardware-oper. Releases are compared part by part, so 17.18.03a matches 17.18.3a.
• Operation records are read every 10 seconds for up to 30 minutes. During a reboot the release is read every 20 seconds for up to 35 minutes. Nothing is retried.
• Old images stay on bootflash. cleanup does nothing.

The YANG for these RPCs and oper nodes is a trimmed copy in src/adapters/software_iosxe_yang.act. The bindings generated from it are in software_iosxe_rpc.act and software_iosxe_oper.act.

Testing¶

IosXeSoftwareMock in src/adapters/software_iosxe_mock.act runs behind the in-process NETCONF mock server. Like a real device, it answers an RPC before the work is done. It also serves one BGP neighbor for checks to read. A mock device sets these leaves under mock/software:

The upgrade duration is split in the shares measured on a lab c8000v with a 962 MB image: copy 130 s, add 20 s, activate 240 s and commit 5 s, 395 s in all. An abort takes 240 s.