Add Performance Standby Docs (#5214)

* Add Performance Standby Docs

* Review updates

website/source/api/system/health.html.md

@@ -26,6 +26,7 @@ The default status codes are:
 - `200` if initialized, unsealed, and active
 - `429` if unsealed and standby
 - `472` if data recovery mode replication secondary and active
+- `473` if performance standby 
 - `501` if not initialized
 - `503` if sealed
 
@@ -45,6 +46,9 @@ The default status codes are:
 - `drsecondarycode` `(int: 472)` – Specifies the status code that should be
   returned for a DR secondary node.
 
+- `performancestandbycode` `(int: 473)` – Specifies the status code that should be
+  returned for a performance standby node.
+
 - `sealedcode` `(int: 503)` – Specifies the status code that should be returned
   for a sealed node.
 
@@ -72,6 +76,7 @@ standby of its status.
   "initialized": true,
   "sealed": false,
   "standby": false,
+  "performance_standby": false,
   "replication_perf_mode": "disabled",
   "replication_dr_mode": "disabled",
   "server_time_utc": 1516639589,

website/source/api/system/leader.html.md

@@ -35,6 +35,8 @@ $ curl \
   "ha_enabled": true,
   "is_self": false,
   "leader_address": "https://127.0.0.1:8200/",
-  "leader_cluster_address": "https://127.0.0.1:8201/"
+  "leader_cluster_address": "https://127.0.0.1:8201/",
+  "performance_standby": false,
+  "performance_standby_last_remote_wal": 0
 }
 ```

website/source/docs/configuration/index.html.md

@@ -148,14 +148,17 @@ The following parameters are used on backends that support [high availability][h
 
 ### Vault Enterprise Parameters
 
+The following parameters are only used with Vault Enterprise
+
 - `disable_sealwrap` `(bool: false)` – Disables using [seal wrapping][sealwrap]
   for any value except the master key. If this value is toggled, the new
   behavior will happen lazily (as values are read or written).
 
-- `disable_performance_standby` `(bool: false)` – If set, the node will not be
-  available to act as a performance standby node when not active.
+- `disable_performance_standby` `(bool: false)` – Specifies whether performance
+  standbys should be disabled on this node. Setting this to true on one Vault
+  node will disable this feature when this node is Active or Standby. It's
+  recomended to sync this setting across all nodes in the cluster.
 
-The following parameters are only used with Vault Enterprise
 [storage-backend]: /docs/configuration/storage/index.html
 [listener]: /docs/configuration/listener/index.html
 [seal]: /docs/configuration/seal/index.html

website/source/docs/enterprise/performance-standby/index.html.md

@@ -0,0 +1,95 @@
+---
+layout: "docs"
+page_title: "Performance Standby Nodes - Vault Enterprise"
+sidebar_current: "docs-vault-enterprise-perf-standbys"
+description: |-
+  Performance Standby Nodes - Vault Enterprise
+---
+
+# Performance Standby Nodes 
+
+Vault supports a multi-server mode for high availability. This mode protects
+against outages by running multiple Vault servers. High availability mode
+is automatically enabled when using a data store that supports it. You can 
+learn more about HA mode on the [Concepts](/docs/concepts/ha.html) page.
+
+Vault Enterprise offers additional features that allow HA nodes to service
+read-only requests on the local standby node. Read-only requests are requests
+that do not modify Vault's storage. 
+
+## Server-to-Server Communication
+
+Performance Standbys require the request forwarding method described in the [HA
+Server-to-Server](/docs/concepts/ha.html#server-to-server-communication) docs.
+
+A performance standby will connect to the active node over the existing request
+forwarding connection. If selected by the active node to be promoted to a
+performance standby it will be handed a newly-generated private key and certificate
+for use in creating a new mutually-authenticated TLS connection to the cluster
+port. This connection will be used to send updates from the active node to the
+standby.
+
+## Request Forwarding
+
+A Performance Standby will attempt to process requests that come in. If a
+storage write is detected the standby will forward the request over the cluster
+port connection to the active node. If the request is read-only the Performance
+Standby will handle the requests locally.
+
+Sending requests to Performance Stanbys that result in forwarded writes will be
+slightly slower than going directly to the active node. A client that has
+advanced knowledge of the behavior of the call can choose to point the request
+to the appropriate node.
+
+### Direct Access
+
+A Performance Standby will tag itself as such in consul if service registration
+is enabled. To access the set of Performance Standbys the `performance-standby`
+tag can be used. For example to send requets to only the performance standbys
+`https://performance-standby.vault.dc1.consul` could be used (host name may vary
+based on consul configuration).
+
+### Behind Load Balancers
+
+Additionally, if you wish to point your load balancers at performance standby
+nodes, the `sys/health` endpoint can be used to determine if a node is a
+performance standby. See the [sys/health API](/api/system/health.html) docs for
+more info.
+
+## Storage Support
+
+Using Performance Standbys requires a storage backend that supports
+transactional updates, such as Consul.
+
+## Disabling Performance Standbys
+
+To disable performance standbys the `disable_performance_standby` flag should be
+set to true in the Vault config file. This will both tell a standby not to
+attempt to enable performance mode and an active node to not allow any
+performance standby connections.
+
+This setting should be synced across all nodes in the cluster.
+
+## Monitoring Performance Standbys
+
+To verify your node is a performance standby the `vault status` command can be
+used:
+
+```
+$ vault status
+Key                                    Value
+---                                    -----
+Seal Type                              shamir
+Sealed                                 false
+Total Shares                           1
+Threshold                              1
+Version                                0.11.0+prem
+Cluster Name                           vault-cluster-d040e74c
+Cluster ID                             9f82e03b-71fb-97a6-9c5a-46fa6715d6e4
+HA Enabled                             true
+HA Cluster                             https://127.0.0.1:8201
+HA Mode                                standby
+Active Node Address                    http://127.0.0.1:8200
+Performance Standby Node               true
+Performance Standby Last Remote WAL    380329
+```

