container

package
v1.14.3 Latest Latest
Warning

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

 Go to latest Published: Mar 4, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Overview

Package container provides functionality for managing Docker containers in Watchtower. It defines types and methods to interact with the Docker API, handle container metadata, and implement lifecycle operations like updates, restarts, and image management.

Key components:

  • Container: Implements types.Container interface for state and metadata operations.
  • Client: Interface for Docker API interactions (list, start, stop, etc.).
  • imageClient: Manages image pulling and staleness checks.
  • Filters: Logic to select containers by names, labels, and scopes.
  • Labels: Methods to interpret Watchtower-specific labels and lifecycle hooks.

Usage example: 

cli := container.NewClient(container.ClientOptions{})
containers, _ := cli.ListContainers(filters.NoFilter)
for _, c := range containers {
    stale, _, _ := cli.IsContainerStale(c, types.UpdateParams{})
    if stale {
        cli.StopContainer(c, 10*time.Second)
    }
}

The package integrates with Docker’s API via docker/docker client libraries and supports Watchtower’s update workflows, including authentication, scope filtering, and custom lifecycle hooks.

Index

Constants

View Source 
const (
	// CPUCopyModeAuto indicates automatic detection of container runtime for
	// CPU copying behavior.
	CPUCopyModeAuto = "auto"

	// DaemonInitTimeout is the default timeout for Docker daemon initialization operations.
	// This timeout applies to initial connection, ping, API version negotiation, and
	// server version retrieval during client initialization.
	// The value is 30 seconds, which should be sufficient for most Docker daemon
	// initialization scenarios while preventing indefinite hangs.
	DaemonInitTimeout = 30 * time.Second
)

Constants for CPUCopyMode values.

View Source 
const (

	// ContainerChainLabel accumulates container IDs across Watchtower self-updates, comma-separated.
	ContainerChainLabel = "com.centurylinklabs.watchtower.container-chain"
)

Watchtower-specific labels identify containers managed by Watchtower and their configurations.

Variables

View Source 
var (
	ReadMountinfoFunc = os.ReadFile
	ReadCgroupFunc    = os.ReadFile
)

File reading functions for testing mocks.

View Source 
var (

	// ErrContainerIDNotFound indicates the container ID could not be found using hostname matching.
	ErrContainerIDNotFound = errors.New("HOSTNAME environment variable is not set")
)

Errors for container ID detection operations in container_id.go.

View Source 
var (

	// ErrUnexpectedContainerType indicates an unexpected container type was encountered.
	ErrUnexpectedContainerType = errors.New("unexpected container type")
)

Errors for container configuration and metadata operations in container.go.

Functions

func ContainsWatchtowerLabel 

func ContainsWatchtowerLabel(labels map[string]string) bool

ContainsWatchtowerLabel checks if the container is Watchtower.

Parameters:

  • labels: Label map to check.

Returns:

  • bool: True if watchtower label is "true", false otherwise.

func DetectCycles added in v1.13.0 

func DetectCycles(containers []types.Container) map[string]bool

DetectCycles identifies all containers involved in circular dependencies using three-color DFS.

This function constructs a directed dependency graph from container relationships and uses depth-first search with node coloring to detect all cycles. The algorithm ensures that every connected component of the graph is explored, identifying all containers that are part of any circular dependency chain.

Graph Construction: 1. Each container becomes a node identified by its resolved container identifier 2. Dependencies (links) become directed edges from dependent to dependency 3. Container names are normalized to handle Docker Compose service name variations 4. Only containers present in the input list are included (missing dependencies ignored)

DFS Traversal Strategy: - Start DFS from each unvisited (white) node to ensure all components are explored - The three-color algorithm detects cycles during traversal and marks all involved nodes - Multiple DFS calls are needed because the graph may have disconnected components

Implementation Rationale: - Uses adjacency list representation for efficient neighbor iteration (O(1) per edge) - Normalization ensures consistent handling of Docker Compose vs container names - Returns all cyclic nodes rather than just detecting presence, enabling targeted handling - Single pass through graph with O(V + E) complexity makes it suitable for large deployments

