filters

Documentation

Overview

Package filters provides filtering logic for Watchtower containers. It defines functions to select containers by container names, image names, labels, and scopes.

Key components:

• Filter Functions: Select containers (e.g., FilterByNames, FilterByScope).
• BuildFilter: Combines filters into a single function.

Usage example:

filter, desc, err := filters.BuildFilter(log, names, disableNames, monitoredImageNamePatterns, skippedImageNamePatterns, enabledLabels, disabledLabels, true, "scope")
if err != nil {
	return err
}
containers, _ := client.ListContainers(filter)
log.Info().Msg(desc)

The package uses zerolog for logging filter operations and integrates with container types.

Index

• func BuildFilter(log *zerolog.Logger, normalizedNames []string, normalizedDisableNames []string, ...) (types.Filter, string, error)
• func ExcludeOldWatchtowerFilter(c types.FilterableContainer) bool
• func ExcludeOldWatchtowerFilterChain(baseFilter types.Filter) types.Filter
• func FilterByDisableNames(log *zerolog.Logger, normalizedDisableNames []string, baseFilter types.Filter) types.Filter
• func FilterByDisabledLabels(log *zerolog.Logger, labels map[string]string, baseFilter types.Filter) types.Filter
• func FilterByEnableLabel(enable bool, baseFilter types.Filter) types.Filter
• func FilterByEnabledLabels(log *zerolog.Logger, labels map[string]string, baseFilter types.Filter) types.Filter
• func FilterByImage(log *zerolog.Logger, images []string, baseFilter types.Filter) types.Filter
• func FilterByMonitoredImageNamePatterns(log *zerolog.Logger, namePatterns []string, baseFilter types.Filter) types.Filter
• func FilterByNames(log *zerolog.Logger, normalizedNames []string, baseFilter types.Filter) types.Filter
• func FilterByScope(log *zerolog.Logger, scope string, baseFilter types.Filter) types.Filter
• func FilterBySkippedImageNamePatterns(log *zerolog.Logger, namePatterns []string, baseFilter types.Filter) types.Filter
• func IsOldWatchtower(c types.FilterableContainer) bool
• func NoFilter(c types.FilterableContainer) bool
• func UnscopedWatchtowerContainersFilter(c types.FilterableContainer) bool
• func WatchtowerContainersFilter(c types.FilterableContainer) bool

Functions

func BuildFilter

func BuildFilter(log *zerolog.Logger,
	normalizedNames []string,
	normalizedDisableNames []string,
	monitoredImageNamePatterns []string,
	skippedImageNamePatterns []string,
	enabledLabels []string,
	disabledLabels []string,
	enableLabel bool,
	scope string,
) (types.Filter, string, error)

BuildFilter constructs a composite filter for containers.

Parameters:

• normalizedNames: Normalized container names or regex patterns. When set, only containers matching these patterns are monitored.
• normalizedDisableNames: Container names or regex patterns to skip. Matching containers are excluded from monitoring.
• monitoredImageNamePatterns: Image name regex patterns. When set, only containers whose image matches one of these patterns are monitored.
• skippedImageNamePatterns: Image name regex patterns. Containers whose image matches one of these patterns are excluded from monitoring.
• enabledLabels: Label key-value pairs. When set, only containers matching at least one pair are monitored.
• disabledLabels: Label key-value pairs. Containers matching any pair are excluded.
• enableLabel: Require enable label if true.
• scope: Scope to match.

Returns:

• types.Filter: Combined filter function.
• string: Description of the filter.
• error: Non-nil if any enabled or disabled label pair is malformed.

func ExcludeOldWatchtowerFilter

func ExcludeOldWatchtowerFilter(c types.FilterableContainer) bool

ExcludeOldWatchtowerFilter rejects containers that are old Watchtower containers renamed during self-update (prefixed with "watchtower-old-").

These containers are predecessors that should only be removed, never updated or included in update cycles. This filter ensures they are excluded from regular container processing regardless of scope.

Returns:

• bool: True if the container should be included, false if it is an old Watchtower container that should be excluded.

func ExcludeOldWatchtowerFilterChain

func ExcludeOldWatchtowerFilterChain(baseFilter types.Filter) types.Filter

ExcludeOldWatchtowerFilterChain wraps a base filter with old Watchtower exclusion. It chains the exclusion check before the base filter, ensuring old Watchtower containers are rejected early in the pipeline.

Parameters:

• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function that excludes old Watchtower containers and applies the base filter.

func FilterByDisableNames

func FilterByDisableNames(log *zerolog.Logger, normalizedDisableNames []string, baseFilter types.Filter) types.Filter

FilterByDisableNames excludes containers matching specified names.

Name patterns are compiled once when the filter is built.

Parameters:

