luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Docs: Implementing the plugin version interface (#19606)

This commit is contained in:
Tom Proctor 2023-03-20 17:43:31 +00:00 committed by GitHub
parent 4d10063cbd
commit 7fd394fc76
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 49 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
website/content/docs/plugins/plugin-development.mdx
View File

@ -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

23
website/content/docs/secrets/databases/custom.mdx
View File

@ -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

14
website/content/partials/plugin-versioning.mdx Normal file
View File

@ -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.