Safe Rollback When a Stage Fails

The decision is new. The mechanism is not.

rollback() is unchanged from Phase 3.5

NAPALM's rollback() and discard_config() were both fully taught, with real signatures and real verified behavior, in NAPALM for Network Engineers (Phase 3.5). Nothing about either method changes here. What's new is the trigger: rollback happens automatically, as a direct, coded consequence of Lesson 3's gate returning FAIL -- not a manual runbook step a human decides to run later.

Quick checkConcept check

What does this lesson add that NAPALM's own rollback lesson (Phase 3.5) didn't already cover?

A new rollback method with different behaviorNothing about rollback() itself -- the new material is connecting a failed gate decision (Lesson 3) directly to an automatic rollback call, as real control flow, rather than rollback being a manually-invoked, separate actionThis lesson introduces rollback() for the first timeA way to roll back without NAPALM

Why rollback(), not discard_config()

A real distinction, already taught, applied correctly here

NAPALM Lesson 5 drew a precise line: discard_config() abandons a candidate that was never committed; rollback() undoes a commit that already took effect. This module's stage always commits immediately, then validates the result (Lesson 3) -- so by the time a gate fails, the change is already live. rollback() is the correct choice for exactly that reason, not an arbitrary pick.

Quick checkScenario

This module's run_stage() always commits the change before validating it. Given that, why is rollback() the correct primitive here rather than discard_config()?

They're interchangeable -- either would workdiscard_config() only makes sense for a candidate that was never committed; by the time this module's gate evaluates a stage, the commit has already happened, so undoing it requires rollback(), exactly the distinction NAPALM Lesson 5 already establisheddiscard_config() doesn't exist in the installed NAPALM versionrollback() is required by nornir_napalm regardless of workflow shape

rollback_stage(): real, verified

rollback_stage(nr_subset) -- real, verified

from nornir_napalm.plugins.tasks import napalm_rollback

def rollback_stage(nr_subset):
  return nr_subset.run(task=napalm_rollback)

napalm_rollback is one of nornir_napalm's own real task functions (verified in Phase 3.6's own research) -- this module reuses it directly, not a hand-written connection call.

real, executed -- triggered on the failed canary from Lesson 3

agg = rollback_stage(canary)
for hostname, mr in agg.items():
  print(hostname, "failed:", mr.failed, "changed:", mr[0].changed, "result:", repr(mr[0].result))

Run against the exact same canary host whose validation failed in Lesson 3 -- this is the direct next step, not a separate hypothetical example.

output — real, verified

SW1 failed: False changed: True result: 'Rollback completed'

Real, verified output. 'Rollback completed' is napalm_rollback's own literal, real return message -- not something authored for this lesson.

Quick checkIdentify the correct code

Which correctly triggers a real rollback on every host in a Nornir subset, using the same mechanism this lesson verified?

nr_subset.run(task=napalm_rollback)nr_subset.rollback()napalm_rollback(nr_subset)nr_subset.run(task=napalm_configure, rollback=True)

Connecting the gate to the rollback

the automatic trigger — real, verified as part of Lesson 5's full script

gate = evaluate_gate(canary_result, threshold=1.0)

if gate["decision"] == "FAIL":
  rollback_agg = rollback_stage(canary)
  rolled_back = not rollback_agg.failed

No human decides to run this -- it's a direct if-branch on the gate's own decision, verified end to end in the capstone (Lesson 5).

Quick checkPredict output

Based on this lesson's real, verified output, what happens to the REST of the fleet (not the canary) when the gate fails and rollback triggers?

The rest of the fleet is rolled back too, as a precautionNothing -- rollback_stage() is called only on the canary subset that failed; the rest of the fleet was never touched in the first place, since expansion never happens after a FAIL decisionThe rest of the fleet automatically becomes the new canaryThe entire rollout restarts from scratch

Key takeaways

rollback_stage() reuses nornir_napalm's real napalm_rollback task directly -- no new connection logic, no reimplementation.
rollback() (not discard_config()) is the correct choice here specifically because this module's stages always commit before validating -- a direct, correct application of Phase 3.5's own real distinction.
Real, verified output: 'Rollback completed' on the exact canary host whose validation failed in Lesson 3 -- the same scenario, continued, not a new hypothetical.
The trigger is a direct if-branch on the gate's own decision -- rollback happens automatically on FAIL, and the rest of the fleet is never touched since expansion never runs.

What you'll learn

The decision is new. The mechanism is not.

Why rollback(), not discard_config()

rollback_stage(): real, verified

Connecting the gate to the rollback