diff --git a/command/operator_raft.go b/command/operator_raft.go index cb5f7eecb4..34107dbb59 100644 --- a/command/operator_raft.go +++ b/command/operator_raft.go @@ -20,9 +20,9 @@ func (c *OperatorRaftCommand) Help() string { helpText := ` Usage: vault operator raft [options] [args] - This command groups subcommands for operators interacting with the Vault raft storage backend. Most - users will not need to interact with these commands. Here are a few examples - of the raft operator commands: + This command groups subcommands for operators interacting with the Vault raft + storage backend. Most users will not need to interact with these commands. Here + are a few examples of the raft operator commands: Joins a node to the raft cluster: @@ -38,7 +38,7 @@ Usage: vault operator raft [options] [args] Restores and saves snapshots from the raft cluster: - $ vault operator raft snapshot take out.snap + $ vault operator raft snapshot save out.snap Please see the individual subcommand help for detailed usage information. ` diff --git a/command/operator_raft_join.go b/command/operator_raft_join.go index bc05ec930b..07688b750b 100644 --- a/command/operator_raft_join.go +++ b/command/operator_raft_join.go @@ -22,15 +22,15 @@ type OperatorRaftJoinCommand struct { } func (c *OperatorRaftJoinCommand) Synopsis() string { - return "Joins a node to the raft cluster" + return "Joins a node to the Raft cluster" } func (c *OperatorRaftJoinCommand) Help() string { helpText := ` Usage: vault operator raft join [options] - Join the current node as a peer to the raft cluster by providing the address - of the raft leader node. + Join the current node as a peer to the Raft cluster by providing the address + of the Raft leader node. $ vault operator raft join "http://127.0.0.2:8200" @@ -48,28 +48,28 @@ func (c *OperatorRaftJoinCommand) Flags() *FlagSets { Name: "leader-ca-cert", Target: &c.flagLeaderCACert, Completion: complete.PredictNothing, - Usage: "CA cert to communicate with raft leader.", + Usage: "CA cert to communicate with Raft leader.", }) f.StringVar(&StringVar{ Name: "leader-client-cert", Target: &c.flagLeaderClientCert, Completion: complete.PredictNothing, - Usage: "Client cert to to authenticate to raft leader.", + Usage: "Client cert to to authenticate to Raft leader.", }) f.StringVar(&StringVar{ Name: "leader-client-key", Target: &c.flagLeaderClientKey, Completion: complete.PredictNothing, - Usage: "Client key to to authenticate to raft leader.", + Usage: "Client key to to authenticate to Raft leader.", }) f.BoolVar(&BoolVar{ Name: "retry", Target: &c.flagRetry, Default: false, - Usage: "Continuously retry joining the raft cluster upon failures.", + Usage: "Continuously retry joining the Raft cluster upon failures.", }) f.BoolVar(&BoolVar{ @@ -129,7 +129,7 @@ func (c *OperatorRaftJoinCommand) Run(args []string) int { NonVoter: c.flagNonVoter, }) if err != nil { - c.UI.Error(fmt.Sprintf("Error joining the node to the raft cluster: %s", err)) + c.UI.Error(fmt.Sprintf("Error joining the node to the Raft cluster: %s", err)) return 2 } diff --git a/command/operator_raft_listpeers.go b/command/operator_raft_listpeers.go index b9cbd2eb45..765996c1b7 100644 --- a/command/operator_raft_listpeers.go +++ b/command/operator_raft_listpeers.go @@ -16,14 +16,14 @@ type OperatorRaftListPeersCommand struct { } func (c *OperatorRaftListPeersCommand) Synopsis() string { - return "Returns the raft peer set" + return "Returns the Raft peer set" } func (c *OperatorRaftListPeersCommand) Help() string { helpText := ` Usage: vault operator raft list-peers - Provides the details of all the peers in the raft cluster. + Provides the details of all the peers in the Raft cluster. $ vault operator raft list-peers diff --git a/command/operator_raft_remove_peer.go b/command/operator_raft_remove_peer.go index 2ff62d30d5..86939bebdb 100644 --- a/command/operator_raft_remove_peer.go +++ b/command/operator_raft_remove_peer.go @@ -16,14 +16,14 @@ type OperatorRaftRemovePeerCommand struct { } func (c *OperatorRaftRemovePeerCommand) Synopsis() string { - return "Removes a node from the raft cluster" + return "Removes a node from the Raft cluster" } func (c *OperatorRaftRemovePeerCommand) Help() string { helpText := ` Usage: vault operator raft remove-peer - Removes a node from the raft cluster. + Removes a node from the Raft cluster. $ vault operator raft remove-peer node1 diff --git a/command/operator_raft_snapshot.go b/command/operator_raft_snapshot.go index 8003d295e7..5e3b042877 100644 --- a/command/operator_raft_snapshot.go +++ b/command/operator_raft_snapshot.go @@ -13,21 +13,22 @@ type OperatorRaftSnapshotCommand struct { } func (c *OperatorRaftSnapshotCommand) Synopsis() string { - return "Restores and saves snapshots from the raft cluster" + return "Restores and saves snapshots from the Raft cluster" } func (c *OperatorRaftSnapshotCommand) Help() string { helpText := ` Usage: vault operator raft snapshot [options] [args] - This command groups subcommands for operators interacting with the snapshot functionality of - the raft storage backend. Here are a few examples of the raft snapshot operator commands: + This command groups subcommands for operators interacting with the snapshot + functionality of the integrated Raft storage backend. Here are a few examples of + the Raft snapshot operator commands: Installs the provided snapshot, returning the cluster to the state defined in it: $ vault operator raft snapshot restore raft.snap - Saves a snapshot of the current state of the raft cluster into a file: + Saves a snapshot of the current state of the Raft cluster into a file: $ vault operator raft snapshot save raft.snap diff --git a/command/operator_raft_snapshot_save.go b/command/operator_raft_snapshot_save.go index adaa1e87b2..a23ebc7b89 100644 --- a/command/operator_raft_snapshot_save.go +++ b/command/operator_raft_snapshot_save.go @@ -17,14 +17,14 @@ type OperatorRaftSnapshotSaveCommand struct { } func (c *OperatorRaftSnapshotSaveCommand) Synopsis() string { - return "Saves a snapshot of the current state of the raft cluster into a file" + return "Saves a snapshot of the current state of the Raft cluster into a file" } func (c *OperatorRaftSnapshotSaveCommand) Help() string { helpText := ` Usage: vault operator raft snapshot save - Saves a snapshot of the current state of the raft cluster into a file. + Saves a snapshot of the current state of the Raft cluster into a file. $ vault operator raft snapshot save raft.snap diff --git a/website/data/docs-navigation.js b/website/data/docs-navigation.js index a86bae1f43..acd2185ceb 100644 --- a/website/data/docs-navigation.js +++ b/website/data/docs-navigation.js @@ -138,6 +138,7 @@ export default [ 'init', 'key-status', 'migrate', + 'raft', 'rekey', 'rotate', 'seal', diff --git a/website/pages/docs/commands/operator/raft.mdx b/website/pages/docs/commands/operator/raft.mdx new file mode 100644 index 0000000000..4685f18bbf --- /dev/null +++ b/website/pages/docs/commands/operator/raft.mdx @@ -0,0 +1,158 @@ +--- +layout: docs +page_title: operator raft - Command +sidebar_title: raft +description: >- + The "operator raft" command is used to interact with the integrated Raft storage backend. +--- + +# operator raft + +This command groups subcommands for operators to manage the integrated Raft storage backend. + +```text +Usage: vault operator raft [options] [args] + + This command groups subcommands for operators interacting with the Vault + integrated Raft storage backend. Most users will not need to interact with these + commands. Here are a few examples of the Raft operator commands: + +Subcommands: + join Joins a node to the Raft cluster + list-peers Returns the Raft peer set + remove-peer Removes a node from the Raft cluster + snapshot Restores and saves snapshots from the Raft cluster +``` + +## join + +This command is used to join a new node as a peer to the Raft cluster. In order +to join, there must be at least one existing member of the cluster. If Shamir +seal is in use, then this API will request for the unseal keys to be supplied to +join the cluster. + +```text +Usage: vault operator raft join [options] + + Join the current node as a peer to the Raft cluster by providing the address + of the Raft leader node. + + $ vault operator raft join "http://127.0.0.2:8200" +``` + +### Parameters + +The following flags are available for the `operator raft join` command. + +- `-leader-ca-cert` `(string: "")` - CA cert to communicate with Raft leader. + +- `-leader-client-cert` `(string: "")` - Client cert to to authenticate to Raft leader. + +- `-leader-client-key` `(string: "")` - Client key to to authenticate to Raft leader. + +- `-non-voter` `(bool: false) (enterprise)` - This flag is used to make the + server not participate in the Raft quorum, and have it only receive the data + replication stream. This can be used to add read scalability to a cluster in + cases where a high volume of reads to servers are needed. The default is false. + +- `-retry` `(bool: false)` - Continuously retry joining the Raft cluster upon + failures. The default is false. + +## list-peers + +This command is used to list the full set of peers in the Raft cluster. + +```text +Usage: vault operator raft list-peers + + Provides the details of all the peers in the Raft cluster. + + $ vault operator raft list-peers +``` + +### Example Output + +```python +{ + ... + "data": { + "config": { + "index": 62, + "servers": [ + { + "address": "127.0.0.2:8201", + "leader": true, + "node_id": "node1", + "protocol_version": "3", + "voter": true + }, + { + "address": "127.0.0.4:8201", + "leader": false, + "node_id": "node3", + "protocol_version": "3", + "voter": true + } + ] + } + } +} +``` + +## remove-peer + +This command is used to remove a node from being a peer to the Raft cluster. In +certain cases where a peer may be left behind in the Raft configuration 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. + +```text +Usage: vault operator raft remove-peer + + Removes a node from the Raft cluster. + + $ vault operator raft remove-peer node1 +``` + +## snapshot + +This command groups subcommands for operators interacting with the snapshot +functionality of the integrated Raft storage backend. There are 2 subcommands +supported: `save` and `restore`. + +```text +Usage: vault operator raft snapshot [options] [args] + + This command groups subcommands for operators interacting with the snapshot + functionality of the integrated Raft storage backend. + +Subcommands: + restore Installs the provided snapshot, returning the cluster to the state defined in it + save Saves a snapshot of the current state of the Raft cluster into a file +``` + +### snapshot save + +Takes a snapshot of the Vault data. The snapshot can be used to restore Vault to +the point in time when a snapshot was taken. + +```text +Usage: vault operator raft snapshot save + + Saves a snapshot of the current state of the Raft cluster into a file. + + $ vault operator raft snapshot save raft.snap +``` + +### snapshot restore + +Restores a snapshot of Vault data taken with `vault operator raft snapshot save`. + +```text +Usage: vault operator raft snapshot restore + + Installs the provided snapshot, returning the cluster to the state defined in it. + + $ vault operator raft snapshot restore raft.snap +```