Nomad Watcher

HashiCorp Nomad

The Nomad watcher discovers and monitors jobs and task groups running in HashiCorp Nomad clusters, reporting when newer container images are available.

Supported Job Types & Drivers

• Job Types: service, batch, system
• Task Drivers: docker, podman (or any task specifying config.image)

---

Prerequisites

WUD must be able to reach the Nomad HTTP API (default port 4646):

• Local / In-Cluster: Connect directly to http://localhost:4646 or http://nomad:4646.
• Remote Cluster: Provide the Nomad API URL via WUD_WATCHER_NOMAD_{name}_URL.
• ACL Enabled: Provide a Nomad Secret Token via WUD_WATCHER_NOMAD_{name}_TOKEN.
• TLS / mTLS: Configure CAFILE, CERTFILE, and KEYFILE if your Nomad cluster enforces TLS.

---

Configuration Options

WUD_WATCHER_NOMAD_{name}_CAFILE

Optionalpathdefault: Empty

Path to custom CA certificate for TLS validation

Allowed values:Path to valid CA certificate file

WUD_WATCHER_NOMAD_{name}_CERTFILE

Optionalpathdefault: Empty

Path to client certificate file for mTLS authentication

Allowed values:Path to client certificate file

WUD_WATCHER_NOMAD_{name}_CRON

Optionalstringdefault: 0 * * * *

CRON schedule for automatic checks

Allowed values:[Valid CRON expression](https://crontab.guru/)

WUD_WATCHER_NOMAD_{name}_DRIVERS

Optionalstringdefault: docker,podman

List of task drivers to inspect for container images

Allowed values:Comma-separated list of driver names

WUD_WATCHER_NOMAD_{name}_JITTER

Optionalintegerdefault: 60000

Random jitter in milliseconds applied to the CRON schedule

Allowed values:> 0

WUD_WATCHER_NOMAD_{name}_KEYFILE

Optionalpathdefault: Empty

Path to client private key file for mTLS authentication

Allowed values:Path to client private key file

WUD_WATCHER_NOMAD_{name}_NAMESPACE

Optionalstringdefault: *

Nomad namespace to watch

Allowed values:'*' (all namespaces) or specific namespace name

WUD_WATCHER_NOMAD_{name}_TOKEN

Optionalstringdefault: Empty

Secret token used for authenticating against Nomad ACL

Allowed values:Nomad ACL Secret Token

WUD_WATCHER_NOMAD_{name}_URL

Optionalstringdefault: http://localhost:4646

Nomad HTTP API endpoint

Allowed values:Valid HTTP or HTTPS URL

WUD_WATCHER_NOMAD_{name}_WATCHATSTART

Optionalbooleandefault: true

Trigger an initial watch cycle when WUD starts if the container store is empty

Allowed values:true | false

WUD_WATCHER_NOMAD_{name}_WATCHBYDEFAULT

Optionalbooleandefault: true

Whether to watch Nomad tasks by default when wud.watch is not defined

Allowed values:true | false

WUD_WATCHER_NOMAD_{name}_WATCHDIGESTDEFAULT

Optionalbooleandefault: false

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

Allowed values:true | false

---

Nomad Job Metadata (meta block)

You can customize how WUD treats each Nomad job, task group, or individual task by setting key-value pairs in the meta { ... } block in your job file.

Supported Prefixes

• Canonical (Recommended): getwud.app/<property>
• Short alias (Nomad-idiomatic): wud.<property> or 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.

Cascading Priority

Metadata cascades with the following precedence:

Task.meta → TaskGroup.meta → Job.meta

A setting placed on a job applies to all its tasks unless overridden by a group or task. In job/group metadata, suffixing with .<task_name> (e.g. getwud.app/display.name.redis) targets a specific task.

---

Examples

Nomad Job Specification (example.nomad.hcl)

job "webapp" {
  datacenters = ["dc1"]
  type        = "service"

  # Job-level metadata applied to all tasks
  meta = {
    "wud.stack" = "production"
  }

  group "web" {
    count = 2

    task "nginx" {
      driver = "docker"

      config {
        image = "nginx:1.27.0"
      }

      meta = {
        "wud.watch"        = "true"
        "wud.tag.include"  = "^1\\.27"
        "wud.display.name" = "Frontend Web"
      }
    }
  }

  group "cache" {
    count = 1

    task "redis" {
      driver = "docker"

      config {
        image = "redis:7.2.4"
      }

      meta = {
        "wud.display.name" = "Cache Redis"
      }
    }
  }
}

Docker Compose

Deploy WUD alongside or connected to a Nomad cluster:

services:
  wud:
    image: getwud/wud:latest
    container_name: wud
    ports:
      - "3000:3000"
    environment:
      # Nomad watcher configuration
      - WUD_WATCHER_NOMAD_MYCLUSTER_URL=http://nomad-server:4646
      - WUD_WATCHER_NOMAD_MYCLUSTER_NAMESPACE=*
      - WUD_WATCHER_NOMAD_MYCLUSTER_CRON=0 * * * *
      - WUD_WATCHER_NOMAD_MYCLUSTER_WATCHBYDEFAULT=true