• log: Logger for debug output.
• normalizedDisableNames: Names or regex patterns to exclude.
• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function excluding names and applying base filter.

func FilterByDisabledLabels

func FilterByDisabledLabels(log *zerolog.Logger, labels map[string]string, baseFilter types.Filter) types.Filter

FilterByDisabledLabels excludes containers that have any of the specified label key-value pairs.

An empty label list disables the filter entirely.

A label entry with an empty value (key="") performs a presence check: the label must exist on the container with any value. A non-empty value requires an exact match.

Parameters:

• labels: Map of label key-value pairs to exclude.
• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function excluding matching labels and applying base filter.

func FilterByEnableLabel

func FilterByEnableLabel(enable bool, baseFilter types.Filter) types.Filter

FilterByEnableLabel applies the boolean --label-enable filter.

When enable is true, only containers whose enable label is present with a value that parses as true are included. When enable is false, containers whose enable label is present with a value that parses as false are excluded. Absent labels and invalid values are both treated as unset, matching Enabled() returning ok=false.

Parameters:

• enable: require the enable label when true, exclude false values when false.
• baseFilter: base filter to chain.

Returns:

• types.Filter: filter function applying enable-label semantics and baseFilter.

func FilterByEnabledLabels

func FilterByEnabledLabels(log *zerolog.Logger, labels map[string]string, baseFilter types.Filter) types.Filter

FilterByEnabledLabels restricts processing to containers that have at least one of the specified label key-value pairs.

An empty label list disables the filter entirely.

A label entry with an empty value (key="") performs a presence check: the label must exist on the container with any value. A non-empty value requires an exact match.

Parameters:

• labels: Map of label key-value pairs to require.
• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function matching labels and applying base filter.

func FilterByImage

func FilterByImage(log *zerolog.Logger, images []string, baseFilter types.Filter) types.Filter

FilterByImage selects containers with specific images, optionally including tags.

Parameters:

• images: List of image names (with optional tags) to match.
• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function matching images and applying base filter.

func FilterByMonitoredImageNamePatterns

func FilterByMonitoredImageNamePatterns(log *zerolog.Logger, namePatterns []string, baseFilter types.Filter) types.Filter

FilterByMonitoredImageNamePatterns restricts monitoring to containers whose image name matches specified patterns. When set, only matching containers are monitored.

Image patterns are compiled once when the filter is built.

Parameters:

• log: Logger for debug output.
• namePatterns: Image name regex patterns.
• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function restricting to matching image names, then applying base filter.

func FilterByNames

func FilterByNames(log *zerolog.Logger, normalizedNames []string, baseFilter types.Filter) types.Filter

FilterByNames selects containers matching specified names.

Name patterns are compiled once when the filter is built.

Parameters:

• log: Logger for debug output.
• normalizedNames: List of normalized names or regex patterns to match.
• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function combining name check with base filter.

func FilterByScope

func FilterByScope(log *zerolog.Logger, scope string, baseFilter types.Filter) types.Filter

FilterByScope selects containers in a specific scope.

Parameters:

• scope: Scope to match.
• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function matching scope and applying base filter.

func FilterBySkippedImageNamePatterns

func FilterBySkippedImageNamePatterns(log *zerolog.Logger, namePatterns []string, baseFilter types.Filter) types.Filter

FilterBySkippedImageNamePatterns prevents monitoring of containers whose image name matches specified patterns. Matching containers are excluded from monitoring.

Image patterns are compiled once when the filter is built.

Parameters:

• log: Logger for debug output.
• namePatterns: Image name regex patterns.
• baseFilter: Base filter to chain.

Returns:

• types.Filter: Filter function excluding matching image names, then applying base filter.

func IsOldWatchtower

func IsOldWatchtower(c types.FilterableContainer) bool

IsOldWatchtower reports whether the container is an old Watchtower container renamed during self-update (prefixed with "watchtower-old-").

This is the positive counterpart to ExcludeOldWatchtowerFilter and is intended for guard clauses where a positive check reads more naturally.

Returns:

• bool: True if the container is an old Watchtower container.

func NoFilter

func NoFilter(c types.FilterableContainer) bool

NoFilter allows all containers through.

Returns:

• bool: Always true.

func UnscopedWatchtowerContainersFilter

func UnscopedWatchtowerContainersFilter(c types.FilterableContainer) bool

UnscopedWatchtowerContainersFilter selects only unscoped Watchtower containers.

Returns:

• bool: True if container is Watchtower and has no scope or scope "none", false otherwise.

func WatchtowerContainersFilter

func WatchtowerContainersFilter(c types.FilterableContainer) bool

WatchtowerContainersFilter selects only Watchtower containers.

Returns:

• bool: True if container is Watchtower, false otherwise.