dockerupdate

package
v0.0.0-...-44b29c8 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: Apache-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package dockerupdate is the Docker image-update engine: update checks, the standalone and Compose replacement flows, the scheduled runner and its systemd timer, and the files they persist. It is shared by the bridge (whose docker.update_container job calls UpdateContainerWait) and the root-sandboxed linuxio-docker-update binary (which runs the scheduled pass), so it imports only common packages. The bridge re-exports the wire types below from bridge/apischema as aliases; the generated frontend contract names them by their Go type name, so renaming one is a contract change.

Index

Constants

View Source
const ConfigPath = version.ConfigDir + "/docker-update.json"

ConfigPath is where the scheduled-update configuration is persisted.

View Source
const RunnerPath = version.BinDir + "/linuxio-docker-update"

RunnerPath is the root-sandboxed worker binary the scheduled service executes.

Variables

View Source
var WorkerUnit = UnitSpec{
	Requires:        []string{"docker.service"},
	After:           []string{"docker.service", "network-online.target"},
	Wants:           []string{"network-online.target"},
	ProtectSystem:   "strict",
	ProtectHome:     "read-only",
	ReadWritePaths:  []string{version.DataDir, "/run"},
	PrivateTmp:      true,
	NoNewPrivileges: true,
}

WorkerUnit is the confinement of the update worker.

Functions

func AcquireLock

func AcquireLock(ctx context.Context) (func(), error)

AcquireLock takes the host-wide Docker update lock shared by scheduled and on-demand updates and by standalone container edits.

func CheckRunnerInstalled

func CheckRunnerInstalled() (bool, error)

CheckRunnerInstalled reports whether the update worker binary is installed as an executable regular file.

func InferComposeFilesFromWorkingDir

func InferComposeFilesFromWorkingDir(ctx context.Context, cli *client.Client, workingDir string) []string

InferComposeFilesFromWorkingDir looks for a conventionally named Compose file in the translated working directory.

func NormalizeImageReference

func NormalizeImageReference(imageRef string) (normalized string, pinnedDigest string, immutable bool, err error)

NormalizeImageReference returns the canonical tagged reference for imageRef, plus the pinned digest when the reference is immutable.

func ParseComposeConfigFiles

func ParseComposeConfigFiles(configFilesStr string) []string

ParseComposeConfigFiles splits the comma-separated config-files label.

func PrimaryContainerName

func PrimaryContainerName(ctr container.Summary) string

PrimaryContainerName returns the first container name without its leading slash.

func PullAndInspectImage

func PullAndInspectImage(
	ctx context.Context,
	cli ContainerClient,
	imageRef string,
) (client.ImageInspectResult, error)

PullAndInspectImage pulls imageRef and returns the inspected result.

func RecoverStandaloneUpdate

func RecoverStandaloneUpdate(ctx context.Context, cli ContainerClient) error

RecoverStandaloneUpdate finishes or rolls back an interrupted standalone replacement recorded in the default journal.

func ReplaceStandalone

func ReplaceStandalone(
	ctx context.Context,
	cli ContainerClient,
	before container.InspectResponse,
	options client.ContainerCreateOptions,
	journal *Journal,
) (container.InspectResponse, error)

ReplaceStandalone parks before under a rollback name, creates and verifies the replacement described by options, then removes the rollback container. Any failure before that point restores the original. It returns the verified replacement.

func RunComposeProject

func RunComposeProject(ctx context.Context, target ComposeTarget, emitter ComposeLineEmitter, args ...string) error

RunComposeProject executes a docker compose command, streaming output lines to the emitter. Every config file is passed in label order so projects that use override files are reconciled with the same effective configuration.

func RunScheduled

func RunScheduled(ctx context.Context, configPath string, report func(message string)) error

RunScheduled executes one configured check or update pass. It is called by the short-lived Docker update worker; no updater daemon remains resident between timer activations. report, when not nil, is told what the pass is doing.

func StandaloneCreateOptions

func StandaloneCreateOptions(
	inspect container.InspectResponse,
	imageRef string,
	name string,
) (client.ContainerCreateOptions, error)

StandaloneCreateOptions copies the inspected container's recreation configuration into create options for a replacement running imageRef as name.

func TranslateComposeConfigFiles

func TranslateComposeConfigFiles(ctx context.Context, cli *client.Client, configFiles []string) []string

TranslateComposeConfigFiles maps Compose file paths as seen from inside a container onto host paths, dropping files that cannot be found.

func TranslateContainerPathToHost

func TranslateContainerPathToHost(ctx context.Context, cli *client.Client, containerPath string) string

TranslateContainerPathToHost attempts to translate a container path to a host path by inspecting volume mounts across all containers to find the correct mount source

func ValidateStandaloneEdit

func ValidateStandaloneEdit(ctx context.Context, cli ContainerClient, before container.InspectResponse, journal *Journal) error

