Prepull-Before-Maintenance Outage Choreography

Defensive publication + clean-room reference implementation. A unified Kubernetes deploy control loop that collapses the maintenance-window outage of a large-image, single-writer, single-route workload from build + cold-pull + pod-swap down to pod-swap alone.

Prior-art purpose. This repository is published to establish dated, public, enabling prior art over the mechanism it describes, so that the technique remains free for everyone to use and cannot be patented by others. Publication date: 2026-07-03.

---

What it is

When a workload's image is large (~1 GB) and its nodes cold-pull slowly (measured 7 min on one node, 33–65 min on others), a naive maintenance-page deploy engages maintenance first and then eats the whole pull as user-facing downtime — a measured ~13-minute outage. This project discloses a control loop that eliminates that:

1. Prepull-before-maintenance — build and pull run while the site is still up; the maintenance window is engaged only afterward, so it brackets only the pod swap.
2. DaemonSet image-present barrier — a DaemonSet whose container image is the target workload image, with a trivially-true readiness probe, turns numberReady == desiredNumberScheduled into a precise per-node "image cached" barrier that gates when maintenance engages. Read straight off first-class Kubernetes status — no registry query, no on-node exec, no CRD.
3. Cache pin — the same DaemonSet stays resident, keeping the image referenced so node image-GC doesn't evict it between deploys.
4. Graceful degradation — a prepull miss is non-fatal; it falls through into a three-valued rollout supervisor (COMPLETE / REAL_FAILURE / TIMEOUT_NO_FAILURE) that never rolls back a still-pulling pod (silence is not failure).
5. TTL consistency invariant — the maintenance-lock TTL is derived arithmetically from the rollout timeout and asserted before the window opens, so a background watchdog can never clear maintenance mid-rollout and expose a half-rolled pod.
6. Volume-holder pinning — for the single-writer RWO volume, scheduling is pinned to the volume-holder node for the window (and reversed on exit), so neither the forward rollout nor a rollback can multi-attach.

Measured result: a ~13-minute outage collapsed to pod-swap time. The offline reference reproduces an ~81× collapse (30 s vs. 40.5 m).

Why it's novel

Standalone image warmers (kube-fledged, OpenKruise ImagePullJob/NodeImage) stop at "image is on the nodes." Here the barrier gates the maintenance flip, a barrier miss degrades into the rollout supervisor, and the lock TTL is an invariant derived from the rollout deadline — one unified control loop, not three independent knobs. See docs/PRIOR-ART.md for the delta table and the honest novelty nub.

Repository layout

Path	What
DEFENSIVE-PUBLICATION.md	The full ~5000-word disclosure: mechanism, data model, worked example, prior-art delta, claims.
docs/FIGURES.md	Diagrams with captions (choreography, barrier, ternary supervisor, TTL invariant, outage collapse).
docs/PRIOR-ART.md	Real references, delta table, novelty nub.
docs/OPEN-SOURCE-APP.md	How the reference maps to a real app + AKS deployment sketch.
src/	Clean-room, dependency-free, offline-runnable Node.js (ESM) reference.

Run the reference (offline, no dependencies)

cd src
node example.js

No network, no cluster, no credentials. It runs three scenarios against a deterministic virtual-time cluster stub and asserts the outcomes:

• A prepull-before-maintenance → ~30 s outage (rollout-ok);
• B no prepull → ~40.5 m outage (pull falls inside the window; still tolerated, no false rollback);
• C broken image → REAL_FAILURE → rollback under the volume pin.

Status of constants

Empirically-tuned production constants (exact rollout/prepull timeouts, poll cadences, margin terms, watchdog cadence) are [WITHHELD — trade secret]; illustrative values are supplied so the disclosure is fully enabling. Measured outcomes are disclosed for enablement.

License

Dual-licensed:

• AGPL-3.0-or-later — network copyleft; use it freely under those terms.
• Commercial license — from Gus IT LLC (Florida, USA) for organizations that cannot adopt AGPL. Contact gus@gusit.de.

Author: Gustavo Assuncao, PhD · Publisher: Gus IT LLC · 2026-07-03.

No secrets, credentials, tokens, or proprietary source are contained in this repository. It describes mechanisms, never credentials.