mirror of https://github.com/hashicorp/consul
48 lines
2.0 KiB
Markdown
48 lines
2.0 KiB
Markdown
---
|
|
layout: commands
|
|
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.
|
|
---
|
|
|
|
# Consul Leave
|
|
|
|
Command: `consul leave`
|
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/leave](/consul/api-docs/agent#graceful-leave-and-shutdown)
|
|
|
|
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.
|
|
|
|
For nodes in server mode, the node is removed from the Raft peer set
|
|
in a graceful manner. This is critical, as in certain situations a
|
|
non-graceful leave can affect cluster availability.
|
|
|
|
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.
|
|
|
|
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)
|
|
are not supported from commands, but may be from the corresponding HTTP endpoint.
|
|
|
|
| ACL Required |
|
|
| ------------- |
|
|
| `agent:write` |
|
|
|
|
## Usage
|
|
|
|
Usage: `consul leave [options]`
|
|
|
|
#### API Options
|
|
|
|
@include 'http_api_options_client.mdx'
|