ValidateStandaloneEdit checks that before can be replaced in place by an edit: no interrupted update is journaled, and the container is a stable standalone container with no dependents. Stopped containers are allowed.

func ValidateTarget

func ValidateTarget(target string) error

ValidateTarget checks the container ID of an update request.

func WaitForContainerReady

func WaitForContainerReady(
	ctx context.Context,
	cli containerReadinessClient,
	containerID string,
) (container.InspectResponse, error)

WaitForContainerReady polls the container until it is running and, when it has a health check, healthy.

Types

type ComposeLineEmitter

type ComposeLineEmitter func(msgType, message string, progress *ComposeProgress)

ComposeLineEmitter receives each line of compose output. For structured `--progress=json` events, progress is non-nil and message holds a humanized rendering of the same event; for plain text lines progress is nil.

type ComposeMessageCollector

type ComposeMessageCollector struct {
	// contains filtered or unexported fields
}

ComposeMessageCollector accumulates compose output so a failure can report it.

func (*ComposeMessageCollector) Emit

func (c *ComposeMessageCollector) Emit(_ string, message string, _ *ComposeProgress)

Emit is a ComposeLineEmitter that records each non-empty line.

func (*ComposeMessageCollector) String

func (c *ComposeMessageCollector) String() string

String returns the collected lines joined by newlines.

type ComposeProgress

type ComposeProgress struct {
	ID       string `json:"id"` // layer id (e.g. "fbcfea79c1c4") or group (e.g. "Image alpine:3.17")
	ParentID string `json:"parent_id,omitempty"`
	Text     string `json:"text"`              // "Pulling", "Downloading", "Extracting", "Pull complete", "Creating", "Started"…
	Status   string `json:"status"`            // "Working" | "Done" | "Error"
	Details  string `json:"details,omitempty"` // Docker's humanized current (e.g. "2.097MB")
	Current  int64  `json:"current,omitzero"`
	Total    int64  `json:"total,omitzero"`
	Percent  int    `json:"percent,omitzero"`
}

ComposeProgress is a single structured progress event parsed from `docker compose --progress=json`. The JSON tags mirror Docker's own event schema so the same struct is used to both decode Docker's output and to encode the payload sent to the frontend.

type ComposeTarget

type ComposeTarget struct {
	Name               string
	ConfigFiles        []string
	EnvironmentFiles   []string
	IsolateEnvironment bool
	WorkingDir         string
}

ComposeTarget identifies a Compose project by its config files, environment files and working directory. IsolateEnvironment restricts the docker compose process to a fixed set of environment variables.

type ContainerClient

ContainerClient is the slice of the Docker client the update and replacement flows use; tests substitute a fake.

type DockerContainerAutoUpdateMode

type DockerContainerAutoUpdateMode string

type DockerContainerAutoUpdateOptions

type DockerContainerAutoUpdateOptions struct {
	DockerContainerAutoUpdateSettings
	Enabled bool `json:"enabled"`
}

DockerContainerAutoUpdateOptions adds Enabled, which reports whether the systemd timer is on and is never saved.

type DockerContainerAutoUpdateSettings

type DockerContainerAutoUpdateSettings struct {
	Cleanup        bool                          `json:"cleanup"`
	ContainerNames []string                      `json:"container_names"`
	IncludeStopped bool                          `json:"include_stopped"`
	Mode           DockerContainerAutoUpdateMode `json:"mode"`
	ReviveStopped  bool                          `json:"revive_stopped"`
	Time           string                        `json:"time"`
	UpdateAll      bool                          `json:"update_all"`
	UpdateStopped  bool                          `json:"update_stopped"`
}

DockerContainerAutoUpdateSettings is every saved scheduled-update option. It is embedded in the wire type below and in the on-disk document, so a new saved option is one field here.

type DockerContainerAutoUpdateState

type DockerContainerAutoUpdateState struct {
	Available             bool                              `json:"available"`
	Containers            []DockerContainerAutoUpdateTarget `json:"containers"`
	Error                 *string                           `json:"error,omitzero"`
	MissingContainerNames []string                          `json:"missing_container_names"`
	Options               DockerContainerAutoUpdateOptions  `json:"options"`
	TimerActive           bool                              `json:"timer_active"`
	TimerEnabled          bool                              `json:"timer_enabled"`
}

func GetAutoUpdate

GetAutoUpdate reports the scheduled-update configuration, the timer state and the containers the schedule can target.

func SetAutoUpdate

SetAutoUpdate persists the schedule, renders the service and timer units, enables or disables the timer and returns the resulting state.

type DockerContainerAutoUpdateTarget

type DockerContainerAutoUpdateTarget struct {
	ID              string  `json:"id"`
	Image           string  `json:"image"`
	Name            string  `json:"name"`
	Selected        bool    `json:"selected"`
	State           string  `json:"state"`
	MutationAllowed bool    `json:"mutationAllowed"`
	MutationReason  *string `json:"mutationReason,omitzero"`
}

type DockerContainerUpdateRequest