Time Complexity: O(V + E) where V = containers, E = dependency links Space Complexity: O(V + E) for graph storage and DFS recursion stack

Edge Cases: - Empty container list: Returns empty map - No dependencies: Returns empty map (no cycles possible) - Single container with self-dependency: Detected as cycle - Multiple disconnected cycles: All detected and marked - Missing dependency targets: Ignored (only analyze provided containers)

Parameters:

  • containers: List of containers to analyze for cycles. Should not be nil.

Returns:

  • map[string]bool: Map where keys are container names and values indicate cycle involvement. true = container is part of at least one cycle, false/absent = no cycles detected. Empty map returned if no cycles found.

func ExtractContainerIDFromPath added in v1.14.0 

func ExtractContainerIDFromPath(path string) types.ContainerID

ExtractContainerIDFromPath extracts container ID from a path containing /containers/<id>.

func GetContainerIDFromCgroupFile added in v1.14.0 

func GetContainerIDFromCgroupFile() (types.ContainerID, error)

GetContainerIDFromCgroupFile retrieves the container ID from /proc/<pid>/cgroup. Uses the cgroup file to find Docker container paths.

func GetContainerIDFromHostname added in v1.14.0 

func GetContainerIDFromHostname(ctx context.Context, client Client) (types.ContainerID, error)

GetContainerIDFromHostname retrieves the container ID by matching the HOSTNAME env var. Uses Docker API to list containers and find matching hostname.

func GetContainerIDFromMountinfo added in v1.14.0 

func GetContainerIDFromMountinfo() (types.ContainerID, error)

GetContainerIDFromMountinfo retrieves the container ID from /proc/self/mountinfo. Uses the mountinfo file to find container paths containing /containers/<id>.

func GetCurrentContainerID added in v1.14.0 

func GetCurrentContainerID(ctx context.Context, client Client) (types.ContainerID, error)

GetCurrentContainerID retrieves the current container ID using a fallback strategy. It attempts multiple detection methods in order of preference and reliability.

The detection methods are tried in the following order: 1. Mountinfo-based detection - cgroup v2 compatible 2. Cgroup file parsing - cgroup v1 compatible 3. Hostname matching - fallback using Docker API

Parameters:

  • client: Docker client interface for container operations

Returns:

  • types.ContainerID: The detected container ID if successful
  • error: Non-nil if all detection methods fail, containing the last error encountered

func GetEffectiveScope added in v1.14.0 

func GetEffectiveScope(container types.Container, currentScope string) (string, error)

GetEffectiveScope determines the effective operational scope by prioritizing explicit scope over scope derived from the container's label. This is crucial for self-update scenarios where a new Watchtower instance needs to inherit the same scope as the instance being replaced to maintain proper isolation and prevent cross-scope interference during the update process.

Parameters:

  • container: The current Watchtower container.
  • currentScope: The explicit scope value (takes priority if non-empty).

Returns:

  • string: The effective scope.
  • error: Non-nil if derivation fails.

func GetLinksFromWatchtowerLabel added in v1.14.0 

func GetLinksFromWatchtowerLabel(c *Container, clog *logrus.Entry) []string

GetLinksFromWatchtowerLabel extracts dependency links from the watchtower depends-on label.

It parses the com.centurylinklabs.watchtower.depends-on label value, splitting on commas and normalizing each container name, returning all normalized links, including potential self-references.

Note: Watchtower depends-on labels reference container names directly, unlike Compose depends-on, which references services within the same project. Therefore, we do not prefix with project name for Watchtower labels.

Parameters:

  • c: Container instance
  • clog: Logger instance for debug output

Returns:

  • []string: List of all normalized links, including potential self-references, or nil if label not present

func GetSourceContainer added in v1.8.6 

func GetSourceContainer(
	ctx context.Context,
	api dockerClient.APIClient,
	containerID types.ContainerID,
) (types.Container, error)

GetSourceContainer retrieves detailed information about a container by its ID.

It resolves network mode if it references another container.

Parameters:

  • ctx: Context for cancellation and timeout control.
  • api: Docker API client.
  • containerID: ID of the container to inspect.

