scheduling

Documentation

Overview

Package scheduling provides functionality for scheduling and executing container updates in Watchtower. It handles periodic scheduling using cron specifications, manages update concurrency, and ensures graceful shutdown of scheduled operations.

Index

• func RunUpgradesOnSchedule(ctx context.Context, deps ScheduleDeps) error
• func ShouldExitDueToInvalidRestart(c types.Container, runOnce bool) bool
• func WaitForRunningUpdate(log *zerolog.Logger, ctx context.Context, lock chan bool)
• type ScheduleDeps

Functions

func RunUpgradesOnSchedule

func RunUpgradesOnSchedule(ctx context.Context, deps ScheduleDeps) error

RunUpgradesOnSchedule schedules and executes periodic container updates according to the cron specification.

It sets up a cron scheduler, runs updates at specified intervals, and ensures graceful shutdown on interrupt signals (SIGINT, SIGTERM) or context cancellation, handling concurrency with a lock channel. If update-on-start is enabled, it triggers the first update immediately before starting the scheduler. If SkipFirstRun is true, it skips Watchtower self-update on the first scheduled run (useful after self-update cleanup).

Parameters:

• ctx: The context controlling the scheduler's lifecycle, enabling shutdown on cancellation.
• deps: Schedule dependencies including a complete BaseParams policy snapshot. deps.Logger is required and must be non-nil (nil panics on first log call).

Returns:

• error: An error if scheduling fails (e.g., invalid cron spec), nil on successful shutdown.

func ShouldExitDueToInvalidRestart

func ShouldExitDueToInvalidRestart(c types.Container, runOnce bool) bool

ShouldExitDueToInvalidRestart determines if the program should exit due to an invalid restart of an old Watchtower container.

This function checks two conditions:

1. The current container's name matches the watchtower-old-* prefix, indicating it is a predecessor renamed during self-update that should not run.
2. The current container is present in the container chain label, indicating it is an ancestor in the self-update lineage.

If either condition is true and runOnce is false, the program should exit to prevent an old Watchtower container from running.

Parameters:

• c: The current Watchtower container to check.
• runOnce: Whether the process is in run-once mode.

Returns:

• bool: True if the program should exit due to an invalid restart, false otherwise.

func WaitForRunningUpdate

func WaitForRunningUpdate(log *zerolog.Logger, ctx context.Context, lock chan bool)

WaitForRunningUpdate waits for any currently running update to complete before proceeding with shutdown. It checks the lock channel status and blocks with a timeout if an update is in progress.

Parameters:

• log: Process logger. Required and must be non-nil. A nil logger panics on the first log call.
• ctx: The context for cancellation, allowing early shutdown on context timeout.
• lock: The channel used to synchronize updates, ensuring only one runs at a time.

Types

type ScheduleDeps

type ScheduleDeps struct {
	// Logger is the process logger for scheduled runs. Required and must be non-nil.
	Logger *zerolog.Logger
	// Filter determines which containers are updated.
	Filter types.Filter
	// FilterDesc is a human-readable description of the filter for startup messaging.
	FilterDesc string
	// Lock ensures only one update runs at a time, or nil to create a new one.
	Lock chan bool
	// ScheduleSpec is the cron-formatted schedule string for periodic updates.
	ScheduleSpec string
	// Startup holds resolved values for startup messaging (no flag reads).
	// Callers must set Filtering, Scope, Client, Notifier, and Version on Startup.
	// RunUpgradesOnSchedule only applies Sched and UpdateOnStart at send time.
	Startup logging.StartupParams
	// WriteStartupMessage writes the startup message with scheduling information.
	WriteStartupMessage func(logging.StartupParams)
	// RunUpdate performs container updates and sends notifications.
	RunUpdate func(context.Context, types.Filter, types.UpdateParams) *metrics.Metric
	// Client is retained for callers. Prefer Startup.Client for messaging.
	Client container.Client
	// Scope is retained for callers. Prefer Startup.Scope for messaging.
	Scope string
	// Notifier is closed on schedule shutdown. Prefer Startup.Notifier for messaging.
	Notifier types.Notifier
	// MetaVersion is retained for callers. Prefer Startup.Version for messaging.
	MetaVersion string
	// UpdateOnStart triggers an immediate update before the scheduler starts.
	UpdateOnStart bool
	// SkipFirstRun skips Watchtower self-update on the first scheduled run
	// (useful after self-update cleanup of old instances).
	SkipFirstRun bool
	// CurrentWatchtowerContainer is the running Watchtower container for parent checking.
	CurrentWatchtowerContainer types.Container
	// StartupMessageSent is true when the startup message was already sent
	// (for example by the HTTP API in blocking mode).
	StartupMessageSent bool
	// BaseParams is the complete update policy snapshot for every scheduled tick.
	// Must include Cleanup, MonitorOnly, UseComposeDependsOn, ReviveStopped, and
	// all other process-wide UpdateParams fields.
	BaseParams types.UpdateParams
}

ScheduleDeps holds dependencies for scheduled update runs.

BaseParams must be a complete types.UpdateParams snapshot from config.UpdateParams (or an equivalent full construction). Each tick copies BaseParams and applies only per-run fields such as SkipSelfUpdate.