website/source/docs/internals/high-availability.html.md

@@ -47,3 +47,22 @@ then one of the standbys will take over and become the active instance.
 It is important to note that only _unsealed_ servers act as a standby.
 If a server is still in the sealed state, then it cannot act as a standby
 as it would be unable to serve any requests should the active server fail.
+
+# Performance Standby Nodes (Enterprise)
+
+Performance Standby Nodes are just like traditional High Availability standby
+nodes but they can service read-only requests from users or applications.
+Read-only requests are requests that do not modify Vault's storage. This allows
+for Vault to quickly scale its ability to service these kinds of operations,
+providing near-linear request-per-second scaling in many common scenarios for
+some secrets engines like K/V and Transit. By spreading traffic across
+performance standby nodes, clients can scale these IOPS horizontally to handle
+extremely high traffic workloads.  
+
+If a request comes into a Performance Standby Node that causes a storage write
+the request will be forwarded onto the active server. If the request is
+read-only the request will be serviced locally on the Performance Standby.
+
+Just like traditional HA standbys if the active node is sealed, fails, or loses
+newtwork connectivity then a performance standby can take over and become the
+active instance.

website/source/layouts/docs.erb

@@ -664,9 +664,12 @@
           <li<%= sidebar_current("docs-vault-enterprise-sealwrap")%>>
             <a href="/docs/enterprise/sealwrap/index.html">Seal Wrap / FIPS 140-2</a>
           </li>
-	  <li<%= sidebar_current("docs-vault-enterprise-namespaces")%>>
+	      <li<%= sidebar_current("docs-vault-enterprise-namespaces")%>>
             <a href="/docs/enterprise/namespaces/index.html">Namespaces</a>
           </li>
+          <li <%= sidebar_current("docs-vault-enterprise-performance-standbys")%>>
+            <a href="/docs/enterprise/performance-standby/index.html">Performance Standbys</a>
+          </li>
           <li<%= sidebar_current("docs-vault-enterprise-control-groups") %>>
             <a href="/docs/enterprise/control-groups/index.html">Control Groups</a>
           </li>