Returns:

  • types.Container: Container object if successful.
  • error: Non-nil if inspection fails, nil on success.

func IsWatchtowerParent added in v1.14.0 

func IsWatchtowerParent(currentID types.ContainerID, chain string) bool

IsWatchtowerParent checks if the current container ID exists in the comma-separated container-chain label values.

It handles edge cases like empty chain or invalid IDs by returning false appropriately. The chain values are trimmed of whitespace before comparison.

Parameters:

  • currentID: The container ID to check for in the chain.
  • chain: Comma-separated string of container IDs from the container-chain label.

Returns:

  • bool: True if currentID is found in the chain, false otherwise.

func ListSourceContainers added in v1.8.6 

func ListSourceContainers(
	ctx context.Context,
	api dockerClient.APIClient,
	opts ClientOptions,
	filter types.Filter,
	isPodmanOptional ...bool,
) ([]types.Container, error)

ListSourceContainers retrieves a list of containers from the container runtime host.

It filters containers based on options and a provided filter function.

Parameters:

  • ctx: Context for cancellation and timeout control.
  • api: Docker API client.
  • opts: Client options for filtering.
  • filter: Function to filter containers.
  • isPodmanOptional: Optional variadic flag indicating Podman runtime (defaults to false).

Returns:

  • []types.Container: Filtered list of containers.
  • error: Non-nil if listing fails, nil on success.

func ParseContainerIDFromCgroupString added in v1.14.0 

func ParseContainerIDFromCgroupString(cgroupString string) (types.ContainerID, error)

ParseContainerIDFromCgroupString parses the cgroup string to extract container ID.

func ParseContainerIDFromMountinfo added in v1.14.0 

func ParseContainerIDFromMountinfo(mountinfoString string) (types.ContainerID, error)

ParseContainerIDFromMountinfo parses the mountinfo string to extract container ID.

func RenameTargetContainer added in v1.8.6 

func RenameTargetContainer(
	ctx context.Context,
	api Operations,
	targetContainer types.Container,
	targetName string,
) error

RenameTargetContainer renames an existing container to the specified target name in Watchtower.

Parameters:

  • ctx: Context for cancellation and timeout control.
  • api: Interface for container operations (Operations).
  • targetContainer: Container to be renamed.
  • targetName: New name for the container.

Returns:

  • error: Non-nil if rename fails, nil on success.

func ResolveContainerIdentifier added in v1.13.0 

func ResolveContainerIdentifier(c types.Container) string

ResolveContainerIdentifier returns a standardized container identifier used for dependency resolution, update coordination, logging, and cycle detection.

Container identifier formats:

  1. project-service-containerNumber (if project name, service name, and container number are all available)
  2. project-service (if project name and service name are available)
  3. service (if only service name is available)
  4. container name (if name is available)
  5. container ID (fallback)

Parameters:

  • c: Container to get identifier for

Returns:

  • string: Container identifier formatted according to the prioritization order, always returns a non-empty string for valid containers

func StartTargetContainer added in v1.8.6 

func StartTargetContainer(
	ctx context.Context,
	api Operations,
	sourceContainer types.Container,
	networkConfig *dockerNetwork.NetworkingConfig,
	reviveStopped bool,
	clientVersion string,
	minSupportedVersion string,
	disableMemorySwappiness bool,
	cpuCopyMode string,
	isPodman bool,
) (types.ContainerID, error)

StartTargetContainer creates and starts a new container based on the source container’s configuration.

It applies the provided network configuration and respects the reviveStopped option. For legacy Docker API versions (< 1.44) with multiple networks, it creates the container with a single network and attaches others sequentially to avoid issues with multiple network endpoints in ContainerCreate. For modern API versions (>= 1.44) or single networks, it attaches all networks at creation.

Parameters:

  • ctx: Context for cancellation and timeout control.
  • api: Interface for container operations (Operations).
  • sourceContainer: Source container to replicate.
  • networkConfig: Network configuration to apply to the new container.
  • reviveStopped: If true, starts the new container even if the source is stopped.
  • clientVersion: Docker API version used by the client.
  • minSupportedVersion: Minimum Docker API version required for full network features.
  • disableMemorySwappiness: If true, disables memory swappiness for Podman compatibility.
  • cpuCopyMode: CPU copy mode for container recreation, used for compatibility with Podman.
  • isPodman: If true, indicates Podman is being used for CPU compatibility.

