Skip to main content
Version: 9.x

Kubernetes Watcher

Kubernetes

The Kubernetes watcher discovers and monitors workloads running in Kubernetes clusters, reporting when newer image versions are available.

Supported workload types
  • Deployment
  • StatefulSet
  • DaemonSet
  • CronJob

Prerequisites​

WUD must be able to reach the Kubernetes API server. Two modes are supported:

  • In-cluster (default): WUD runs inside the cluster with an appropriate ServiceAccount.
  • Out-of-cluster: provide a path to a kubeconfig file via WUD_WATCHER_KUBERNETES_{name}_KUBECONFIG.

RBAC (In-Cluster Mode)​

When running WUD inside a Kubernetes cluster, configure the following RBAC resources so that WUD can read workloads, nodes, and pods:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: wud
  namespace: wud
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: wud-reader
rules:
  - apiGroups: ["apps"]
    resources: ["deployments", "statefulsets", "daemonsets"]
    verbs: ["get", "list"]
  - apiGroups: ["batch"]
    resources: ["cronjobs"]
    verbs: ["get", "list"]
  - apiGroups: [""]
    resources: ["nodes", "pods"]
    verbs: ["get", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: wud-reader-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: wud-reader
subjects:
  - kind: ServiceAccount
    name: wud
    namespace: wud

Configuration Options​

WUD_WATCHER_KUBERNETES_{name}_CRON
Optionalstringdefault: 0 * * * *

CRON schedule for automatic checks

Allowed values:[Valid CRON expression](https://crontab.guru/)
WUD_WATCHER_KUBERNETES_{name}_JITTER
Optionalintegerdefault: 60000

Random jitter in milliseconds applied to the CRON schedule

Allowed values:> 0
WUD_WATCHER_KUBERNETES_{name}_KUBECONFIG
Optionalpath

Path to a kubeconfig file. When omitted, in-cluster ServiceAccount is used.

Allowed values:File path
WUD_WATCHER_KUBERNETES_{name}_NAMESPACE
Optionalstring

Kubernetes namespace to watch. Empty means all namespaces.

WUD_WATCHER_KUBERNETES_{name}_WATCHATSTART
Optionalbooleandefault: true

Trigger a watch cycle immediately at startup

WUD_WATCHER_KUBERNETES_{name}_WATCHBYDEFAULT
Optionalbooleandefault: true

If true, all workloads are watched unless explicitly opted out

WUD_WATCHER_KUBERNETES_{name}_WATCHDIGESTDEFAULT
Optionalboolean

Default behavior for digest watching on non-semver images

WUD_WATCHER_KUBERNETES_{name}_WORKLOADTYPES
Optionalstringdefault: Deployment,StatefulSet,DaemonSet,CronJob

Workload kinds to discover and monitor

Allowed values:Comma-separated list or JSON array: Deployment, StatefulSet, DaemonSet, CronJob

Workload Customization & Annotations​

WUD supports annotations on Kubernetes workloads to fine-tune update discovery, filtering, and notifications.

Supported Prefixes​

  • Canonical (Recommended): getwud.app/<property>
  • Short alias: wud/<property>
  • Legacy: wud.getwud.io/<property>
Fine-tune your workloads

Looking for detailed examples, regex filtering, tag transforms, or digest watching? Check out the comprehensive Container & Workload Customization guide.

Multi-Container Pods​

Suffix any annotation with .<container_name> to target a specific container within a multi-container pod:

annotations:
  getwud.app/display.name.nginx: "My Nginx"
  getwud.app/display.name.sidecar: "My Sidecar"
  getwud.app/watch.digest.nginx: "true"

Examples​

WUD_WATCHER_KUBERNETES_MYCLUSTER_NAMESPACE=production
WUD_WATCHER_KUBERNETES_MYCLUSTER_WATCHBYDEFAULT=false

Container ID format​

WUD builds a unique ID for each watched container:

{namespace}_{kind}_{workloadName}_{containerName}

Example: production_deployment_my-nginx_nginx