Skip to main content
Version: Next 🚧

Docker Swarm Watcher

Docker Swarm

The Docker Swarm watcher discovers and monitors services and stacks running across your Docker Swarm cluster, reporting when newer container images are available.

Service-Level Monitoring

In Docker Swarm, workloads are monitored at the Service level rather than individual task replicas. This ensures:

  • A single consolidated entry per service regardless of the replica count (replicas: 1 or replicas: 10).
  • Seamless support for both replicated and global service modes.
  • Automatic stack namespace grouping via com.docker.stack.namespace when deployed using docker stack deploy.

Prerequisites​

WUD must be connected to a Docker Swarm Manager node:

  • Local Manager: Mount /var/run/docker.sock from a Swarm manager node.
  • Remote Manager: Connect via TCP (host:port) with optional TLS certificates (cafile, certfile, keyfile).
  • Cluster Visibility: Monitoring a Swarm manager provides complete visibility across all worker nodes in the cluster.
Worker Nodes

If WUD connects to a worker node instead of a manager node, Docker will reject the service listing API (This node is not a swarm manager). WUD will log a warning and skip the cycle. Ensure WUD is scheduled on or points to a manager node.

Configuration Options​

WUD_WATCHER_SWARM_{name}_CAFILE
Optionalpath

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

Allowed values:File path
WUD_WATCHER_SWARM_{name}_CERTFILE
Optionalpath

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

Allowed values:File path
WUD_WATCHER_SWARM_{name}_CRON
Optionalstringdefault: 0 * * * *

CRON schedule for automatic checks

Allowed values:[Valid CRON expression](https://crontab.guru/)
WUD_WATCHER_SWARM_{name}_HOST
Optionalstring

Remote Swarm manager hostname or IP address

Allowed values:Hostname or IP
WUD_WATCHER_SWARM_{name}_JITTER
Optionalintegerdefault: 60000

Random jitter in milliseconds applied to the CRON schedule

Allowed values:> 0
WUD_WATCHER_SWARM_{name}_KEYFILE
Optionalpath

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

Allowed values:File path
WUD_WATCHER_SWARM_{name}_PORT
Optionalintegerdefault: 2375

Docker daemon TCP port to connect to on the manager node

Allowed values:Port number
WUD_WATCHER_SWARM_{name}_SOCKET
Optionalpathdefault: /var/run/docker.sock

Docker daemon UNIX socket on a Swarm manager node

Allowed values:Valid UNIX socket path
WUD_WATCHER_SWARM_{name}_STACKS
Optionallistdefault: All stacks

Filter monitoring to specific Swarm stack namespaces

Allowed values:Comma-separated list of stack names (e.g. `core,monitoring,prod`)
WUD_WATCHER_SWARM_{name}_WATCHATSTART
Optionalbooleandefault: true

Whether to check for service image updates during WUD startup

Allowed values:true | false
WUD_WATCHER_SWARM_{name}_WATCHBYDEFAULT
Optionalbooleandefault: true

Whether to watch Swarm services by default when getwud.app/watch or wud.watch is not defined

Allowed values:true | false
WUD_WATCHER_SWARM_{name}_WATCHDIGESTDEFAULT
Optionalbooleandefault: false (Hub), true (others)

Whether to watch image digest by default for non-semver images

Allowed values:true | false

Service & Stack Customization​

You can customize monitoring behavior per service using labels. Labels can be placed in deploy.labels in your stack file or passed via docker service create --label.

Both canonical prefixes (getwud.app/*) and short aliases (wud.*, wud/*) are supported:

version: '3.8'

services:
  web:
    image: nginx:1.27.0
    deploy:
      replicas: 3
      labels:
        - "getwud.app/display.name=Production Web Gateway"
        - "getwud.app/tag.include=^1\\.27"
        - "getwud.app/watch.digest=true"
        - "getwud.app/trigger.include=slack,webhook"

For the complete reference of supported properties, see the Workload Customization guide.

Examples​

1. Deploy WUD as a Swarm Service on a Manager Node​

Deploy WUD directly into your Swarm cluster using a stack compose file:

version: '3.8'

services:
  wud:
    image: getwud/wud:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      - WUD_WATCHER_SWARM_LOCAL_SOCKET=/var/run/docker.sock
      - WUD_WATCHER_SWARM_LOCAL_CRON=0 2 * * *
    deploy:
      mode: replicated
      replicas: 1
      placement:
        constraints:
          - node.role == manager

2. Monitor a Remote Swarm Manager via TLS​

services:
  wud:
    image: getwud/wud:latest
    environment:
      - WUD_WATCHER_SWARM_CLUSTER1_HOST=swarm-manager.internal
      - WUD_WATCHER_SWARM_CLUSTER1_PORT=2376
      - WUD_WATCHER_SWARM_CLUSTER1_CAFILE=/certs/ca.pem
      - WUD_WATCHER_SWARM_CLUSTER1_CERTFILE=/certs/cert.pem
      - WUD_WATCHER_SWARM_CLUSTER1_KEYFILE=/certs/key.pem
    volumes:
      - /path/to/certs:/certs:ro

3. Filter Specific Stacks​

To restrict WUD to only monitor services belonging to the production and ingress stacks:

environment:
  - WUD_WATCHER_SWARM_PROD_STACKS=production,ingress