2014-02-08 00:41:03 +00:00
|
|
|
---
|
2020-09-01 15:14:13 +00:00
|
|
|
layout: commands
|
2020-04-07 18:55:19 +00:00
|
|
|
page_title: 'Commands: Leave'
|
|
|
|
|
description: >-
|
|
|
|
|
The `leave` command triggers a graceful leave and shutdown of the agent. It is
|
|
|
|
|
used to ensure other nodes see the agent as left instead of failed. Nodes that
|
|
|
|
|
leave will not attempt to re-join the cluster on restarting with a snapshot.
|
2014-02-08 00:41:03 +00:00
|
|
|
---
|
|
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
# Consul Leave
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
Command: `consul leave`
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2023-01-25 16:52:43 +00:00
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/leave](/consul/api-docs/agent#graceful-leave-and-shutdown)
|
2022-01-10 17:40:11 +00:00
|
|
|
|
2014-10-19 23:40:10 +00:00
|
|
|
The `leave` command triggers a graceful leave and shutdown of the agent.
|
|
|
|
|
It is used to ensure other nodes see the agent as "left" instead of
|
2014-02-08 00:41:03 +00:00
|
|
|
"failed". Nodes that leave will not attempt to re-join the cluster
|
|
|
|
|
on restarting with a snapshot.
|
|
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
For nodes in server mode, the node is removed from the Raft peer set
|
2014-04-16 04:01:12 +00:00
|
|
|
in a graceful manner. This is critical, as in certain situations a
|
|
|
|
|
non-graceful leave can affect cluster availability.
|
2014-02-19 01:32:13 +00:00
|
|
|
|
2023-06-30 15:13:24 +00:00
|
|
|
Depending on how many Consul servers are running, running `consul leave` on a server explicitly can reduce the quorum
|
|
|
|
|
size (which is derived from the number of Consul servers, see
|
|
|
|
|
[deployment_table](/consul/docs/architecture/consensus#deployment_table)).
|
|
|
|
|
Even if the cluster used `bootstrap_expect` to set a number of servers and thus quorum size initially,
|
|
|
|
|
issuing `consul leave` on a server will reconfigure the cluster to have fewer servers.
|
|
|
|
|
This means you could end up with just one server that is still able to commit writes because the quorum size for
|
|
|
|
|
1-server setup is only 1, but those writes might be lost if that server fails before more are added.
|
2019-01-25 20:20:48 +00:00
|
|
|
|
2023-01-25 16:52:43 +00:00
|
|
|
The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of
|
|
|
|
|
[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching)
|
2022-01-10 21:44:56 +00:00
|
|
|
are not supported from commands, but may be from the corresponding HTTP endpoint.
|
|
|
|
|
|
|
|
|
|
| ACL Required |
|
|
|
|
|
| ------------- |
|
|
|
|
|
| `agent:write` |
|
|
|
|
|
|
2014-02-08 00:41:03 +00:00
|
|
|
## Usage
|
|
|
|
|
|
2017-02-09 21:41:17 +00:00
|
|
|
Usage: `consul leave [options]`
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2017-02-09 21:41:17 +00:00
|
|
|
#### API Options
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
@include 'http_api_options_client.mdx'
|
