Documentation
¶
Overview ¶
Package saferollout replaces a running container with a new image without a blind cutover. It generalizes the pattern edgegateway used for node gateways — start the new image under a throwaway name, watch it, then promote — and adds the missing half: a rollback, so a failed promotion never leaves nothing running.
Index ¶
Constants ¶
const ( PhasePulling = "pulling" PhaseTesting = "testing" PhaseObserving = "observing" PhasePromoting = "promoting" PhaseVerifying = "verifying" PhaseRollingBack = "rolling-back" PhaseRolledBack = "rolled-back" PhaseFailed = "failed" PhaseDone = "done" )
Phases reported through OnPhase, in order. "failed" is terminal and carries the cause; "rolled-back" means the previous image is running again.
const DefaultHealthWait = 90 * time.Second
DefaultHealthWait bounds how long the promoted container may take to become healthy (or, with no healthcheck, to stay running).
const DefaultObserve = 25 * time.Second
DefaultObserve is how long a test container must stay up before its image is trusted. A bad image or config almost always exits on boot, so simply still being alive after the window is a strong signal.
Variables ¶
This section is empty.
Functions ¶
func EnsureImage ¶
func EnsureImage(ctx context.Context, dc docker.Client, ref string, auth *docker.RegistryAuth, notify func(string, ...any)) error
EnsureImage makes an image available, preferring a fresh pull but accepting one already on the host. A hard pull is wrong for the two cases that matter most at install time: an air-gapped host, and an operator running a locally built or pre-loaded image. Docker's own `docker run` behaves the same way.
func Run ¶
Run performs the rollout. It is not atomic: the window between removing the old container and the new one becoming healthy is real downtime. What it guarantees is that the window is short and ends with *something* running. Note that rolling an image back does NOT roll back a migration the new image already applied.
func WaitHealthy ¶
WaitHealthy blocks until the container is healthy, or until timeout. "Healthy" means whatever the container can prove: Docker's verdict when there is a healthcheck, otherwise that it stayed running for a settle period — rather than the instant after `docker run` returns, which a crash-looping container also passes.
Types ¶
type Spec ¶
type Spec struct {
// Name is the live container. Image is the new image, already resolved.
Name string
Image string
// Build returns the run spec for the container. It is called with the name to create and the image to run, so
// the caller can vary the spec between the test container and the live one — chiefly by NOT publishing ports
// on the test container, since the live one still holds them.
Build func(name, image string) docker.RunSpec
// Test runs the new image under Name+"-test" first and watches it for Observe before promoting. Skip it for
// containers that cannot safely run a second copy against the same state — a second control plane would
// migrate the live database, and a second Postgres cannot open the same data directory.
Test bool
Observe time.Duration
// HealthWait bounds the post-promotion check. Zero uses DefaultHealthWait.
HealthWait time.Duration
// Rollback restores the previous image if the promoted container never becomes healthy. Almost always wanted.
// The exception is a container whose new image has already made a one-way change to shared state — see the
// migration caveat on Run.
Rollback bool
// OnPhase is called as each phase begins, and once with PhaseFailed on error.
OnPhase func(phase string, cause error)
}
Spec describes one rollout.