Capstone: a mini-PaaS — registry, build, run, health, and zero-downtime rollout

The five stages, as one pipeline

Before reading the five contracts below, notice what the hook incident actually was: not a single missing feature, but a missing composition. Each contract individually looked acceptable; together they were missing the one that makes the others meaningful.

Everything in this unit is a stage of the same machine. A minimal production platform — your mini-PaaS — is the composition of five contracts, each of which fails the others if it is wrong.

1 · Registry — immutability. The registry is the source of truth for artifacts, and its one non-negotiable rule is that deployments reference an immutable digest, not a mutable tag. myapp:latest can be overwritten; myapp@sha256:9f2c... cannot — the same digest always pulls the exact same bytes. Pin digests in the deploy manifest and a rollback genuinely returns to known-good code, two pods can never disagree about what latest means, and an image-pull is reproducible across nodes and time. Tags are convenient labels for humans; digests are the contract for machines.

2 · Build — slim and reproducible. A multi-stage build (from the slimming lesson) compiles in a toolchain stage and ships a ~25 MB distroless artifact, so the new version pulls onto cold nodes in ~2 s during the rollout instead of stalling it for 90 s. The build is pinned (base image by digest, dependencies by lockfile) so the digest is deterministic — the same source produces the same image.

3 · Run — bounded resources. Every container runs with a memory limit (from the OOM lesson) so one bad release cannot OOM the node and take down the other version mid-rollout, plus a cgroup-aware runtime target (GOMEMLIMIT / MaxRAMPercentage) so the runtime stays under the wall. Bounded resources are what make it safe to run old and new versions side by side during a rollout.

4 · Health — honest gating. A readiness probe that runs a real query (from the health lesson) gates traffic: a new pod receives no requests until it is genuinely ready, and a sick pod drains. This is the signal the rollout controller waits on — without honest readiness, “rollout complete” is a lie and traffic hits a pod that cannot serve.

The rollout — composing it into zero downtime

The fifth contract is the rolling deploy, and it only works because the other four hold. A rolling update replaces pods incrementally under two knobs: maxUnavailable (how many existing pods may be down at once — set low, e.g. 0 or 25%, to preserve capacity) and maxSurge (how many extra pods may be created above the desired count, e.g. 25%, to add new-version capacity before removing old).

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxUnavailable: 0      # never drop below desired capacity
    maxSurge: 1            # bring up one new pod before retiring an old one

The sequence ties the whole track together. The controller creates a new pod from the digest-pinned slim image (stages 1–2); it pulls in ~2 s and starts under its memory limit (stage 3); the controller waits for the new pod’s honest readiness probe to pass before sending it traffic (stage 4); only then does it terminate an old pod, which runs its preStop → SIGTERM → drain lifecycle (from the health lesson) so its in-flight requests finish; and it repeats until every pod is the new version — with maxUnavailable: 0 capacity never dips, and with honest readiness no traffic ever lands on a not-ready pod. Remove any one contract and the rollout breaks: a mutable tag makes rollback unreliable, a fat image stalls the surge, a missing memory limit lets the new version OOM the node hosting the old one, a dishonest probe routes traffic to a dead pod, and a missing preStop drops the in-flight requests of the pods being retired. That is the lesson of the whole unit: production containers are not five independent best practices — they are one pipeline where each stage is load-bearing for the next.