Watches are a way of specifying a view of data (e.g. list of nodes, KV pairs, health
checks) which is monitored for updates. When an update is detected, an external handler
is invoked. A handler can be any executable or HTTP endpoint. As an example, you could watch the status
of health checks and notify an external system when a check is critical.
Watches are implemented using blocking queries in the HTTP API.
Agents automatically make the proper API calls to watch for changes
and inform a handler when the data view has updated.
Watches can be configured as part of the agent's configuration,
causing them to run once the agent is initialized. Reloading the agent configuration
allows for adding or removing watches dynamically.
Alternatively, the watch command enables a watch to be
started outside of the agent. This can be used by an operator to inspect data in Consul
or to easily pipe data into processes without being tied to the agent lifecycle.
In either case, the type of the watch must be specified. Each type of watch
supports different parameters, some required and some optional. These options are specified
in a JSON body when using agent configuration or as CLI flags for the watch command.
The watch configuration specifies the view of data to be monitored.
Once that view is updated, the specified handler is invoked. Handlers can be either an
executable or an HTTP endpoint. A handler receives JSON formatted data
with invocation info, following a format that depends on the type of the watch.
Each watch type documents the format type. Because they map directly to an HTTP
API, handlers should expect the input to match the format of the API. A Consul
index is also given, corresponding to the responses from the
HTTP API.
An executable handler reads the JSON invocation info from stdin. Additionally,
the CONSUL_INDEX environment variable will be set to the Consul index.
Anything written to stdout is logged.
Here is an example configuration, where handler_type is optionally set to
script:
Consul watch with script handler defined in agent configuration
Consul watch with script handler defined in agent configuration
Prior to Consul 1.0, watches used a single handler field to define the command to run, and
would always run in a shell. In Consul 1.0, the args array was added so that handlers can be
run without a shell. The handler field is deprecated, and you should include the shell in
the args to run under a shell, eg. "args": ["sh", "-c", "..."].
An HTTP handler sends an HTTP request when a watch is invoked. The JSON invocation info is sent
as a payload along the request. The response also contains the Consul index as a header named
X-Consul-Index.
The HTTP handler can be configured by setting handler_type to http. Additional handler options
are set using http_handler_config. The only required parameter is the path field which specifies
the URL to the HTTP endpoint. Consul uses POST as the default HTTP method, but this is also configurable.
Other optional fields are header, timeout and tls_skip_verify. The watch invocation data is
always sent as a JSON payload.
Here is an example configuration:
Consul watch with HTTP handler defined in agent configuration
Consul watch with HTTP handler defined in agent configuration
The keyprefix watch type is used to watch a prefix of keys in the KV store.
It requires that the prefix parameter be specified. This watch
returns all keys matching the prefix whenever any key matching the prefix
changes.
The "service" watch type is used to monitor the providers
of a single service. It requires the service parameter
and optionally takes the parameters tag and
passingonly. The tag parameter will filter by one or more tags.
It may be either a single string value or a slice of strings.
The passingonly parameter is a boolean that will filter to only the
instances passing all health checks.
This maps to the /v1/health/service API internally.
Here is an example configuration with a single tag:
[{"Node":{"ID":"f013522f-aaa2-8fc6-c8ac-c84cb8a56405","Node":"hashicorp-consul-server-1","Address":"192.0.2.50","Datacenter":"dc1","TaggedAddresses":null,"Meta":null,"CreateIndex":23785783,"ModifyIndex":23785783},"Service":{"ID":"redis","Service":"redis","Tags":[],"Meta":null,"Port":6379,"Address":"","Weights":{"Passing":1,"Warning":1},"EnableTagOverride":false,"CreateIndex":23785794,"ModifyIndex":23785794,"Proxy":{"MeshGateway":{},"Expose":{}},"Connect":{}},"Checks":[{"Node":"hashicorp-consul-server-1","CheckID":"serfHealth","Name":"Serf Health Status","Status":"passing","Notes":"","Output":"Agent alive and reachable","ServiceID":"","ServiceName":"","ServiceTags":[],"Type":"","Definition":{"Interval":"0s","Timeout":"0s","DeregisterCriticalServiceAfter":"0s","HTTP":"","Header":null,"Method":"","Body":"","TLSServerName":"","TLSSkipVerify":false,"TCP":"","GRPC":"","GRPCUseTLS":false},"CreateIndex":23785783,"ModifyIndex":23791503}]}]
[{"Node":{"ID":"f013522f-aaa2-8fc6-c8ac-c84cb8a56405","Node":"hashicorp-consul-server-1","Address":"192.0.2.50","Datacenter":"dc1","TaggedAddresses":null,"Meta":null,"CreateIndex":23785783,"ModifyIndex":23785783},"Service":{"ID":"redis","Service":"redis","Tags":[],"Meta":null,"Port":6379,"Address":"","Weights":{"Passing":1,"Warning":1},"EnableTagOverride":false,"CreateIndex":23785794,"ModifyIndex":23785794,"Proxy":{"MeshGateway":{},"Expose":{}},"Connect":{}},"Checks":[{"Node":"hashicorp-consul-server-1","CheckID":"serfHealth","Name":"Serf Health Status","Status":"passing","Notes":"","Output":"Agent alive and reachable","ServiceID":"","ServiceName":"","ServiceTags":[],"Type":"","Definition":{"Interval":"0s","Timeout":"0s","DeregisterCriticalServiceAfter":"0s","HTTP":"","Header":null,"Method":"","Body":"","TLSServerName":"","TLSSkipVerify":false,"TCP":"","GRPC":"","GRPCUseTLS":false},"CreateIndex":23785783,"ModifyIndex":23791503}]}]
The "checks" watch type is used to monitor the checks of a given
service or those in a specific state. It optionally takes the service
parameter to filter to a specific service or the state parameter to
filter to a specific state. By default, it will watch all checks.
This maps to the /v1/health/state/ API if monitoring by state
or /v1/health/checks/ if monitoring by service.
Here is an example configuration for monitoring by state:
Example checks watch type for all services in the passing state
Example checks watch type for all services in the passing state
The "event" watch type is used to monitor for custom user
events. These are fired using the consul event command.
It takes only a single optional name parameter which restricts
the watch to only events with the given name.