Returns:

  • types.ContainerID: ID of the new container.
  • error: Non-nil if creation or start fails, nil on success.

func StopAndRemoveSourceContainer added in v1.14.0 

func StopAndRemoveSourceContainer(
	ctx context.Context,
	api dockerClient.APIClient,
	sourceContainer types.Container,
	timeout time.Duration,
	removeVolumes bool,
) error

StopAndRemoveSourceContainer stops and removes the specified container using the Docker API.

It first stops the container if running, then removes it with optional volume cleanup.

Parameters:

  • ctx: Context for cancellation and timeout control.
  • api: Docker API client for interacting with the Docker daemon.
  • sourceContainer: Container object to stop and remove, containing metadata like name and ID.
  • timeout: Duration to wait for graceful shutdown before forcing termination with SIGKILL.
  • removeVolumes: Boolean indicating whether to remove associated volumes during container removal.

Returns:

  • error: Non-nil if stopping or removing the container fails, nil on successful completion.

func StopSourceContainer added in v1.8.6 

func StopSourceContainer(
	ctx context.Context,
	api dockerClient.APIClient,
	sourceContainer types.Container,
	timeout time.Duration,
) error

StopSourceContainer stops the specified container using the Docker API's StopContainer method.

It checks if the container is running, sends the configured stop signal (defaulting to SIGTERM if unset), and waits for the specified timeout for graceful shutdown, forcing termination with SIGKILL if necessary.

Parameters:

  • ctx: Context for cancellation and timeout control.
  • api: Docker API client for interacting with the Docker daemon.
  • sourceContainer: Container object to stop, containing metadata like name and ID.
  • timeout: Duration to wait for graceful shutdown before forcing termination with SIGKILL.

Returns:

  • error: Non-nil if stopping the container fails, nil on successful completion.

Types

type Client 

