open-consul/website/pages/commands/force-leave.mdx

66 lines
2.2 KiB
Plaintext
Raw Normal View History

2014-02-08 00:41:03 +00:00
---
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: Force Leave'
sidebar_title: force-leave
2020-04-07 18:55:19 +00:00
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
---
# Consul Force Leave
2014-02-08 00:41:03 +00:00
Command: `consul force-leave`
2014-02-08 00:41:03 +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
was shutdown without a [graceful leave](/commands/leave).
2014-02-08 00:41:03 +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),
Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave`
command can be used to transition the "failed" nodes to a "left" state more
quickly, as reported by [`consul members`](/commands/members).
2014-02-08 00:41:03 +00:00
This can be particularly useful for a node that was running as a server,
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-08 00:41:03 +00:00
## Usage
Usage: `consul force-leave [options] node`
2014-02-08 00:41:03 +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
## 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
[WAN gossip pool](https://learn.hashicorp.com/consul/security-networking/datacenters),
`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:
```
consul force-leave server1.us-east1
```
2020-04-07 18:55:19 +00:00
#### Command Options
2020-04-07 18:55:19 +00:00
- `-prune` - Removes failed or left agent from the list of
members entirely