backport of commit fd422cb (#19639)

Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com>

website/content/docs/plugins/plugin-development.mdx

@@ -100,6 +100,19 @@ be omitted.
 
 [api_addr]: /vault/docs/configuration#api_addr
 
+## Leveraging plugin versioning
+
+@include 'plugin-versioning.mdx'
+
+Auth and secrets plugins based on `framework.Backend` from the SDK should set the
+[`RunningVersion`](https://github.com/hashicorp/vault/blob/sdk/v0.6.0/sdk/framework/backend.go#L95-L96)
+variable, and the framework will implement the version interface.
+
+Database plugins have a smaller API than `framework.Backend` exposes, and should
+instead implement the
+[`PluginVersioner`](https://github.com/hashicorp/vault/blob/sdk/v0.6.0/sdk/logical/logical.go#L150-L154)
+interface directly.
+
 ## Building a Plugin from Source
 
 To build a plugin from source, first navigate to the location holding the

website/content/docs/secrets/databases/custom.mdx

@@ -209,7 +209,7 @@ build with [gox](https://github.com/mitchellh/gox) for cross platform builds.
 To use your plugin with the database secrets engine you need to place the binary in the
 plugin directory as specified in the [plugin internals](/vault/docs/plugins) docs.
 
-You should now be able to register your plugin into the vault catalog. To do
+You should now be able to register your plugin into the Vault catalog. To do
 this your token will need sudo permissions.
 
 ```shell-session
@@ -228,6 +228,27 @@ $ vault write database/config/mydatabase \
     myplugins_connection_details="..."
 ```
 
+## Updating database plugins to leverage plugin versioning
+
+@include 'plugin-versioning.mdx'
+
+In addition to the `Database` interface above, database plugins can then also
+implement the
+[`PluginVersioner`](https://github.com/hashicorp/vault/blob/sdk/v0.6.0/sdk/logical/logical.go#L150-L154)
+interface:
+
+```go
+// PluginVersioner is an optional interface to return version info.
+type PluginVersioner interface {
+	// PluginVersion returns the version for the backend
+	PluginVersion() PluginVersion
+}
+
+type PluginVersion struct {
+	Version string
+}
+```
+
 ## Upgrading database plugins to leverage plugin multiplexing
 
 ### Background

website/content/partials/plugin-versioning.mdx

@@ -0,0 +1,14 @@
+Plugins can optionally self-report their own semantic version. For plugins that
+do so, Vault will automatically populate the plugin's version in the catalog
+without requiring the user to provide it. If users do provide a version during
+registration, Vault will error if the version provided does not match what the
+plugin reports. Plugins that report a non-empty version _must_ report a valid
+[Semantic Version](https://semver.org/) with a leading 'v' added or registration
+will fail, e.g. `v1.0.0` or `v2.3.2-beta`.
+
+Plugins that want to opt into this behavior can implement the version interface.
+However, it is not a prerequisite; users can still provide a version during
+registration if the plugin does not implement the version interface.
+
+To implement the version interface, plugins should first upgrade the Vault SDK
+package to at least v0.6.0.