Skip to content

Latest commit

 

History

History
96 lines (62 loc) · 4.57 KB

stop-a-node.md

File metadata and controls

96 lines (62 loc) · 4.57 KB
title summary toc
Stop or Remove a Node
Learn why and how to temporarily stop a CockroachDB node.
false

Changed in v1.1: This page shows you how to use the cockroach quit command to either temporarily stop a node that you plan to restart or permanently remove a node that has already been decommissioned.

Generally, you temporarily stop nodes during the process of upgrading your cluster's version of CockroachDB, whereas you permanently remove nodes when downsizing a cluster.

Stopping vs. Removing Nodes

To differentiate between stopping and removing nodes, it's important to first understand three concepts:

  • Range: CockroachDB stores all user data and almost all system data in a giant sorted map of key value pairs. This keyspace is divided into "ranges", contiguous chunks of the keyspace, so that every key can always be found in a single range.

  • Range Replica: CockroachDB replicates each range (3 times by default) and stores each replica on a different node.

  • Range Lease: For each range, one of its replicas holds the "range lease". The replica with the lease is the one that receives and coordinates all read and write requests for the range.

When you temporarily stop a node, CockroachDB lets the node finish all in-flight requests and transfers any range leases off the node before shutting it down. Range replicas are left on the node in the expectation that it will rejoin the cluster (specifically in the case of version upgrades). If the node does not rejoin within approximately 5 minutes, however, CockroachDB automatically rebalances the node's range replicas to other nodes, using unaffected replicas on other nodes as sources.

When you permanently remove a node, the only difference is that the range replicas are actively moved off the node before the node shuts down.

Synopsis

# Temporarily stop a node:
$ cockroach quit <flags except --decommission>

# Permanently remove a node:
$ cockroach quit --decommission <other flags>

# View help:
$ cockroach quit --help

Flags

The quit command supports the following general-use and logging flags.

General

Flag Description
--certs-dir The path to the certificate directory. The directory must contain valid certificates if running in secure mode.

Env Variable: COCKROACH_CERTS_DIR
Default: ${HOME}/.cockroach-certs/
--decommission If specified, the node will be permanently removed instead of temporarily stopped.

Use this flag with cockroach quit after decommissioning the node with the cockroach node decommission command.
--host The server host to connect to. This can be the address of any node in the cluster.

Env Variable: COCKROACH_HOST
Default:localhost
--insecure Run in insecure mode. If this flag is not set, the --certs-dir flag must point to valid certificates.

Env Variable: COCKROACH_INSECURE
Default: false
--port The server port to connect to.

Env Variable: COCKROACH_PORT
Default: 26257

Logging

By default, the quit command logs errors to stderr.

If you need to troubleshoot this command's behavior, you can change its logging behavior.

Examples

Temporarily stop a node

Secure Insecure

To temporarily stop a node running in the background:

  1. Install the cockroach binary on a machine separate from the node:

  2. Run the cockroach quit command without the --decommission flag:

    ~~~ shell $ cockroach quit --certs-dir=certs --host= ~~~
    ~~~ shell $ cockroach quit --insecure --host= ~~~

To stop a node running in the foreground, either follow the instructions above or SSH onto the node and press CTRL + c.

Permanently decommission and remove a node

{% include cli/decommission-a-node.html %}

See Also