docs: add section on upgrading plugins (#7984)

* docs: add section on upgrading plugins

* docs: move plugin upgrade to its own guides page

* docs: reword step 4

* docs: add page to sidebar

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

@@ -4,7 +4,7 @@ page_title: "Custom Plugin Backends"
 sidebar_title: "Plugin Backends"
 sidebar_current: "docs-plugin"
 description: |-
-  Plugin backends are mountable backends that are implemented unsing Vault's plugin system.
+  Plugin backends are mountable backends that are implemented using Vault's plugin system.
 ---
 
 # Custom Plugin Backends
@@ -46,4 +46,11 @@ Disabling a plugin backend is the identical to disabling internal secrets engine
 $ vault secrets disable my-secrets
 ```
 
+# Upgrading Plugins
+
+Upgrade instructions can be found in the [Upgrading Plugins - Guides][upgrading_plugins]
+page.
+
+
 [api_addr]: /docs/configuration/index.html#api_addr
+[upgrading_plugins]: /docs/upgrading/plugins.html

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

@@ -0,0 +1,38 @@
+---
+layout: "docs"
+page_title: "Upgrading Plugins - Guides"
+sidebar_title: "Upgrade Plugins"
+sidebar_current: "docs-upgrading-plugins"
+description: |-
+  These are general upgrade instructions for Vault plugins.
+---
+
+# Upgrading Vault Plugins
+
+The following procedure details steps for upgrading a plugin that has already
+been registered to the catalog on a running server. This procedure is applicable
+to secret, auth, and database plugins.
+
+## Upgrade Procedure
+
+Vault executes plugin binaries when they are configured and roles are established
+around them. The binary cannot be modified or replaced while running, so
+upgrades cannot be performed by simply swapping the binary and updating the hash
+in the plugin catalog.
+
+Instead, you can restart or reload a plugin with the
+`sys/plugins/reload/backend` [API][plugin_reload_api]. Follow these steps to
+replace or upgrade a Vault plugin binary:
+
+1. Register plugin_v1 to the catalog
+2. Mount the plugin backend
+3. Register plugin_v2 to the catalog under the same plugin name, but with
+updated command to run plugin_v2 and updated sha256 of plugin_v2
+4. Trigger a plugin reload with `sys/plugins/reload/backend` to reload all
+mounted backends using that plugin or a subset of the mounts using that plugin
+with either the `plugin` or `mounts` parameter respectively.
+
+Until step 4, the mount will still use plugin_v1, and when the reload is
+triggered, Vault will kill plugin_v1’s process and start a plugin_v2 process.
+
+[plugin_reload_api]: /api/system/plugins-reload-backend.html

website/source/layouts/docs.erb

@@ -356,6 +356,7 @@
           {
             category: 'upgrading',
             content: [
+              'plugins',
               'upgrade-to-0.5.0',
               'upgrade-to-0.5.1',
               'upgrade-to-0.6.0',