saferollout

package
v1.10.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0, Apache-2.0 Imports: 6 Imported by: 0

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

View Source
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.

View Source
const DefaultHealthWait = 90 * time.Second

DefaultHealthWait bounds how long the promoted container may take to become healthy (or, with no healthcheck, to stay running).

View Source
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

func Run(ctx context.Context, dc docker.Client, sp Spec) error

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

func WaitHealthy(ctx context.Context, dc docker.Client, name string, timeout time.Duration) error

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.

func (Spec) TestName

func (s Spec) TestName() string

TestName is the throwaway container a Test rollout starts.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL