github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/source/docs/commands/operator.html.markdown

3.7 KiB
Raw Blame History

layout page_title sidebar_current description
docs Commands: Operator docs-commands-operator The operator command provides cluster-level tools for Consul operators.

Consul Operator

Command: consul operator

The operator command provides cluster-level tools for Consul operators, such as interacting with the Raft subsystem. This was added in Consul 0.7.

~> Use this command with extreme caution, as improper use could lead to a Consul outage and even loss of data.

If ACLs are enabled then a token with operator privileges may required in order to use this command. Requests are forwarded internally to the leader if required, so this can be run from any Consul node in a cluster. See the ACL internals guide for more information.

See the Outage Recovery guide for some examples of how this command is used. For an API to perform these operations programatically, please see the documentation for the Operator endpoint.

Usage

Usage: consul operator <subcommand> [common options] [action] [options]

Run consul operator <subcommand> with no arguments for help on that subcommand. The following subcommands are available:

  • raft - View and modify Consul's Raft configuration.

Options common to all subcommands include:

  • -http-addr - Address to the HTTP server of the agent you want to contact to send this command. If this isn't specified, the command will contact "127.0.0.1:8500" which is the default HTTP address of a Consul agent.

  • -token - ACL token to use. Defaults to that of agent.

Raft Operations

The raft subcommand is used to view and modify Consul's Raft configuration. Two actions are available, as detailed in this section.

raft -list-peers -stale=[true|false]

This action displays the current Raft peer configuration.

The -stale argument defaults to "false" which means the leader provides the result. If the cluster is in an outage state without a leader, you may need to set -stale to "true" to get the configuration from a non-leader server.

The output looks like this:

Node     ID              Address         State     Voter
alice    127.0.0.1:8300  127.0.0.1:8300  follower  true
bob      127.0.0.2:8300  127.0.0.2:8300  leader    true
carol    127.0.0.3:8300  127.0.0.3:8300  follower  true

  • Node is the node name of the server, as known to Consul, or "(unknown)" if the node is stale at not known.

  • ID is the ID of the server. This is the same as the Address in Consul 0.7 but may be upgraded to a GUID in a future version of Consul.

  • Address is the IP:port for the server.

  • State is either "follower" or "leader" depending on the server's role in the Raft configuration.

  • Voter is "true" or "false", indicating if the server has a vote in the Raft configuration. Future versions of Consul may add support for non-voting servers.

raft -remove-peer -address="IP:port"

This command removes Consul server with given -address from the Raft configuration.

The -address argument is required and is the "IP:port" for the server to remove. The port number is usually 8300, unless configured otherwise.

There are rare cases where a peer may be left behind in the Raft quorum even though the server is no longer present and known to the cluster. This command can be used to remove the failed server so that it is no longer affects the Raft quorum. If the server still shows in the output of the consul members command, it is preferable to clean up by simply running consul force-leave instead of this command.