diff --git a/website/source/docs/agent/http.html.markdown b/website/source/docs/agent/http.html.markdown index 2b59a2da98..17d21ec903 100644 --- a/website/source/docs/agent/http.html.markdown +++ b/website/source/docs/agent/http.html.markdown @@ -18,6 +18,7 @@ All endpoints fall into one of several categories: * health - Manages health checks * session - Session manipulation * acl - ACL creations and management +* event - User Events * status - Consul system status * internal - Internal APIs. Purposely undocumented, subject to change. @@ -1188,6 +1189,97 @@ It returns a JSON body like this: ... ] +## Event + +The Event endpoints are used to fire new events and to query the available +events. + +The following endpoints are supported: + +* /v1/event/fire/\: Fires a new user event +* /v1/event/list: Lists the most recent events an agent has seen. + +### /v1/event/fire/\ + +The fire endpoint is used to trigger a new user event. A user event +needs a name, and optionally takes a number of parameters. + +By default, the agent's local datacenter is used, but another datacenter +can be specified using the "?dc=" query parameter. + +The fire endpoint expects a PUT request, with an optional body. +The body contents are opaque to Consul, and become the "payload" +of the event. + +The `?node=`, `?service=`, and `?tag=` query parameters may optionally +be provided. They respectively provide a regular expression to filter +by node name, service, and service tags. + +The return code is 200 on success, along with a body like: + + { + "ID":"b54fe110-7af5-cafc-d1fb-afc8ba432b1c", + "Name":"deploy", + "Payload":null, + "NodeFilter":"", + "ServiceFilter":"", + "TagFilter":"", + "Version":1, + "LTime":0 + } + +This is used to provide the ID of the newly fired event. + +### /v1/event/list + +Thie endpoint is hit with a GET and returns the most recent +events known by the agent. As a consequence of how the +[event command](/docs/commands/event.html) works, each agent +may have a different view of the events. Events are broadcast using +the [gossip protocol](/docs/internals/gossip.html), which means +they have no total ordering, nor do they make a promise of delivery. + +Additionally, each node applies the node, service and tag filters +locally before storing the event. This means the events at each agent +may be different depending on their configuration. + +This endpoint does allow for filtering on events by name by providing +the `?name=` query parameter. + +Lastly, to support [watches](/docs/agent/watches.html), this endpoint +supports blocking queries. However, the semantics of this endpoint +is slightly different. Most blocking queries provide a monotonic index, +and block until a newer index is available. This can be supported as +a consequence of the total ordering of the [consensus protocol](/docs/internals/consensus.html). +With gossip, there is no ordering, and instead `X-Consul-Index` maps +to the newest event that matches the query. + +In practice, this means the index is only useful when used against a +single agent, and has no meaning globally. Because Consul defines +the index as being opaque, clients should not be expecting a natural +ordering either. + +Lastly, agent's only buffer the most recent entries. The number +of entries should not be depended upon, but currently defaults to +256. This value could change in the future. The buffer should be large +enough for most clients and watches. + +It returns a JSON body like this: + + [ + { + "ID": "b54fe110-7af5-cafc-d1fb-afc8ba432b1c", + "Name": "deploy", + "Payload": "MTYwOTAzMA=="", + "NodeFilter": "", + "ServiceFilter": "", + "TagFilter": "", + "Version": 1, + "LTime": 19 + }, + ... + ] + ## Status The Status endpoints are used to get information about the status diff --git a/website/source/docs/agent/watches.html.markdown b/website/source/docs/agent/watches.html.markdown index a3b03157a6..561e6594c3 100644 --- a/website/source/docs/agent/watches.html.markdown +++ b/website/source/docs/agent/watches.html.markdown @@ -62,6 +62,7 @@ The following types are supported, with more documentation below: * `nodes` - Watch the list of nodes * `service`- Watch the instances of a service * `checks` - Watch the value of health checks +* `event` - Watch for custom user events ### Type: key @@ -284,3 +285,45 @@ An example of the output of this command: } ] + +### Type: event + +The "event" watch type is used to monitor for custom user +events. These are fired using the [consul event](/docs/commands/event.html) command. +It takes only a single optional "name" parameter, which restricts +the watch to only events with the given name. + +This maps to the `v1/event/list` API internvally. + +Here is an example configuration: + + { + "type": "event", + "name": "web-deploy", + "handler": "/usr/bin/my-deploy-handler.sh" + } + +Or, using the watch command: + + $ consul watch -type event -name web-deploy /usr/bin/my-deploy-handler.sh + +An example of the output of this command: + + [ + { + "ID": "f07f3fcc-4b7d-3a7c-6d1e-cf414039fcee", + "Name": "web-deploy", + "Payload": "MTYwOTAzMA==", + "NodeFilter": "", + "ServiceFilter": "", + "TagFilter": "", + "Version": 1, + "LTime": 18 + }, + ... + ] + +To fire a new `web-deploy` event the following could be used: + + $ consul event -name web-deploy 1609030 + diff --git a/website/source/docs/commands/event.html.markdown b/website/source/docs/commands/event.html.markdown new file mode 100644 index 0000000000..8b851f7980 --- /dev/null +++ b/website/source/docs/commands/event.html.markdown @@ -0,0 +1,56 @@ +--- +layout: "docs" +page_title: "Commands: Event" +sidebar_current: "docs-commands-event" +--- + +# Consul Event + +Command: `consul event` + +The event command provides a mechanism to fire a custom user event to an +entire datacenter. These events are opaque to Consul, but they can be used +to build scripting infrastructure to do automated deploys, restart services, +or perform any other orchestration action. Events can be handled by +[using a watch](/docs/agent/watches.html). + +Under the hood, events are propogated using the [gossip protocol](/docs/internals/gossip.html). +While the details are not important for using events, an understanding of +the semantics is useful. The gossip layer will make a best-effort to deliver +the event, but there is **no guarantee** delivery. Unlike most Consul data, which is +replicated using [consensus](/docs/internals/consensus.html), event data +is purely peer-to-peer over gossip. This means it is not persisted and does +not have a total ordering. In practice, this means you cannot rely on the +order of message delivery. An advantage however is that events can still +be used even in the absense of server nodes or during an outage. + +The underlying gossip also sets limits on the size of a user event +message. It is hard to give an exact number, as it depends on various +parameters of the event, but the payload should be kept very small +(< 100 bytes). Specifying too large of an event will return an error. + +## Usage + +Usage: `consul event [options] [payload]` + +The only required option is `-name` which specifies the event name. An optional +payload can be provided as the final argument. + +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. + +* `-name` - The name of the event. + +* `-node` - Regular expression to filter nodes which should evaluate the event. + +* `-service` - Regular expression to filter to only nodes which matching services. + +* `-tag` - Regular expression to filter to only nodes with a service that has + a matching tag. This must be used with `-service`. As an example, you may + do "-server mysql -tag slave". + diff --git a/website/source/docs/commands/watch.html.markdown b/website/source/docs/commands/watch.html.markdown index 7f565a3594..a0d53fc1d4 100644 --- a/website/source/docs/commands/watch.html.markdown +++ b/website/source/docs/commands/watch.html.markdown @@ -37,6 +37,8 @@ The list of available flags are: * `-key` - Key to watch. Only for `key` type. +* `-name`- Event name to watch. Only for `event` type. + * `-passingonly=[true|false]` - Should only passing entries be returned. Default false. only for `service` type. @@ -49,5 +51,5 @@ The list of available flags are: * `-tag` - Service tag to filter on. Optional for `service` type. * `-type` - Watch type. Required, one of "key", "keyprefix", "services", - "nodes", "services", or "checks". + "nodes", "services", "checks", or "event". diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 427a7be74c..04855527a0 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -57,6 +57,10 @@