type Client interface {
	// ListContainers retrieves a list of containers, optionally filtered.
	//
	// If no filters are provided, all containers are returned.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - filter: Optional filters to apply to container list. Multiple filters are combined with logical AND.
	//
	// Returns:
	//   - []types.Container: List of matching containers.
	//   - error: Non-nil if listing fails, nil on success.
	ListContainers(ctx context.Context, filter ...types.Filter) ([]types.Container, error)

	// GetContainer fetches detailed information about a specific container by its ID.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - containerID: ID of the container to retrieve.
	//
	// Returns:
	//   - types.Container: Container details if found.
	//   - error: Non-nil if retrieval fails, nil on success.
	GetContainer(ctx context.Context, containerID types.ContainerID) (types.Container, error)

	// GetCurrentWatchtowerContainer retrieves minimal container information
	// for the specified container ID, skipping image inspection.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - containerID: ID of the container to retrieve.
	//
	// Returns:
	//   - types.Container: Container with imageInfo set to nil.
	//   - error: Non-nil if inspection fails, nil on success.
	GetCurrentWatchtowerContainer(ctx context.Context, containerID types.ContainerID) (types.Container, error)

	// StopContainer stops a specified container, respecting the given timeout.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - container: Container to stop.
	//   - timeout: Duration to wait before forcing stop.
	//
	// Returns:
	//   - error: Non-nil if stop fails, nil on success.
	StopContainer(ctx context.Context, container types.Container, timeout time.Duration) error

	// StopAndRemoveContainer stops and removes a specified container,
	// respecting the given timeout.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - container: Container to stop and remove.
	//   - timeout: Duration to wait before forcing stop.
	//
	// Returns:
	//   - error: Non-nil if stop/removal fails, nil on success.
	StopAndRemoveContainer(ctx context.Context, container types.Container, timeout time.Duration) error

	// StartContainer creates and starts a new container based on the provided
	// container's configuration.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - container: Source container to replicate.
	//
	// Returns:
	//   - types.ContainerID: ID of the new container.
	//   - error: Non-nil if creation/start fails, nil on success.
	StartContainer(ctx context.Context, container types.Container) (types.ContainerID, error)

	// RenameContainer renames an existing container to the specified new name.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - container: Container to rename.
	//   - newName: New name for the container.
	//
	// Returns:
	//   - error: Non-nil if rename fails, nil on success.
	RenameContainer(ctx context.Context, container types.Container, newName string) error

	// IsContainerStale checks if a container's image is outdated compared to
	// the latest available version.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - container: Container to check.
	//   - params: Update parameters for staleness check.
	//
	// Returns:
	//   - bool: True if image is stale, false otherwise.
	//   - types.ImageID: Latest image ID.
	//   - error: Non-nil if check fails, nil on success.
	IsContainerStale(
		ctx context.Context,
		container types.Container,
		params types.UpdateParams,
	) (bool, types.ImageID, error)

	// ExecuteCommand runs a command inside a container and returns whether
	// to skip updates based on the result.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - container: Container to execute command in.
	//   - command: Command to execute.
	//   - timeout: Minutes to wait before timeout (0 for no timeout).
	//   - uid: UID to run command as (-1 to use container default).
	//   - gid: GID to run command as (-1 to use container default).
	//
	// Returns:
	//   - bool: True if updates should be skipped, false otherwise.
	//   - error: Non-nil if execution fails, nil on success.
	ExecuteCommand(
		ctx context.Context,
		container types.Container,
		command string,
		timeout int,
		uid int,
		gid int,
	) (bool, error)

	// RemoveImageByID deletes an image from the Docker host by its ID.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - imageID: ID of the image to remove.
	//   - imageName: Name of the image to remove (for logging purposes).
	//
	// Returns:
	//   - error: Non-nil if removal fails, nil on success.
	RemoveImageByID(ctx context.Context, imageID types.ImageID, imageName string) error

	// WarnOnHeadPullFailed determines whether to log a warning when a HEAD request fails during image pulls.
	//
	// The decision is based on the configured warning strategy and container context.
	//
	// Parameters:
	//   - container: Container to evaluate.
	//
	// Returns:
	//   - bool: True if warning is needed, false otherwise.
	WarnOnHeadPullFailed(container types.Container) bool

	// GetVersion returns the client's API version.
	//
	// Returns:
	//   - string: Docker API version (e.g., "1.44").
	GetVersion() string

	// GetInfo returns system information from the Docker daemon.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//
	// Returns:
	//   - map[string]any: System information.
	//   - error: Non-nil if retrieval fails, nil on success.
	GetInfo(ctx context.Context) (map[string]any, error)

	// WaitForContainerHealthy waits for a container to become healthy or times out.
	//
	// The timeout parameter controls the maximum wait duration:
	//   - timeout > 0: Wait up to the specified duration for the container to become healthy.
	//   - timeout <= 0: Wait indefinitely until the container becomes healthy, unhealthy,
	//     or the context is cancelled.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - containerID: ID of the container to wait for.
	//   - timeout: Maximum duration to wait for health. Zero or negative values cause
	//     indefinite waiting.
	//
	// Returns:
	//   - error: Non-nil if timeout is reached, container becomes unhealthy, or inspection
	//     fails; nil if healthy or no health check is configured.
	WaitForContainerHealthy(ctx context.Context, containerID types.ContainerID, timeout time.Duration) error

	// UpdateContainer updates the configuration of an existing container.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - container: Container to update.
	//   - config: Update configuration containing the changes to apply.
	//
	// Returns:
	//   - error: Non-nil if update fails, nil on success.
	UpdateContainer(ctx context.Context, container types.Container, config dockerContainer.UpdateConfig) error

	// RemoveContainer removes a container from the Docker host.
	//
	// Parameters:
	//   - ctx: Context for cancellation and timeout control.
	//   - container: Container to remove.
	//
	// Returns:
	//   - error: Non-nil if removal fails, nil on success.
	RemoveContainer(ctx context.Context, container types.Container) error
}

Client defines the interface for interacting with the Docker API within Watchtower.

It provides methods for managing containers, images, and executing commands, abstracting the underlying Docker client operations.

func NewClient 

func NewClient(opts ClientOptions) Client

NewClient initializes a new Client instance for Docker API interactions.

It configures the client using environment variables (e.g., DOCKER_HOST, DOCKER_API_VERSION) and validates the API version, falling back to autonegotiation if necessary.

Parameters:

  • opts: Options to customize container management behavior.

Returns:

  • Client: Initialized client instance (exits on failure).

type ClientOptions 

type ClientOptions struct {
	RemoveVolumes           bool
	IncludeStopped          bool
	ReviveStopped           bool
	IncludeRestarting       bool
	DisableMemorySwappiness bool
	CPUCopyMode             string
	WarnOnHeadFailed        WarningStrategy
	Fs                      afero.Fs
}

ClientOptions configures the behavior of the dockerClient wrapper around the Docker API.

It controls container management and warning behaviors.

type Container 

type Container struct {
	LinkedToRestarting bool          // Indicates if linked to a restarting container
	Stale              bool          // Marks the container as having an outdated image
	OldImageID         types.ImageID // Stores the image ID before update for cleanup tracking
	// contains filtered or unexported fields
}

func NewContainer 

func NewContainer(
	containerInfo *dockerContainer.InspectResponse,
	imageInfo *dockerImage.InspectResponse,
) *Container

NewContainer creates a new Container instance with the specified metadata.

Parameters:

  • containerInfo: Docker container metadata.
  • imageInfo: Docker image metadata.

Returns:

  • *Container: Initialized container instance.

func (*Container) ContainerInfo 

func (c *Container) ContainerInfo() *dockerContainer.InspectResponse

ContainerInfo returns the full Docker container metadata.

Returns:

  • *dockerContainerType.InspectResponse: Container metadata.

func (*Container) Enabled 

func (c *Container) Enabled() (bool, bool)

Enabled checks if Watchtower should manage the container.

Returns:

  • bool: True if enabled, false otherwise.
  • bool: True if label is set, false if absent/invalid.

func (*Container) GetContainerChain added in v1.14.0 

func (c *Container) GetContainerChain() (string, bool)

GetContainerChain returns the container chain label value.

Returns:

  • string: The label value or empty if absent.
  • bool: True if the label is present, false otherwise.

func (*Container) GetCreateConfig 

func (c *Container) GetCreateConfig() *dockerContainer.Config

GetCreateConfig generates a container configuration for recreation.

It isolates runtime overrides from image defaults and sets the image name.

Returns:

  • *dockerContainerType.Config: Configuration for container creation.

func (*Container) GetCreateHostConfig 

func (c *Container) GetCreateHostConfig() *dockerContainer.HostConfig

GetCreateHostConfig generates a host configuration for recreation.

It adjusts link formats for Docker API compatibility.

Returns:

  • *dockerContainerType.HostConfig: Host configuration for container creation.

func (*Container) GetLifecycleGID added in v1.12.0 

func (c *Container) GetLifecycleGID() (int, bool)

GetLifecycleGID returns the GID for lifecycle hooks from labels.

Returns:

  • int: GID value if set and valid.
  • bool: True if label is present and valid, false otherwise.

func (*Container) GetLifecyclePostCheckCommand 

func (c *Container) GetLifecyclePostCheckCommand() string

GetLifecyclePostCheckCommand returns the post-check command from labels.

Returns:

  • string: Post-check command or empty if unset.

func (*Container) GetLifecyclePostUpdateCommand 

func (c *Container) GetLifecyclePostUpdateCommand() string

GetLifecyclePostUpdateCommand returns the post-update command from labels.

Returns:

  • string: Post-update command or empty if unset.

func (*Container) GetLifecyclePreCheckCommand 

func (c *Container) GetLifecyclePreCheckCommand() string

GetLifecyclePreCheckCommand returns the pre-check command from labels.

Returns:

  • string: Pre-check command or empty if unset.

func (*Container) GetLifecyclePreUpdateCommand 

func (c *Container) GetLifecyclePreUpdateCommand() string

