mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-19 05:31:10 +02:00
a43e292424
* conversion stage 1 * correct image paths * add sidebar title to frontmatter * docs/concepts and docs/internals * configuration docs and multi-level nav corrections * commands docs, index file corrections, small item nav correction * secrets converted * auth * add enterprise and agent docs * add extra dividers * secret section, wip * correct sidebar nav title in front matter for apu section, start working on api items * auth and backend, a couple directory structure fixes * remove old docs * intro side nav converted * reset sidebar styles, add hashi-global-styles * basic styling for nav sidebar * folder collapse functionality * patch up border length on last list item * wip restructure for content component * taking middleman hacking to the extreme, but its working * small css fix * add new mega nav * fix a small mistake from the rebase * fix a content resolution issue with middleman * title a couple missing docs pages * update deps, remove temporary markup * community page * footer to layout, community page css adjustments * wip downloads page * deps updated, downloads page ready * fix community page * homepage progress * add components, adjust spacing * docs and api landing pages * a bunch of fixes, add docs and api landing pages * update deps, add deploy scripts * add readme note * update deploy command * overview page, index title * Update doc fields Note this still requires the link fields to be populated -- this is solely related to copy on the description fields * Update api_basic_categories.yml Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages. * Add bottom hero, adjust CSS, responsive friendly * Add mega nav title * homepage adjustments, asset boosts * small fixes * docs page styling fixes * meganav title * some category link corrections * Update API categories page updated to reflect the second level headings for api categories * Update docs_detailed_categories.yml Updated to represent the existing docs structure * Update docs_detailed_categories.yml * docs page data fix, extra operator page remove * api data fix * fix makefile * update deps, add product subnav to docs and api landing pages * Rearrange non-hands-on guides to _docs_ Since there is no place for these on learn.hashicorp, we'll put them under _docs_. * WIP Redirects for guides to docs * content and component updates * font weight hotfix, redirects * fix guides and intro sidenavs * fix some redirects * small style tweaks * Redirects to learn and internally to docs * Remove redirect to `/vault` * Remove `.html` from destination on redirects * fix incorrect index redirect * final touchups * address feedback from michell for makefile and product downloads
119 lines
3.4 KiB
Markdown
119 lines
3.4 KiB
Markdown
---
|
|
layout: "guides"
|
|
page_title: "Plugin Backends - Guides"
|
|
sidebar_title: "Building Plugin Backends"
|
|
sidebar_current: "guides-operations-plugin-backends"
|
|
description: |-
|
|
Learn how to build, register, and mount a custom plugin backend.
|
|
---
|
|
|
|
# Introduction
|
|
|
|
Plugin backends utilize the [plugin system][plugin-system] to enable third-party
|
|
secrets engines and auth methods.
|
|
|
|
It is worth noting that even though [database secrets engines][database-backend]
|
|
operate under the same underlying plugin mechanism, they are slightly different
|
|
in design than plugin backends demonstrated in this guide. The database secrets
|
|
engine manages multiple plugins under the same backend mount point, whereas
|
|
plugin backends are kv backends that function as either secret or auth methods.
|
|
|
|
This guide provides steps to build, register, and mount non-database external
|
|
plugin backends.
|
|
|
|
## Setup Vault
|
|
|
|
Set `plugin_directory` to the desired path in the Vault configuration file.
|
|
The path should exist and have proper lockdown on access permissions.
|
|
|
|
```hcl
|
|
# /etc/vault/config.d/plugins.hcl
|
|
plugin_directory = "/etc/vault/vault_plugins"
|
|
```
|
|
|
|
If the Vault server is already running, you will need to tell it to reload its
|
|
configuration by sending SIGHUP. If you stop and start the Vault server, you
|
|
will need to unseal it again.
|
|
|
|
## Compile Plugin
|
|
|
|
Build the custom binary, and move it inside the `plugin_directory` path
|
|
configured above. This guide uses `mock-plugin` that comes from Vault's
|
|
[`logical/plugin/mock`](https://github.com/hashicorp/vault/tree/master/logical/plugin/mock/mock-plugin) package.
|
|
|
|
Download the source (you would probably use your own plugin):
|
|
|
|
```sh
|
|
$ go get -f -u -d github.com/hashicorp/vault
|
|
# ...
|
|
$ cd $GOPATH/src/github.com/hashicorp/vault/logical/plugin/mock/mock-plugin
|
|
```
|
|
|
|
Compile the plugin:
|
|
|
|
```sh
|
|
$ go build -o my-mock-plugin
|
|
```
|
|
|
|
Put the plugin in the directory:
|
|
|
|
```sh
|
|
$ mv my-mock-plugin /etc/vault/vault_plugins
|
|
```
|
|
|
|
## Register in Plugin Catalog
|
|
|
|
Calculate the SHA256 sum of the compiled plugin binary, and use that to register
|
|
the plugin into Vault's plugin catalog:
|
|
|
|
```sh
|
|
$ shasum -a 256 /etc/vault/vault_plugins/my-mock-plugin
|
|
2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615 /etc/vault/vault_plugins/my-mock-plugin
|
|
|
|
$ vault write sys/plugins/catalog/my-mock-plugin \
|
|
sha256=2c071aafa1b30897e60b79643e77592cb9d1e8f803025d44a7f9bbfa4779d615 \
|
|
command=my-mock-plugin
|
|
Success! Data written to: sys/plugins/catalog/my-mock-plugin
|
|
```
|
|
|
|
## Enable Plugin
|
|
|
|
Enabling the plugin varies depending on if it's a secrets engine or auth method:
|
|
|
|
```sh
|
|
$ vault secrets enable -path=my-secrets-plugin -plugin-name=my-mock-plugin plugin
|
|
Success! Enabled the my-mock-plugin plugin at: my-secrets-plugin/
|
|
```
|
|
|
|
If you try to mount this particular plugin as an auth method instead of a
|
|
secrets engine, you will get an error:
|
|
|
|
```sh
|
|
$ vault auth enable -path=my-auth-plugin -plugin-name=my-mock-plugin plugin
|
|
# ...
|
|
* cannot mount 'my-mock-plugin' of type 'secret' as an auth method
|
|
```
|
|
|
|
## Perform Operations
|
|
|
|
Each plugin responds to read, write, list, and delete as its own behavior.
|
|
|
|
```text
|
|
$ vault write my-secrets-plugin/kv/foo value=bar
|
|
Key Value
|
|
--- -----
|
|
value bar
|
|
```
|
|
|
|
## Disable Plugin
|
|
|
|
When you are done using the plugin, disable it.
|
|
|
|
```text
|
|
$ vault secrets disable my-secrets-plugin
|
|
Success! Disabled the secrets engine (if it existed) at: my-secrets-plugin/
|
|
```
|
|
|
|
[plugin-system]: /docs/internals/plugins.html
|
|
[database-backend]: /docs/secrets/databases/index.html
|