Watches

Modified: 08 Sep 2022 04:28 UTC

A watch is a configuration of a service to monitor in Consul. The watch polls the state of the service and emits events when the service becomes healthy, becomes unhealthy, or has a change in the number of instances. Note that a watch does not include a behavior; watches only emit the event so that jobs can consume that event.

Watch configurations include only the following fields:

watches: [
  {
    name: "backend",
    interval: 3,
    tag: "prod",    // optional
    dc: "us-east-1" // optional
  }
]

The interval is the time (in seconds) between polling attempts to Consul. The name is the service to query, the tag is the optional tag to add to the query, and the dc is the optional Consul datacenter to query.

A watch keeps an in-memory list of the healthy IP addresses associated with the service. The list is not persisted to disk and if ContainerPilot is restarted it will need to check back in with the canonical data store, which is Consul. If this list changes between polls, the watch emits one or two events:

The name of the events emitted by watches are namespaced so as not to collide with internal job names. These events are prefixed by watch. Here is an example configuration for a job listening for a watch event:

jobs: [
  {
    name: "update-app",
    exec: "/bin/update-app.sh",
    when: {
      source: "watch.backend",
      each: "changed"
    }
  }
],
watches: [
  {
    name: "backend",
    interval: 3
  }
]

In this example, the watch backend will be checked every 3 seconds. Each time the watch emits the changed event, the update-app job will execute /bin/update-app.sh.