Add plugin backends docs (#3125)

* Add docs on plugins/backend/reload, add plugin backend guide

* Fix docs headers

* Fix API endpoint description

* Update plugin guide and internals pages

website/source/api/system/plugins-backend-reload.html.md

@@ -0,0 +1,47 @@
+---
+layout: "api"
+page_title: "/sys/plugins/backend/reload - HTTP API"
+sidebar_current: "docs-http-system-plugins-backend-reload"
+description: |-
+  The `/sys/plugins/backend/reload` endpoint is used to reload plugin backends.
+---
+
+# `/sys/plugins/backend/reload`
+
+The `/sys/plugins/backend/reload` endpoint is used to reload mounted plugin
+backends. Either the plugin name (`plugin`) or the desired plugin backend mounts
+(`mounts`) must be provided, but not both. In the case that the plugin name is
+provided, all mounted paths that use that plugin backend will be reloaded.
+
+## Reload Plugins
+
+This endpoint reloads mounted plugin backends.
+
+| Method   | Path                      -   | Produces               |
+| :------- | :---------------------------- | :--------------------- |
+| `PUT`    | `/sys/plugins/backend/reload` | `204 (empty body)`     |
+
+### Parameters
+
+- `plugin` `(string: "")` – The name of the plugin to reload, as 
+  registered in the plugin catalog.
+
+- `mounts` `(slice: [])` – Array or comma separated string mount paths 
+  of the plugin backends to reload.
+
+### Sample Payload
+
+```json
+{
+  "plugin": "mock-plugin"
+}
+```
+
+### Sample Request
+
+```
+$ curl \
+    --header "X-Vault-Token: ..." \
+    --request PUT
+    https://vault.rocks/v1/sys/backends/reload
+```

website/source/docs/internals/plugins.html.md

@@ -26,11 +26,14 @@ crash the entirety of Vault.
 
 ## Plugin Communication
 Vault creates a mutually authenticated TLS connection for communication with the
-plugin's RPC server. While invoking the plugin process Vault passes a [wrapping
+plugin's RPC server. While invoking the plugin process, Vault passes a [wrapping
 token](https://www.vaultproject.io/docs/concepts/response-wrapping.html) to the
 plugin process' environment. This token is single use and has a short TTL. Once
-unwrapped, it provides the plugin with a unique generated TLS certificate and
-private key for it to use to talk to the original vault process. 
+unwrapped, it provides the plugin with a uniquely generated TLS certificate and
+private key for it to use to talk to the original vault process.
+
+~> Note: Reading the original connection's TLS connection state is not supported
+in plugins.
 
 ## Plugin Registration
 An important consideration of Vault's plugin system is to ensure the plugin
@@ -70,7 +73,6 @@ $ vault write sys/plugins/catalog/myplugin-database-plugin \
 Success! Data written to: sys/plugins/catalog/myplugin-database-plugin
 ```
 
-
 ### Plugin Execution
 When a backend wants to run a plugin, it first looks up the plugin, by name, in
 the catalog. It then checks the executable's SHA256 sum against the one
@@ -79,6 +81,11 @@ the catalog, sending along the JWT formatted response wrapping token and mlock
 settings (like Vault, plugins support the use of mlock when available).
 
 # Plugin Development
+
+~> Advanced topic! Plugin development is a highly advanced topic in Vault, and
+is not required knowledge for day-to-day usage. If you don't plan on writing any
+plugins, we recommend not reading this section of the documentation.
+
 Because Vault communicates to plugins over a RPC interface, you can build and
 distribute a plugin for Vault without having to rebuild Vault itself. This makes
 it easy for you to build a Vault plugin for your organization's internal use,
@@ -89,10 +96,6 @@ In theory, because the plugin interface is HTTP, you could even develop a plugin
 using a completely different programming language! (Disclaimer, you would also
 have to re-implement the plugin API which is not a trivial amount of work.)
 
-~> Advanced topic! Plugin development is a highly advanced topic in Vault, and
-is not required knowledge for day-to-day usage. If you don't plan on writing any
-plugins, we recommend not reading this section of the documentation.
-
 Developing a plugin is simple. The only knowledge necessary to write
 a plugin is basic command-line skills and basic knowledge of the
 [Go programming language](http://golang.org).

website/source/guides/plugin-backends.html.md

@@ -0,0 +1,103 @@
+---
+layout: "guides"
+page_title: "Plugin Backends - Guides"
+sidebar_current: "guides-plugin-backends"
+description: |-
+  Learn how to build, register, and mount a custom plugin backend.
+---
+
+# Introduction
+
+Plugin backends utilize the [plugin system][plugin-system] to enable 
+third-party secret and auth backends to be mounted. 
+
+It is worth noting that even though [database backend][database-backend]
+operates under the same underlying plugin mechanism, it is slightly different
+in design than plugin backends demonstrated in this guide. The database backend 
+manages multiple plugins under the same backend mount point, whereas plugin
+backends are generic backends that function as either secret or auth backends. 
+
+This guide provides steps to build, register, and mount non-database external
+plugin backends.
+
+## Setting up Vault
+
+Set `plugin_directory` to the desired path in the Vault configuration file.
+The path should exist and have proper lockdown on access permissions.
+
+```
+$ cat vault-config.hcl
+...
+plugin_directory="/etc/vault/vault_plugins"
+...
+```
+
+## Build the Plugin Backend
+
+Build the custom backend binary, and move it to the `plugin_directory` path.
+In this guide, we will use `mock-plugin` that comes from Vault's 
+`logical/plugin/mock` package.
+
+```
+$ ls .
+main.go
+
+$ ls ..
+backend.go  backend_test.go  mock-plugin/  path_internal.go  path_kv.go
+
+$ go build -o mock-plugin main.go
+
+$ mv mock-plugin /etc/vault/vault_plugins
+```
+
+## Register the Plugin Into the Plugin Catalog
+
+Start the Vault server. Find out the sha256 sum of the compiled plugin binary,
+and use that to register the plugin into Vault's plugin catalog.
+
+```
+$ shasum -a 256 ~/code/tmp/vault_plugins/mock-plugin
+2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615  /etc/vault/vault_plugins/mock-plugin
+
+$ vault sys/plugins/catalog/mock-plugin sha_256=2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615 command=mock-plugin
+Success! Data written to: sys/plugins/catalog/mock-plugin
+```
+
+## Mount the Plugin
+
+```
+$ vault mount -path=mock -plugin-name=mock-plugin plugin
+Successfully mounted plugin 'mock-plugin' at 'mock'!
+
+$ vault mounts
+Path        Type       Accessor            Plugin       Default TTL  Max TTL  Force No Cache  Replication Behavior  Description
+cubbyhole/  cubbyhole  cubbyhole_80ef4e30  n/a          n/a          n/a      false           local                 per-token private secret storage
+mock/       plugin     plugin_10fc2cce     mock-plugin  system       system   false           replicated
+secret/     generic    generic_ef2a14ec    n/a          system       system   false           replicated            generic secret storage
+sys/        system     system_e3a4cccd     n/a          n/a          n/a      false           replicated            system endpoints used for control, policy and debugging
+```
+
+## Perform operations on the mount
+
+```
+$ vault write mock/kv/foo value=bar
+Key  	Value
+---  	-----
+value	bar
+```
+
+## Unmount the plugin
+
+```
+$ vault unmount mock
+Successfully unmounted 'mock' if it was mounted
+
+$ vault mounts
+Path        Type       Accessor            Plugin  Default TTL  Max TTL  Force No Cache  Replication Behavior  Description
+cubbyhole/  cubbyhole  cubbyhole_80ef4e30  n/a     n/a          n/a      false           local                 per-token private secret storage
+secret/     generic    generic_ef2a14ec    n/a     system       system   false           replicated            generic secret storage
+sys/        system     system_e3a4cccd     n/a     n/a          n/a      false           replicated            system endpoints used for control, policy and debugging
+```
+
+[plugin-system]: docs/internals/plugins.html
+[database-backend]: docs/secrets/databases/index.html

website/source/layouts/api.erb

@@ -179,6 +179,9 @@
           <li<%= sidebar_current("docs-http-system-mounts") %>>
             <a href="/api/system/mounts.html"><tt>/sys/mounts</tt></a>
           </li>
+          <li<%= sidebar_current("docs-http-system-plugins-backend-reload") %>>
+            <a href="/api/system/plugins-backend-reload.html"><tt>/sys/plugins/backend/reload</tt></a>
+          </li>
           <li<%= sidebar_current("docs-http-system-plugins-catalog") %>>
             <a href="/api/system/plugins-catalog.html"><tt>/sys/plugins/catalog</tt></a>
           </li>

website/source/layouts/guides.erb

@@ -17,6 +17,10 @@
         <a href="/guides/replication.html">Replication Setup &amp; Guidance</a>
       </li>
 
+      <li<%= sidebar_current("guides-plugin-backends") %>>
+        <a href="/guides/plugin-backends.html">Building Plugin Backends</a>
+      </li>
+
       <hr>
 
       <li<%= sidebar_current("guides-upgrading")%>>