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 @@