15e693bf91
* docs/multiplexing: overhaul plugin documentation * update nav data * remove dupe nav data * add external plugin section to index * move custom plugin backends under internals/plugins * remove ref to moved page * revert moving custom plugin backends * add building plugins from source section to plug dev * add mux section to plugin arch * add mux section to custom plugin page * reorder custom database page * use 'external plugin' where appropriate * add link to plugin multiplexing * fix example serve multiplex func call * address review comments * address review comments * Minor format updates (#14590) * mv Plugins to top-level; update upgrading plugins * update links after changing paths * add section on external plugin scaling characteristics * add updates on plugin registration in plugin management page * add plugin learn resource * be more explicit about mux upgrade steps; add notes on when to avoid db muxing * add plugin upgrade built-in section * add caveats to built-in plugin upgrade * improvements to built-in plugin override * formatting, add redirects, correct multiplexing use case * fix go-plugin link * Apply suggestions from code review Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com> * remove single item list; add link to Database interface Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com> Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
92 lines
3 KiB
Plaintext
92 lines
3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Plugin Development
|
|
description: Learn about Vault plugin development.
|
|
---
|
|
|
|
# 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,
|
|
for a proprietary API that you don't want to open source, or to prototype
|
|
something before contributing it back to the main project.
|
|
|
|
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.)
|
|
|
|
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).
|
|
|
|
Your plugin implementation needs to satisfy the interface for the plugin
|
|
type you want to build. You can find these definitions in the docs for the
|
|
backend running the plugin.
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"os"
|
|
|
|
myPlugin "your/plugin/import/path"
|
|
"github.com/hashicorp/vault/api"
|
|
"github.com/hashicorp/vault/sdk/plugin"
|
|
)
|
|
|
|
func main() {
|
|
apiClientMeta := &api.PluginAPIClientMeta{}
|
|
flags := apiClientMeta.FlagSet()
|
|
flags.Parse(os.Args[1:])
|
|
|
|
tlsConfig := apiClientMeta.GetTLSConfig()
|
|
tlsProviderFunc := api.VaultPluginTLSProvider(tlsConfig)
|
|
|
|
err := plugin.Serve(&plugin.ServeOpts{
|
|
BackendFactoryFunc: myPlugin.Factory,
|
|
TLSProviderFunc: tlsProviderFunc,
|
|
})
|
|
if err != nil {
|
|
logger := hclog.New(&hclog.LoggerOptions{})
|
|
|
|
logger.Error("plugin shutting down", "error", err)
|
|
os.Exit(1)
|
|
}
|
|
}
|
|
```
|
|
|
|
And that's basically it! You would just need to change `myPlugin` to your actual
|
|
plugin.
|
|
|
|
[api_addr]: /docs/configuration#api_addr
|
|
|
|
## Building a Plugin from Source
|
|
|
|
To build a plugin from source, first navigate to the location holding the
|
|
desired plugin version. Next, run `go build` to obtain a new binary for the
|
|
plugin. Finally,
|
|
[register](/docs/plugins/plugin-architecture#plugin-registration) the
|
|
plugin and enable it.
|
|
|
|
## Plugin Development - Resources
|
|
|
|
For more information on how to register and enable your plugin, refer to the
|
|
[Building Plugin Backends](https://learn.hashicorp.com/vault/developer/plugin-backends)
|
|
tutorial.
|
|
|
|
Other HashiCorp plugin development resources:
|
|
|
|
* [vault-auth-plugin-example](https://github.com/hashicorp/vault-auth-plugin-example)
|
|
* [Custom Secrets Engines](https://learn.hashicorp.com/collections/vault/custom-secrets-engine)
|
|
|
|
### Plugin Development - Resources - Community
|
|
|
|
See the [Plugin Portal](/docs/plugins/plugin-portal#community) to find
|
|
Community plugin examples/guides developed by community members. HashiCorp does
|
|
not validate these for correctness.
|