From 1e7c7b3062db601a4de6718375e4461819d2fffb Mon Sep 17 00:00:00 2001
From: hc-github-team-secure-vault-core
 <82990506+hc-github-team-secure-vault-core@users.noreply.github.com>
Date: Tue, 21 Mar 2023 08:53:33 -0400
Subject: [PATCH] backport of commit fd422cb49aff414da258d3ab3bfc193840c577c3
 (#19639)

Co-authored-by: Tom Proctor <tomhjp@users.noreply.github.com>
---
 .../docs/plugins/plugin-development.mdx       | 13 +++++++++++
 .../content/docs/secrets/databases/custom.mdx | 23 ++++++++++++++++++-
 .../content/partials/plugin-versioning.mdx    | 14 +++++++++++
 3 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 website/content/partials/plugin-versioning.mdx

diff --git a/website/content/docs/plugins/plugin-development.mdx b/website/content/docs/plugins/plugin-development.mdx
index 7b3c248335e5..bc1bd831d861 100644
--- a/website/content/docs/plugins/plugin-development.mdx
+++ b/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
diff --git a/website/content/docs/secrets/databases/custom.mdx b/website/content/docs/secrets/databases/custom.mdx
index cfe5fa6910dc..535a699f751a 100644
--- a/website/content/docs/secrets/databases/custom.mdx
+++ b/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
diff --git a/website/content/partials/plugin-versioning.mdx b/website/content/partials/plugin-versioning.mdx
new file mode 100644
index 000000000000..5859fcf5f50e
--- /dev/null
+++ b/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.
\ No newline at end of file