open-consul/website/content/commands/event.mdx

72 lines
2.8 KiB
Plaintext
Raw Normal View History

2014-08-29 00:22:56 +00:00
---
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: Event'
description: >-
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.
2014-08-29 00:22:56 +00:00
---
# Consul Event
Command: `consul event`
2022-01-11 13:26:58 +00:00
Corresponding HTTP API Endpoint: [\[PUT\] /v1/event/fire/:name](/api-docs/event#fire-event)
The `event` command provides a mechanism to fire a custom user event to an
2014-08-29 00:22:56 +00:00
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
2020-04-09 23:46:54 +00:00
[using a watch](/docs/agent/watches).
2014-08-29 00:22:56 +00:00
2020-04-09 23:46:54 +00:00
Under the hood, events are propagated using the [gossip protocol](/docs/internals/gossip).
2014-08-29 00:22:56 +00:00
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 guaranteed delivery**. Unlike most Consul data, which is
2020-04-09 23:46:54 +00:00
replicated using [consensus](/docs/internals/consensus), event data
2014-08-29 00:22:56 +00:00
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
2014-11-05 04:01:45 +00:00
be used even in the absence of server nodes or during an outage.
2014-08-29 00:22:56 +00:00
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.
The table below shows this command's [required ACLs](/api#authentication). Configuration of
[blocking queries](/api/features/blocking) and [agent caching](/api/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.
| ACL Required |
| ------------- |
| `event:write` |
2014-08-29 00:22:56 +00:00
## 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.
#### API Options
2014-08-29 00:22:56 +00:00
2020-04-07 18:55:19 +00:00
@include 'http_api_options_client.mdx'
2020-04-07 23:56:08 +00:00
2020-04-07 18:55:19 +00:00
@include 'http_api_options_server.mdx'
2014-08-29 00:22:56 +00:00
#### Command Options
2014-08-29 00:22:56 +00:00
2020-04-07 18:55:19 +00:00
- `-name` - The name of the event.
2014-08-29 00:22:56 +00:00
2020-04-07 18:55:19 +00:00
- `-node` - Regular expression to filter nodes which should evaluate the event.
2014-08-29 00:22:56 +00:00
2020-04-07 18:55:19 +00:00
- `-service` - Regular expression to filter to only nodes with matching services.
2014-08-29 00:22:56 +00:00
2020-04-07 18:55:19 +00:00
- `-tag` - Regular expression to filter to only nodes with a service that has
2014-08-29 00:22:56 +00:00
a matching tag. This must be used with `-service`. As an example, you may
do `-service mysql -tag secondary`.