website: Adding docs

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/\<name\>: Fires a new user event
+* /v1/event/list: Lists the most recent events an agent has seen.
+
+### /v1/event/fire/\<name\>
+
+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

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
+

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".
+

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".
 

website/source/layouts/docs.erb

@@ -57,6 +57,10 @@
 				<ul class="nav">
 					<li<%= sidebar_current("docs-commands-agent") %>>
 					<a href="/docs/commands/agent.html">agent</a>
+                    </li>
+
+					<li<%= sidebar_current("docs-commands-event") %>>
+					<a href="/docs/commands/event.html">event</a>
 					</li>
 
 					<li<%= sidebar_current("docs-commands-forceleave") %>>