Skip to main content
Version: 9.x

Watchers Overview

Multi-Orchestrator

Watchers are responsible for discovering and scanning containers across your infrastructure, whether on Docker daemons or Kubernetes clusters.

Supported Environments​

WUD provides dedicated watchers tailored for your infrastructure:

EnvironmentDocumentationDescription
🐳 DockerDocker Configuration ↓Local sockets, Remote TCP daemons, and Docker Compose stacks.
🐝 Docker SwarmDocker Swarm Watcher Guide →Swarm manager socket/TCP, services, stack namespaces, digests.
☸️ KubernetesKubernetes Watcher Guide →In-cluster RBAC, Deployments, StatefulSets, DaemonSets, CronJobs.
🎯 NomadNomad Watcher Guide →HashiCorp Nomad jobs (service, batch, system) and task groups.

Docker Configuration​

Default Watcher

If no watcher is explicitly configured, a default watcher named local is automatically created, monitoring /var/run/docker.sock.

Per-Workload Configuration

To customize how WUD monitors specific containers or workloads (opt-in/opt-out, tag filtering, semver transforms, custom display names, or trigger routing), see the comprehensive Workload Customization guide.

Configuration Options​

WUD_WATCHER_{watcher_name}_CAFILE
Optionalpath

Path to CA certificate PEM file (for TLS connection only)

Allowed values:File path
WUD_WATCHER_{watcher_name}_CERTFILE
Optionalpath

Path to client certificate PEM file (for TLS connection only)

Allowed values:File path
WUD_WATCHER_{watcher_name}_CRON
Optionalurldefault: 0 * * * *

CRON schedule for automatic checks

