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
- Variables
- func AcquireLock(ctx context.Context) (func(), error)
- func CheckRunnerInstalled() (bool, error)
- func InferComposeFilesFromWorkingDir(ctx context.Context, cli *client.Client, workingDir string) []string
- func NormalizeImageReference(imageRef string) (normalized string, pinnedDigest string, immutable bool, err error)
- func ParseComposeConfigFiles(configFilesStr string) []string
- func PrimaryContainerName(ctr container.Summary) string
- func PullAndInspectImage(ctx context.Context, cli ContainerClient, imageRef string) (client.ImageInspectResult, error)
- func RecoverStandaloneUpdate(ctx context.Context, cli ContainerClient) error
- func ReplaceStandalone(ctx context.Context, cli ContainerClient, before container.InspectResponse, ...) (container.InspectResponse, error)
- func RunComposeProject(ctx context.Context, target ComposeTarget, emitter ComposeLineEmitter, ...) error
- func RunScheduled(ctx context.Context, configPath string, report func(message string)) error
- func StandaloneCreateOptions(inspect container.InspectResponse, imageRef string, name string) (client.ContainerCreateOptions, error)
- func TranslateComposeConfigFiles(ctx context.Context, cli *client.Client, configFiles []string) []string
- func TranslateContainerPathToHost(ctx context.Context, cli *client.Client, containerPath string) string
- func ValidateStandaloneEdit(ctx context.Context, cli ContainerClient, before container.InspectResponse, ...) error
- func ValidateTarget(target string) error
- func WaitForContainerReady(ctx context.Context, cli containerReadinessClient, containerID string) (container.InspectResponse, error)
- type ComposeLineEmitter
- type ComposeMessageCollector
- type ComposeProgress
- type ComposeTarget
- type ContainerClient
- type DockerContainerAutoUpdateMode
- type DockerContainerAutoUpdateOptions
- type DockerContainerAutoUpdateSettings
- type DockerContainerAutoUpdateState
- type DockerContainerAutoUpdateTarget
- type DockerContainerUpdateRequest
- type DockerContainerUpdateResult
- type DockerUpdateCheckResult
- type DockerUpdateCheckState
- type ImageUpdateStatus
- type Journal
- type StatusSnapshot
- type UnitSpec
Constants ¶
const ConfigPath = version.ConfigDir + "/docker-update.json"
ConfigPath is where the scheduled-update configuration is persisted.
const RunnerPath = version.BinDir + "/linuxio-docker-update"
RunnerPath is the root-sandboxed worker binary the scheduled service executes.
Variables ¶
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 ¶
AcquireLock takes the host-wide Docker update lock shared by scheduled and on-demand updates and by standalone container edits.
func CheckRunnerInstalled ¶
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 ¶
ParseComposeConfigFiles splits the comma-separated config-files label.
func PrimaryContainerName ¶
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 ¶
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 ¶
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 ¶
type ContainerClient interface {
ContainerInspect(context.Context, string, client.ContainerInspectOptions) (client.ContainerInspectResult, error)
ContainerList(context.Context, client.ContainerListOptions) (client.ContainerListResult, error)
ImagePull(context.Context, string, client.ImagePullOptions) (client.ImagePullResponse, error)
ContainerStop(context.Context, string, client.ContainerStopOptions) (client.ContainerStopResult, error)
ContainerRename(context.Context, string, client.ContainerRenameOptions) (client.ContainerRenameResult, error)
ContainerCreate(context.Context, client.ContainerCreateOptions) (client.ContainerCreateResult, error)
ContainerStart(context.Context, string, client.ContainerStartOptions) (client.ContainerStartResult, error)
ContainerRemove(context.Context, string, client.ContainerRemoveOptions) (client.ContainerRemoveResult, error)
// contains filtered or unexported methods
}
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 ¶
func SetAutoUpdate(ctx context.Context, cli *client.Client, opts DockerContainerAutoUpdateOptions) (DockerContainerAutoUpdateState, error)
SetAutoUpdate persists the schedule, renders the service and timer units, enables or disables the timer and returns the resulting state.
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 ¶
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 ¶
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.