GetLifecyclePreUpdateCommand returns the pre-update command from labels.

Returns:

  • string: Pre-update command or empty if unset.

func (*Container) GetLifecycleUID added in v1.12.0 

func (c *Container) GetLifecycleUID() (int, bool)

GetLifecycleUID returns the UID for lifecycle hooks from labels.

Returns:

  • int: UID value if set and valid.
  • bool: True if label is present and valid, false otherwise.

func (*Container) HasImageInfo 

func (c *Container) HasImageInfo() bool

HasImageInfo indicates whether image metadata is available.

Returns:

  • bool: True if imageInfo is non-nil, false otherwise.

func (*Container) ID 

func (c *Container) ID() types.ContainerID

ID returns the unique identifier of the container.

Returns:

  • types.ContainerID: Container ID.

func (*Container) ImageID 

func (c *Container) ImageID() types.ImageID

ImageID returns the ID of the container’s image.

Returns:

  • types.ImageID: Image ID or empty string if imageInfo is nil.

func (*Container) ImageInfo 

func (c *Container) ImageInfo() *dockerImage.InspectResponse

ImageInfo returns the Docker image metadata.

Returns:

  • *dockerImageType.InspectResponse: Image metadata or nil if unavailable.

func (*Container) ImageName 

func (c *Container) ImageName() string

ImageName returns the name of the container’s image.

It uses the Zodiac label if present, otherwise Config.Image, appending ":latest" if untagged.

Returns:

  • string: Image name (e.g., "alpine:latest").

func (*Container) IsLinkedToRestarting 

func (c *Container) IsLinkedToRestarting() bool

IsLinkedToRestarting returns whether the container is linked to a restarting container.

Returns:

  • bool: True if linked, false otherwise.

func (*Container) IsMonitorOnly 

func (c *Container) IsMonitorOnly(params types.UpdateParams) bool

IsMonitorOnly determines if the container is monitor-only.

It uses UpdateParams.MonitorOnly and label precedence.

Parameters:

  • params: Update parameters from types.UpdateParams.

Returns:

  • bool: True if monitor-only, false otherwise.

func (*Container) IsNoPull 

func (c *Container) IsNoPull(params types.UpdateParams) bool

IsNoPull determines if image pulls should be skipped.

It uses UpdateParams.NoPull and label precedence.

Parameters:

  • params: Update parameters from types.UpdateParams.

Returns:

  • bool: True if no-pull, false otherwise.

func (*Container) IsRestarting 

func (c *Container) IsRestarting() bool

IsRestarting checks if the container is currently restarting.

Returns:

  • bool: True if restarting, false otherwise.

func (*Container) IsRunning 

func (c *Container) IsRunning() bool

IsRunning checks if the container is currently running.

Returns:

  • bool: True if running, false otherwise.

func (*Container) IsStale 

func (c *Container) IsStale() bool

IsStale returns whether the container’s image is outdated.

Returns:

  • bool: True if stale, false otherwise.

func (*Container) IsWatchtower 

func (c *Container) IsWatchtower() bool

IsWatchtower identifies if this is the Watchtower container.

Returns:

  • bool: True if watchtower label is "true", false otherwise.
func (c *Container) Links() []string

Links returns a list of container names this container depends on.

