website: Document watches
This commit is contained in:
Armon Dadgar
parent
4e3ca1a785
commit
60a50301db
|
|
@ -145,7 +145,13 @@ definitions support being updated during a reload.
|
|||
"data_dir": "/opt/consul",
|
||||
"log_level": "INFO",
|
||||
"node_name": "foobar",
|
||||
"server": true
|
||||
"server": true,
|
||||
"watches": [
|
||||
{
|
||||
"type": "checks",
|
||||
"handler": "/usr/bin/health-check-handler.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
</pre>
|
||||
|
||||
|
|
@ -316,6 +322,11 @@ definitions support being updated during a reload.
|
|||
However, because the caches are not actively invalidated, ACL policy may be stale
|
||||
up to the TTL value.
|
||||
|
||||
* `watches` - Watches is a list of watch specifications.
|
||||
These allow an external process to be automatically invoked when a particular
|
||||
data view is updated. See the [watch documentation](/docs/agent/watches.html) for
|
||||
more documentation. Watches can be modified when the configuration is reloaded.
|
||||
|
||||
## Ports Used
|
||||
|
||||
Consul requires up to 5 different ports to work properly, some requiring
|
||||
|
|
|
|||
286
website/source/docs/agent/watches.html.markdown
Normal file
286
website/source/docs/agent/watches.html.markdown
Normal file
|
|
@ -0,0 +1,286 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Watches"
|
||||
sidebar_current: "docs-agent-watches"
|
||||
---
|
||||
|
||||
# Watches
|
||||
|
||||
Watches are a way of specifying a view of data (list of nodes, KV pairs,
|
||||
health checks, etc) which is monitored for any updates. When an update
|
||||
is detected, an external handler handler is invoked. A handler can be any
|
||||
executable. 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](/docs/agent/http.html).
|
||||
Agent's automatically make the proper API calls to watch for changes,
|
||||
and inform a handler when the data view has updated.
|
||||
|
||||
Watches can can be configured as part of the [agent's configuration](/docs/agent/options.html),
|
||||
causing them to run once the agent is initialized. Reloading the agent configuration
|
||||
allows for adding or removing watches dynamically.
|
||||
|
||||
Alternatively, the [watch command](/docs/commands/watch.html) 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, both required and optional. These options are specified
|
||||
in a JSON body when using agent configuration, or as CLI flags for the watch command.
|
||||
|
||||
## Handlers
|
||||
|
||||
The watch specifiation specifies the view of data to be monitored.
|
||||
Once that view is updated the specified handler is invoked. The handler
|
||||
can be any executable.
|
||||
|
||||
A handler should read it's input from stdin, and expect to read
|
||||
JSON formatted data. The format of the data depends on the type of the
|
||||
watch. Each watch type documents the format type, and because they
|
||||
map directly to an HTTP API, handlers should expect the input to
|
||||
match the format of the API.
|
||||
|
||||
Additionally, the `CONSUL_INDEX` environmental variable will be set.
|
||||
This maps to the `X-Consul-Index` value from the [HTTP API](/docs/agent/http.html).
|
||||
|
||||
## Global Parameters
|
||||
|
||||
In addition to the parameters supported by each option type, there
|
||||
are a few global parameters that all watches support:
|
||||
|
||||
* `datacenter` - Can be provided to override the agent's default datacenter.
|
||||
* `token` - Can be provided to override the agent's default ACL token.
|
||||
* `handler` - The handler to invoke when the data view updates.
|
||||
|
||||
## Watch Types
|
||||
|
||||
The following types are supported, with more documentation below:
|
||||
|
||||
* `key` - Watch a specific KV pair
|
||||
* `keyprefix` - Watch a prefix in the KV store
|
||||
* `services` - Watch the list of available services
|
||||
* `nodes` - Watch the list of nodes
|
||||
* `service`- Watch the instances of a service
|
||||
* `checks` - Watch the value of health checks
|
||||
|
||||
|
||||
### Type: key
|
||||
|
||||
The "key" watch type is used to watch a specific key in the KV store.
|
||||
It requires that the "key" parameter be specified.
|
||||
|
||||
This maps to the `/v1/kv/` API internally.
|
||||
|
||||
Here is an example configuration:
|
||||
|
||||
{
|
||||
"type": "key",
|
||||
"key": "foo/bar/baz",
|
||||
"handler": "/usr/bin/my-key-handler.sh"
|
||||
}
|
||||
|
||||
Or, using the watch command:
|
||||
|
||||
$ consul watch -type key -key foo/bar/baz /usr/bin/my-key-handler.sh
|
||||
|
||||
An example of the output of this command:
|
||||
|
||||
{
|
||||
"Key": "foo/bar/baz",
|
||||
"CreateIndex": 1793,
|
||||
"ModifyIndex": 1793,
|
||||
"LockIndex": 0,
|
||||
"Flags": 0,
|
||||
"Value": "aGV5",
|
||||
"Session": ""
|
||||
}
|
||||
|
||||
### Type: keyprefix
|
||||
|
||||
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 maps to the `/v1/kv/` API internally.
|
||||
|
||||
Here is an example configuration:
|
||||
|
||||
{
|
||||
"type": "keyprefix",
|
||||
"prefix": "foo/",
|
||||
"handler": "/usr/bin/my-prefix-handler.sh"
|
||||
}
|
||||
|
||||
Or, using the watch command:
|
||||
|
||||
$ consul watch -type keyprefix -prefix foo/ /usr/bin/my-prefix-handler.sh
|
||||
|
||||
An example of the output of this command:
|
||||
|
||||
[
|
||||
{
|
||||
"Key": "foo/bar",
|
||||
"CreateIndex": 1796,
|
||||
"ModifyIndex": 1796,
|
||||
"LockIndex": 0,
|
||||
"Flags": 0,
|
||||
"Value": "TU9BUg==",
|
||||
"Session": ""
|
||||
},
|
||||
{
|
||||
"Key": "foo/baz",
|
||||
"CreateIndex": 1795,
|
||||
"ModifyIndex": 1795,
|
||||
"LockIndex": 0,
|
||||
"Flags": 0,
|
||||
"Value": "YXNkZg==",
|
||||
"Session": ""
|
||||
},
|
||||
{
|
||||
"Key": "foo/test",
|
||||
"CreateIndex": 1793,
|
||||
"ModifyIndex": 1793,
|
||||
"LockIndex": 0,
|
||||
"Flags": 0,
|
||||
"Value": "aGV5",
|
||||
"Session": ""
|
||||
}
|
||||
]
|
||||
|
||||
|
||||
### Type: services
|
||||
|
||||
The "services" watch type is used to watch the list of available
|
||||
services. It has no parameters.
|
||||
|
||||
This maps to the `/v1/catalog/services` API internally.
|
||||
|
||||
An example of the output of this command:
|
||||
|
||||
{
|
||||
"consul": [],
|
||||
"redis": [],
|
||||
"web": []
|
||||
}
|
||||
|
||||
### Type: nodes
|
||||
|
||||
The "nodes" watch type is used to watch the list of available
|
||||
nodes. It has no parameters.
|
||||
|
||||
This maps to the `/v1/catalog/nodes` API internally.
|
||||
|
||||
An example of the output of this command:
|
||||
|
||||
[
|
||||
{
|
||||
"Node": "nyc1-consul-1",
|
||||
"Address": "192.241.159.115"
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-consul-2",
|
||||
"Address": "192.241.158.205"
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-consul-3",
|
||||
"Address": "198.199.77.133"
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-worker-1",
|
||||
"Address": "162.243.162.228"
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-worker-2",
|
||||
"Address": "162.243.162.226"
|
||||
},
|
||||
{
|
||||
"Node": "nyc1-worker-3",
|
||||
"Address": "162.243.162.229"
|
||||
}
|
||||
]
|
||||
|
||||
### Type: service
|
||||
|
||||
The "service" watch type is used to monitor the providers
|
||||
of a single service. It requires the "service" parameter,
|
||||
but optionally takes "tag" and "passingonly". The "tag" parameter
|
||||
will filter by tag, and "passingonly" 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:
|
||||
|
||||
{
|
||||
"type": "service",
|
||||
"key": "redis",
|
||||
"handler": "/usr/bin/my-service-handler.sh"
|
||||
}
|
||||
|
||||
Or, using the watch command:
|
||||
|
||||
$ consul watch -type service -service redis /usr/bin/my-service-handler.sh
|
||||
|
||||
An example of the output of this command:
|
||||
|
||||
[
|
||||
{
|
||||
"Node": {
|
||||
"Node": "foobar",
|
||||
"Address": "10.1.10.12"
|
||||
},
|
||||
"Service": {
|
||||
"ID": "redis",
|
||||
"Service": "redis",
|
||||
"Tags": null,
|
||||
"Port": 8000
|
||||
},
|
||||
"Checks": [
|
||||
{
|
||||
"Node": "foobar",
|
||||
"CheckID": "service:redis",
|
||||
"Name": "Service 'redis' check",
|
||||
"Status": "passing",
|
||||
"Notes": "",
|
||||
"Output": "",
|
||||
"ServiceID": "redis",
|
||||
"ServiceName": "redis"
|
||||
},
|
||||
{
|
||||
"Node": "foobar",
|
||||
"CheckID": "serfHealth",
|
||||
"Name": "Serf Health Status",
|
||||
"Status": "passing",
|
||||
"Notes": "",
|
||||
"Output": "",
|
||||
"ServiceID": "",
|
||||
"ServiceName": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
|
||||
### Type: checks
|
||||
|
||||
The "checks" watch type is used to monitor the checks of a given
|
||||
service or in a specific state. It optionally takes the "service"
|
||||
parameter to filter to a specific service, or "state" 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.
|
||||
|
||||
An example of the output of this command:
|
||||
|
||||
[
|
||||
{
|
||||
"Node": "foobar",
|
||||
"CheckID": "service:redis",
|
||||
"Name": "Service 'redis' check",
|
||||
"Status": "passing",
|
||||
"Notes": "",
|
||||
"Output": "",
|
||||
"ServiceID": "redis",
|
||||
"ServiceName": "redis"
|
||||
}
|
||||
]
|
||||
|
||||
|
|
@ -34,6 +34,7 @@ Available commands are:
|
|||
monitor Stream logs from a Consul agent
|
||||
reload Triggers the agent to reload configuration files
|
||||
version Prints the Consul version
|
||||
watch Watch for changes in Consul
|
||||
```
|
||||
|
||||
To get help for any specific command, pass the `-h` flag to the relevant
|
||||
|
|
|
|||
53
website/source/docs/commands/watch.html.markdown
Normal file
53
website/source/docs/commands/watch.html.markdown
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Commands: Watch"
|
||||
sidebar_current: "docs-commands-watch"
|
||||
---
|
||||
|
||||
# Consul Watch
|
||||
|
||||
Command: `consul watch`
|
||||
|
||||
The watch command provides a mechanism to watch for changes in a particular
|
||||
data view (list of nodes, service members, key value, etc) and to invoke
|
||||
a process with the latest values of the view. If no process is specified,
|
||||
the current values are dumped to stdout which can be a useful way to inspect
|
||||
data in Consul.
|
||||
|
||||
There is more [documentation on watches here](/docs/agent/watches.html).
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `consul watch [options] [child...]`
|
||||
|
||||
The only required option is `-type` which specifies the particular
|
||||
data view. Depending on the type, various options may be required
|
||||
or optionally provided. There is more documentation on watch
|
||||
[specifications here](/docs/agent/watches.html).
|
||||
|
||||
The list of available flags are:
|
||||
|
||||
* `-http-addr` - Address to the HTTP server of the agent you want to contact
|
||||
to send this command. If this isn't specified, the command will contact
|
||||
"127.0.0.1:8500" which is the default HTTP address of a Consul agent.
|
||||
|
||||
* `-datacenter` - Datacenter to query. Defaults to that of agent.
|
||||
|
||||
* `-token` - ACL token to use. Defaults to that of agent.
|
||||
|
||||
* `-key` - Key to watch. Only for `key` type.
|
||||
|
||||
* `-passingonly=[true|false]` - Should only passing entries be returned. Default false.
|
||||
only for `service` type.
|
||||
|
||||
* `-prefix` - Key prefix to watch. Only for `keyprefix` type.
|
||||
|
||||
* `-service` - Service to watch. Required for `service` type, optional for `checks` type.
|
||||
|
||||
* `-state` - Check state to filter on. Optional for `checks` type.
|
||||
|
||||
* `-tag` - Service tag to filter on. Optional for `service` type.
|
||||
|
||||
* `-type` - Watch type. Required, one of "key", "keyprefix", "services",
|
||||
"nodes", "services", or "checks".
|
||||
|
||||
|
|
@ -89,6 +89,10 @@
|
|||
|
||||
<li<%= sidebar_current("docs-commands-reload") %>>
|
||||
<a href="/docs/commands/reload.html">reload</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-commands-watch") %>>
|
||||
<a href="/docs/commands/watch.html">watch</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
|
@ -130,6 +134,10 @@
|
|||
|
||||
<li<%= sidebar_current("docs-agent-telemetry") %>>
|
||||
<a href="/docs/agent/telemetry.html">Telemetry</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-agent-watches") %>>
|
||||
<a href="/docs/agent/watches.html">Watches</a>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue