HashiConf 2024 Now streaming live from Boston! Attend for free
Consul
Consul Home

You are viewing documentation for version v1.11.x. View latest version.

Consul Event

Command: consul event

Corresponding HTTP API Endpoint: [PUT] /v1/event/fire/:name

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.

Under the hood, events are propagated using the gossip protocol.

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, 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. Configuration of blocking queries and agent 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

  • -ca-file=<value> - Path to a CA file to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CACERT environment variable.

  • -ca-path=<value> - Path to a directory of CA certificates to use for TLS when communicating with Consul. This can also be specified via the CONSUL_CAPATH environment variable.

  • -client-cert=<value> - Path to a client cert file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_CERT environment variable.

  • -client-key=<value> - Path to a client key file to use for TLS when verify_incoming is enabled. This can also be specified via the CONSUL_CLIENT_KEY environment variable.

  • -http-addr=<addr> - Address of the Consul agent with the port. This can be an IP address or DNS address, but it must include the port. This can also be specified via the CONSUL_HTTP_ADDR environment variable. In Consul 0.8 and later, the default value is http://127.0.0.1:8500, and https can optionally be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using unix:///path/to/socket if the agent is configured to listen that way.

  • -tls-server-name=<value> - The server name to use as the SNI host when connecting via TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME environment variable.

  • -token=<value> - ACL token to use in the request. This can also be specified via the CONSUL_HTTP_TOKEN environment variable. If unspecified, the query will default to the token of the Consul agent at the HTTP address.

  • -token-file=<value> - File containing the ACL token to use in the request instead of one specified via the -token argument or CONSUL_HTTP_TOKEN environment variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE environment variable.

  • -datacenter=<name> - Name of the datacenter to query. If unspecified, the query will default to the datacenter of the Consul agent at the HTTP address.

  • -stale - Permit any Consul server (non-leader) to respond to this request. This allows for lower latency and higher throughput, but can result in stale data. This option has no effect on non-read operations. The default value is false.

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.