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: Force Leave'
|
|
|
|
|
description: >-
|
|
|
|
|
The `force-leave` command forces a member of a Consul cluster to enter the
|
|
|
|
|
left state. If the member is still actually alive, it will eventually rejoin
|
|
|
|
|
the cluster. The true purpose of this method is to force remove failed nodes.
|
2014-02-08 00:41:03 +00:00
|
|
|
---
|
|
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
# Consul Force Leave
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
Command: `consul force-leave`
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2023-01-25 16:52:43 +00:00
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/force-leave/:node](/consul/api-docs/agent#force-leave-and-shutdown)
|
2022-01-10 17:40:11 +00:00
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
The `force-leave` command forces a member of a Consul cluster to enter the
|
2020-04-07 18:55:19 +00:00
|
|
|
"left" state. The purpose of this method is to force-remove a node that has failed or
|
2023-01-25 16:52:43 +00:00
|
|
|
was shutdown without a [graceful leave](/consul/commands/leave).
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2019-09-27 23:49:28 +00:00
|
|
|
Consul periodically tries to reconnect to "failed" nodes in case failure was due
|
|
|
|
|
to a network partition. After some configured amount of time (by default 72 hours),
|
2014-02-19 01:32:13 +00:00
|
|
|
Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave`
|
2019-09-27 23:49:28 +00:00
|
|
|
command can be used to transition the "failed" nodes to a "left" state more
|
2023-01-25 16:52:43 +00:00
|
|
|
quickly, as reported by [`consul members`](/consul/commands/members).
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
This can be particularly useful for a node that was running as a server,
|
2019-09-27 23:49:28 +00:00
|
|
|
as it will eventually be removed from the Raft configuration by the leader.
|
|
|
|
|
|
|
|
|
|
~> Note that for `force-leave` to take full effect the target node's agent must have
|
|
|
|
|
shutdown permanently. If the agent is alive and reachable then it will not be removed
|
|
|
|
|
from the datacenter's member list nor from the raft configuration. Additionally,
|
|
|
|
|
if the agent returns after transitioning to the "left" state, but before it is reaped
|
|
|
|
|
from the member list, then it will rejoin the cluster.
|
2014-02-19 01:32:13 +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 |
|
|
|
|
|
| ---------------- |
|
|
|
|
|
| `operator:write` |
|
|
|
|
|
|
2014-02-08 00:41:03 +00:00
|
|
|
## Usage
|
|
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
Usage: `consul force-leave [options] node`
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2017-02-08 00:16:33 +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'
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2019-09-27 23:49:28 +00:00
|
|
|
## Examples
|
|
|
|
|
|
|
|
|
|
Remove a node named `ec2-001-staging` from the local agent's datacenter:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
consul force-leave ec2-001-staging
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
When run on a server that is part of a
|
2023-02-07 16:36:32 +00:00
|
|
|
[WAN gossip pool](/consul/tutorials/networking/federation-gossip-wan),
|
2019-09-27 23:49:28 +00:00
|
|
|
`force-leave` can remove failed servers in other datacenters from the WAN pool.
|
|
|
|
|
|
|
|
|
|
The identifying node-name in a WAN pool is `[node-name].[datacenter]`.
|
|
|
|
|
Therefore, to remove a failed server node named `server1` from
|
2020-04-07 18:55:19 +00:00
|
|
|
datacenter `us-east1`, run:
|
2019-09-27 23:49:28 +00:00
|
|
|
|
|
|
|
|
```
|
|
|
|
|
consul force-leave server1.us-east1
|
|
|
|
|
```
|
2020-04-07 18:55:19 +00:00
|
|
|
|
2019-10-04 21:10:02 +00:00
|
|
|
#### Command Options
|
|
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
- `-prune` - Removes failed or left agent from the list of
|
2021-12-20 23:56:13 +00:00
|
|
|
members entirely. Added in Consul 1.6.2.
|
|
|
|
|
|
|
|
|
|
- `-wan` - Exclusively leave the agent from the WAN gossip pool. Added in Consul
|
|
|
|
|
1.11.0.
|
