Raft cli docs (#8548)

* Raft cli docs

* s/raft/Raft

* s/raft/Raft

* Update website/pages/docs/commands/operator/raft.mdx

Co-Authored-By: Meggie <m.ladlow@gmail.com>

* Mention that shamir seal requires unseal keys

Co-authored-by: Meggie <m.ladlow@gmail.com>

command/operator_raft.go

@@ -20,9 +20,9 @@ func (c *OperatorRaftCommand) Help() string {
 	helpText := `
 Usage: vault operator raft <subcommand> [options] [args]
 
-  This command groups subcommands for operators interacting with the Vault raft storage backend. Most
+  This command groups subcommands for operators interacting with the Vault raft
-  users will not need to interact with these commands. Here are a few examples
+  storage backend. Most users will not need to interact with these commands. Here
-  of the raft operator commands:
+  are a few examples of the raft operator commands:
 
   Joins a node to the raft cluster:
 
@@ -38,7 +38,7 @@ Usage: vault operator raft <subcommand> [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.
 `

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] <leader-api-addr>
 
-  Join the current node as a peer to the raft cluster by providing the address
+  Join the current node as a peer to the Raft cluster by providing the address
-  of the raft leader node.
+  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
 	}
 

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
 

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 <server_id>
 
-  Removes a node from the raft cluster.
+  Removes a node from the Raft cluster.
 
 	  $ vault operator raft remove-peer node1
 

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 <subcommand> [options] [args]
 
-  This command groups subcommands for operators interacting with the snapshot functionality of
+  This command groups subcommands for operators interacting with the snapshot
-  the raft storage backend. Here are a few examples of the raft snapshot operator commands:
+  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
 

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 <snapshot_file>
 
-  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
 

website/data/docs-navigation.js

@@ -138,6 +138,7 @@ export default [
           'init',
           'key-status',
           'migrate',
+          'raft',
           'rekey',
           'rotate',
           'seal',

website/pages/docs/commands/operator/raft.mdx

@@ -0,0 +1,158 @@
+---
+layout: docs
+page_title: operator raft - Command
+sidebar_title: <code>raft</code>
+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 <subcommand> [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] <leader-api-addr>
+
+  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 <server_id>
+
+  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 <subcommand> [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 <snapshot_file>
+
+  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 <snapshot_file>
+
+  Installs the provided snapshot, returning the cluster to the state defined in it.
+
+	  $ vault operator raft snapshot restore raft.snap
+```