72 lines
2.8 KiB
Plaintext
72 lines
2.8 KiB
Plaintext
---
|
|
layout: commands
|
|
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.
|
|
---
|
|
|
|
# Consul Event
|
|
|
|
Command: `consul event`
|
|
|
|
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
|
|
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).
|
|
|
|
Under the hood, events are propagated using the [gossip protocol](/docs/internals/gossip).
|
|
|
|
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
|
|
replicated using [consensus](/docs/internals/consensus), 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 absence 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.
|
|
|
|
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` |
|
|
|
|
## 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
|
|
|
|
@include 'http_api_options_client.mdx'
|
|
|
|
@include 'http_api_options_server.mdx'
|
|
|
|
#### Command Options
|
|
|
|
- `-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 with 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 `-service mysql -tag secondary`.
|