• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Try Cloud(opens in new tab)
  • Sign up
Vault Home

Documentation

Skip to main contentOverview
  • What is Vault?
  • Use Cases

  • Browser Support
  • Installing Vault

    • Overview
    • Plugin Architecture
    • Plugin Development
    • Plugin Management
    • Plugin Portal
  • Vault Integration Program
  • Vault Interoperability Matrix
  • Troubleshoot






  • Glossary


  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Documentation
  4. Plugins
  5. Plugin Development
  • Vault
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x
  • v1.7.x
  • v1.6.x
  • v1.5.x
  • v1.4.x

ยป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.

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.

Note: Plugins should be prepared to handle multiple concurrent requests from Vault.

Serving A Plugin

Serving A Plugin with Multiplexing

Plugin multiplexing requires github.com/hashicorp/vault/sdk v0.5.4 or above.

The following code exhibits an example main package for a Vault plugin using the Vault SDK for a secrets engine or auth method:

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.ServeMultiplex(&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.

Plugin Backwards Compatibility with Vault

Let's take a closer look at a snippet from the above main package.

    err := plugin.ServeMultiplex(&plugin.ServeOpts{
        BackendFactoryFunc: myPlugin.Factory,
        TLSProviderFunc:    tlsProviderFunc,
    })

The call to plugin.ServeMultiplex ensures that the plugin will use Vault's plugin multiplexing feature. However, this plugin will not be multiplexed if it is run by a version of Vault that does not support multiplexing. Vault will simply fall back to a plugin version that it can run. Additionally, we set the TLSProviderFunc to ensure that our plugin is backwards compatible with versions of Vault that do not support automatic mutual TLS for secure plugin communication. If you are certain your plugin does not need backwards compatibility, this field can be omitted.

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

Other HashiCorp plugin development resources:

  • vault-auth-plugin-example
  • Custom Secrets Engines

Plugin Development - Resources - Community

See the Plugin Portal to find Community plugin examples/guides developed by community members. HashiCorp does not validate these for correctness.

Edit this page on GitHub

On this page

  1. Plugin Development
  2. Serving A Plugin
  3. Plugin Backwards Compatibility with Vault
  4. Building a Plugin from Source
  5. Plugin Development - Resources
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)