It retrieves dependencies from multiple sources in priority order:

  1. com.centurylinklabs.watchtower.depends-on label (Watchtower's native dependency format)
  2. com.docker.compose.depends_on label (Docker Compose dependencies via v5 API)
  3. HostConfig.Links (legacy Docker links)
  4. NetworkMode.ConnectedContainer() (container network mode dependencies)

Self-references are filtered out from all link sources to prevent circular dependencies where a container would depend on itself. This ensures the dependency resolution algorithm can process containers in a valid topological order.

Returns:

  • []string: List of linked container names with self-references removed.

func (*Container) Name 

func (c *Container) Name() string

Name returns the normalized name of the container.

Returns:

  • string: Normalized container name.

func (*Container) PostUpdateTimeout 

func (c *Container) PostUpdateTimeout() int

PostUpdateTimeout returns the post-update command timeout in minutes.

It defaults to 1 minute if unset or invalid; 0 allows indefinite execution.

Returns:

  • int: Timeout in minutes.

func (*Container) PreUpdateTimeout 

func (c *Container) PreUpdateTimeout() int

PreUpdateTimeout returns the pre-update command timeout in minutes.

It defaults to 1 minute if unset or invalid; 0 allows indefinite execution.

Returns:

  • int: Timeout in minutes.

func (*Container) Scope 

func (c *Container) Scope() (string, bool)

Scope retrieves the monitoring scope from labels.

Returns:

  • string: Scope value if set, empty otherwise.
  • bool: True if label is set, false if absent.

func (*Container) SetLinkedToRestarting 

func (c *Container) SetLinkedToRestarting(value bool)

SetLinkedToRestarting sets the linked-to-restarting state.

Parameters:

  • value: New state value.

func (*Container) SetOldImageID added in v1.14.0 

func (c *Container) SetOldImageID(id types.ImageID)

SetOldImageID sets the old image ID for cleanup tracking.

Parameters:

  • id: The old image ID.

func (*Container) SetStale 

func (c *Container) SetStale(value bool)

SetStale marks the container as having an outdated image.

Parameters:

  • value: New stale value.

func (*Container) StopSignal 

func (c *Container) StopSignal() string

StopSignal returns the custom stop signal from labels or HostConfig.

Returns:

  • string: Signal value, defaulting to "SIGTERM" if unset.

func (*Container) StopTimeout added in v1.14.0 

func (c *Container) StopTimeout() *int

StopTimeout returns the container's configured stop timeout in seconds.

Returns:

  • *int: Timeout in seconds if set, nil if unset.

func (*Container) ToRestart 

func (c *Container) ToRestart() bool

ToRestart determines if the container should be restarted.

Returns:

  • bool: True if stale or linked to restarting, false otherwise.

func (*Container) VerifyConfiguration 

func (c *Container) VerifyConfiguration() error

VerifyConfiguration validates the container’s metadata for recreation.

Returns:

  • error: Non-nil if metadata is missing or invalid, nil on success.

type Operations added in v1.11.4 

type Operations interface {
	ContainerCreate(
		ctx context.Context,
		config *dockerContainer.Config,
		hostConfig *dockerContainer.HostConfig,
		networkingConfig *dockerNetwork.NetworkingConfig,
		platform *ocispec.Platform,
		containerName string,
	) (dockerContainer.CreateResponse, error)
	ContainerStart(
		ctx context.Context,
		containerID string,
		options dockerContainer.StartOptions,
	) error
	ContainerRemove(
		ctx context.Context,
		containerID string,
		options dockerContainer.RemoveOptions,
	) error
	NetworkConnect(
		ctx context.Context,
		networkID, containerID string,
		config *dockerNetwork.EndpointSettings,
	) error
	ContainerRename(
		ctx context.Context,
		containerID, newContainerName string,
	) error
}

Operations defines the minimal interface for container operations in Watchtower.

type Runtime added in v1.14.3 

type Runtime int

Runtime represents the type of container runtime detected. 

const (
	// RuntimeUnknown indicates no container runtime has been detected.
	RuntimeUnknown Runtime = iota
	// RuntimeDocker indicates Docker is the container runtime.
	RuntimeDocker
	// RuntimePodman indicates Podman is the container runtime.
	RuntimePodman
)

type WarningStrategy 

type WarningStrategy string

WarningStrategy defines the policy for logging warnings when HEAD requests fail during image pulls.

It allows configuration of verbosity:

  • "always" logs all failures
  • "never" suppresses them
  • "auto" delegates to registry-specific logic (e.g., WarnOnAPIConsumption).
const (
	// WarnAlways indicates warnings should always be logged for HEAD request failures.
	WarnAlways WarningStrategy = "always"
	// WarnNever indicates warnings should never be logged for HEAD request failures.
	WarnNever WarningStrategy = "never"
	// WarnAuto indicates warnings should be logged for HEAD request failures based on registry heuristics.
	WarnAuto WarningStrategy = "auto"
)

Warning strategies for HEAD request failures.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.