Allowed values:[Valid CRON expression](https://crontab.guru/)
WUD_WATCHER_{watcher_name}_DELAY
Optionalstring

Cool-down period before considering an update available for discovered containers

Allowed values:Duration string (e.g. `30s`, `10m`, `24h`, `3d`, `1w`)
WUD_WATCHER_{watcher_name}_EXCLUDE
Optionalstring

Regex pattern to exclude containers by name or labels (using label: prefix) from being watched. See Container Filtering & Precedence Rules.

Allowed values:Regular expression pattern (e.g. `^ix-.*`, `.*-dev$`, `label:env=dev`)
WUD_WATCHER_{watcher_name}_HOST
Optionalstring

Docker daemon hostname or IP address to monitor

Allowed values:Hostname or IP
WUD_WATCHER_{watcher_name}_INCLUDE
Optionalstring

Regex pattern to include containers by name or labels (using label: prefix) to be watched. See Container Filtering & Precedence Rules.

Allowed values:Regular expression pattern (e.g. `^prod-.*`, `label:tier=frontend`)
WUD_WATCHER_{watcher_name}_JITTER
Optionalintegerdefault: 60000

Random jitter in milliseconds applied to the CRON schedule to distribute load across registries (primarily Docker Hub)

Allowed values:> 0
WUD_WATCHER_{watcher_name}_KEYFILE
Optionalpath

Path to client private key PEM file (for TLS connection only)

Allowed values:File path
WUD_WATCHER_{watcher_name}_PORT
Optionalintegerdefault: 2375

Docker daemon TCP port to connect to

Allowed values:Port number
WUD_WATCHER_{watcher_name}_SOCKET
Optionalpathdefault: /var/run/docker.sock

Docker UNIX socket path to monitor

Allowed values:Valid UNIX socket path
WUD_WATCHER_{watcher_name}_WATCHALL
Optionalbooleandefault: false

Whether WUD should monitor all containers instead of only running ones

WUD_WATCHER_{watcher_name}_WATCHATSTART
Optionalbooleandefault: true

Whether WUD should check for image updates during startup

WUD_WATCHER_{watcher_name}_WATCHBYDEFAULT
Optionalbooleandefault: true

Whether WUD should monitor all discovered containers by default. See Container Filtering & Precedence Rules.

WUD_WATCHER_{watcher_name}_WATCHDIGESTDEFAULT
Optionalbooleandefault: false (Hub), true (others)

Whether WUD should watch digest for tags that are not semantic versions, acting as a fallback when not defined in registry config.

WUD_WATCHER_{watcher_name}_WATCHEVENTS
Optionalbooleandefault: true

Whether WUD should listen for Docker daemon events in real-time

Multiple & Remote Watchers

You can configure multiple watchers to monitor both local and remote Docker hosts simultaneously.

Container Filtering & Precedence Rules​

WUD provides a multi-layered filtering engine to determine whether a discovered container should be monitored for image updates. You can filter containers globally at the watcher level using regular expressions on container names or labels, or override decisions locally using container labels.

Evaluation Priority Flow​

When evaluating each discovered container, WUD processes filtering rules in a strict, descending 4-level hierarchy. The first rule that yields a definitive decision halts further evaluation:

Decision Levels Explained​

  1. Container Label wud.watch (Absolute Priority):
    • Evaluated first. If the container defines the wud.watch label with a non-empty value, this value strictly dictates the outcome:
      • wud.watch=true: The container is monitored, even if it matches an EXCLUDE filter or if WATCHBYDEFAULT=false.
      • wud.watch=false: The container is ignored, even if it matches an INCLUDE filter or if WATCHBYDEFAULT=true.
  2. Watcher Exclude Filter (WUD_WATCHER_{name}_EXCLUDE):
    • If defined, the regex pattern is tested against the container (by name or by labels).
    • If the container matches, it is ignored immediately without evaluating include filters or defaults.
  3. Watcher Include Filter (WUD_WATCHER_{name}_INCLUDE):
    • If defined, the regex pattern acts as an explicit allowlist:
      • Containers that match the pattern are monitored.
      • Containers that do not match are ignored.
    • note

      When an INCLUDE filter is configured, the WATCHBYDEFAULT setting is bypassed for non-matching containers.

  4. Watcher Default Fallback (WUD_WATCHER_{name}_WATCHBYDEFAULT):
    • Reached only if no wud.watch label is present, no EXCLUDE filter matched, and no INCLUDE filter was defined.
    • Defaults to true (all remaining containers are monitored).
    • If set to false, remaining containers are ignored (strict opt-in mode).

Precedence Rules Matrix​

The following table summarizes how combinations of container labels and watcher configuration interact:

PriorityEvaluation LevelRule / SettingMatch ConditionOutcomeDescription
1Container Labelwud.watch=trueLabel set to "true"✅ WatchedExplicit opt-in. Overrides all watcher filters (EXCLUDE, INCLUDE, WATCHBYDEFAULT).
1Container Labelwud.watch=falseLabel set to "false"❌ IgnoredExplicit opt-out. Overrides all watcher filters (EXCLUDE, INCLUDE, WATCHBYDEFAULT).
2Watcher FilterEXCLUDEContainer matches regex❌ IgnoredExcluded by container name or label regex. Takes precedence over INCLUDE.
3Watcher FilterINCLUDEContainer matches regex✅ WatchedIncluded by container name or label regex.
3Watcher FilterINCLUDEContainer does not match❌ IgnoredExcluded because it does not match the active allowlist. WATCHBYDEFAULT is bypassed.
4Watcher DefaultWATCHBYDEFAULT=true (default)No INCLUDE filter active✅ WatchedStandard behavior: monitors all discovered containers.
4Watcher DefaultWATCHBYDEFAULT=falseNo INCLUDE filter active❌ IgnoredStrict opt-in mode: containers ignored unless tagged with wud.watch=true.

Targeting Syntax: Container Names vs. Labels​

Both WUD_WATCHER_{name}_EXCLUDE and WUD_WATCHER_{name}_INCLUDE support standard JavaScript regular expressions (RegExp), with two targeting modes:

1. Container Name Matching (Default)​

Without any prefix, the regex is evaluated directly against the normalized container name (e.g. my-app without leading /):

  • ^prod-.*: Matches any container whose name starts with prod-.
  • .*-(dev|test)$: Matches any container whose name ends with -dev or -test.
  • ^(database|redis|rabbitmq)$: Matches exact container names.

2. Label Matching (label:<regex>)​

When the pattern starts with the label: prefix, WUD inspects the container's Docker metadata labels (container.Labels).

The regular expression following label: is tested against three representations for every label defined on the container:

  1. Label Key Alone: key (e.g., ^com\.docker\.compose)
  2. Key-Value with Equals: key=value (e.g., ^env=production$)
  3. Key-Value with Colon: key:value (e.g., ^tier:frontend$)

If any label on the container matches any of these three representations, the filter condition is satisfied.

Case Sensitivity & Escaping

Regex patterns in JavaScript are case-sensitive by default. Remember to escape special regex characters like dots (\.), dashes, or brackets when targeting reverse-DNS label namespaces (e.g. label:^com\.docker\.compose).

Filtering Cookbook​

Here are production-tested recipes for common container filtering architectures:

Recipe 1: Monitor Docker Compose Stacks Exclusively​

Use Case: You run a host with standalone diagnostic containers, CLI utilities, and core Docker Compose stacks. You want WUD to monitor all Compose-managed containers automatically, without editing individual Compose files.

Why it works: Docker Compose automatically injects labels into every service it deploys (com.docker.compose.project, com.docker.compose.service, com.docker.compose.version). Setting INCLUDE=label:^com\.docker\.compose matches these labels natively.

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
      - WUD_WATCHER_LOCAL_INCLUDE=label:^com\.docker\.compose

Recipe 2: Exclude Development & Test Containers by Name​

Use Case: Ephemeral test containers, staging runners, or CI/CD jobs run on your Docker daemon. You want WUD to watch all production services while skipping any test or dev container.

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
      - WUD_WATCHER_LOCAL_EXCLUDE=^(test|dev|staging)-.*

Recipe 3: Exclude Containers by Custom Label​

Use Case: You want to flag specific containers to be ignored by assigning a custom tag such as wud.ignore=true or env=development, without having to rename containers.

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
      - WUD_WATCHER_LOCAL_EXCLUDE=label:^wud\.ignore=true$

Any container bearing that label will be skipped:

Example skipped workload
services:
  backup-job:
    image: restic/restic:latest
    labels:
      - wud.ignore=true

Recipe 4: Allowlist Production Containers by Name​

Use Case: In high-density environments, you only want to monitor containers prefixed with prod- or core-. All other existing and future containers are ignored by default.

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
      - WUD_WATCHER_LOCAL_INCLUDE=^(prod|core)-.*

Recipe 5: Strict Opt-In Mode per Container​

Use Case: In shared or multi-tenant environments, you do not want WUD to automatically discover and monitor every workload. Instead, container owners must explicitly opt in by adding wud.watch=true.

First, configure WUD in opt-in mode by setting WATCHBYDEFAULT=false:

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
      - WUD_WATCHER_LOCAL_WATCHBYDEFAULT=false

Next, add the wud.watch=true label to the specific services you want WUD to monitor:

compose.yaml
services:
  # Monitored because wud.watch=true
  web:
    image: nginx:1.27-alpine
    labels:
      - wud.watch=true

  # Ignored because WATCHBYDEFAULT=false
  redis:
    image: redis:7.2-alpine

Examples​

1. Watch the local Docker host daily at 1:00 AM​

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_CRON=0 1 * * *

2. Watch all containers (including stopped / paused)​

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_WATCHALL=true

3. Watch a remote Docker host via TCP (Port 2375)​

services:
  whatsupdocker:
    image: getwud/wud
    environment:
      - WUD_WATCHER_MYREMOTEHOST_HOST=myremotehost
      - WUD_WATCHER_MYREMOTEHOST_PORT=2375

4. Watch a remote Docker host with TLS (Port 2376)​

services:
  whatsupdocker:
    image: getwud/wud
    environment:
      - WUD_WATCHER_MYREMOTEHOST_HOST=myremotehost
      - WUD_WATCHER_MYREMOTEHOST_PORT=2376
      - WUD_WATCHER_MYREMOTEHOST_CAFILE=/certs/ca.pem
      - WUD_WATCHER_MYREMOTEHOST_CERTFILE=/certs/cert.pem
      - WUD_WATCHER_MYREMOTEHOST_KEYFILE=/certs/key.pem
    volumes:
      - /my-host/my-certs/ca.pem:/certs/ca.pem:ro
      - /my-host/my-certs/cert.pem:/certs/cert.pem:ro
      - /my-host/my-certs/key.pem:/certs/key.pem:ro

5. Watch multiple Docker hosts simultaneously​

services:
  whatsupdocker:
    image: getwud/wud
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
      - WUD_WATCHER_PROD_HOST=prod-docker-host
      - WUD_WATCHER_STAGING_HOST=staging-docker-host