type DockerContainerUpdateRequest struct {
	ContainerID string `json:"containerId"`
}

DockerContainerUpdateRequest names the container one update replaces.

func (DockerContainerUpdateRequest) Target

func (r DockerContainerUpdateRequest) Target() []string

Target makes the container the job's target, so a second update of the same container is refused while one runs.

type DockerContainerUpdateResult

type DockerContainerUpdateResult struct {
	ContainerID     string `json:"containerId"`
	ContainerName   string `json:"containerName"`
	Error           string `json:"error,omitempty"`
	Image           string `json:"image"`
	NewImageID      string `json:"newImageId,omitempty"`
	PreviousImageID string `json:"previousImageId,omitempty"`
	Updated         bool   `json:"updated"`
}

func UpdateContainerWait

func UpdateContainerWait(
	ctx context.Context,
	containerID string,
	lockWait time.Duration,
	report func(phase, message string),
) (DockerContainerUpdateResult, error)

UpdateContainerWait updates one container to its registry image, reporting each phase to report (nil discards progress). It waits up to lockWait for the engine lock another update holds; a lockWait of 0 waits until ctx ends.

type DockerUpdateCheckResult

type DockerUpdateCheckResult struct {
	Checked     int `json:"checked"`
	Errors      int `json:"errors"`
	Uncheckable int `json:"uncheckable"`
	Updates     int `json:"updates"`
}

func RefreshContainerUpdate

func RefreshContainerUpdate(ctx context.Context, cli *client.Client, containerID string) (DockerUpdateCheckResult, error)

RefreshContainerUpdate checks one container against its configured registry reference and refreshes only that container's status entry.

func RefreshImageUpdates

func RefreshImageUpdates(ctx context.Context, cli *client.Client) (DockerUpdateCheckResult, error)

RefreshImageUpdates checks all running containers against their configured registry references and replaces the persistent status snapshot.

type DockerUpdateCheckState

type DockerUpdateCheckState string
const (
	DockerUpdateCheckStateCurrent     DockerUpdateCheckState = "current"
	DockerUpdateCheckStateAvailable   DockerUpdateCheckState = "available"
	DockerUpdateCheckStateUncheckable DockerUpdateCheckState = "uncheckable"
	DockerUpdateCheckStateError       DockerUpdateCheckState = "error"
)

type ImageUpdateStatus

type ImageUpdateStatus struct {
	ContainerID     string                 `json:"container_id,omitempty"`
	ContainerName   string                 `json:"container_name,omitempty"`
	CheckReason     string                 `json:"check_reason,omitempty"`
	CheckState      DockerUpdateCheckState `json:"check_state"`
	ImageID         string                 `json:"image_id,omitempty"`
	ImageRef        string                 `json:"image_ref,omitempty"`
	UpdateAvailable bool                   `json:"update_available"`
	LocalDigest     string                 `json:"local_digest,omitempty"`
	RemoteDigest    string                 `json:"remote_digest,omitempty"`
	CheckedAt       time.Time              `json:"checked_at"`
	Err             string                 `json:"error,omitempty"`
}

ImageUpdateStatus is the persisted result of the last update check for one container and its image.

type Journal

type Journal struct {
	// contains filtered or unexported fields
}

Journal records an in-flight standalone replacement so a crash can be rolled back or finished by the next update or container edit.

func DefaultJournal

func DefaultJournal() *Journal

DefaultJournal returns the journal shared by every standalone replacement.

func NewJournal

func NewJournal(path string) *Journal

NewJournal returns a journal stored at path.

type StatusSnapshot

type StatusSnapshot struct {
	// contains filtered or unexported fields
}

StatusSnapshot indexes the persisted statuses for lookup by container or image.

func NewStatusSnapshot

func NewStatusSnapshot(statuses []ImageUpdateStatus) StatusSnapshot

NewStatusSnapshot indexes statuses by container ID, container name, image ID and image reference.

func ReadStatusSnapshot

func ReadStatusSnapshot() StatusSnapshot

ReadStatusSnapshot loads the persisted update statuses; a missing or invalid file reads as empty.

func (StatusSnapshot) ForContainer

func (s StatusSnapshot) ForContainer(containerID string) (ImageUpdateStatus, bool)

func (StatusSnapshot) ForContainerName

func (s StatusSnapshot) ForContainerName(containerName string) (ImageUpdateStatus, bool)

func (StatusSnapshot) ForImage

func (s StatusSnapshot) ForImage(img image.Summary) (ImageUpdateStatus, bool)

ForImage matches an image by ID first, then by any of its tags or digests.

type UnitSpec

type UnitSpec struct {
	Requires        []string
	After           []string
	Wants           []string
	ProtectSystem   string
	ProtectHome     string
	ReadWritePaths  []string
	PrivateTmp      bool
	NoNewPrivileges bool
}

UnitSpec is how the scheduled update worker is confined and ordered; the service unit text (timer.go) is derived from it.

Jump to

Keyboard shortcuts

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