mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-15 02:57:04 +02:00
132 lines
4.3 KiB
Plaintext
132 lines
4.3 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Plugin Management
|
|
description: >-
|
|
External Plugins are mountable backends that are implemented using Vault's
|
|
plugin system.
|
|
---
|
|
|
|
# Plugin management
|
|
|
|
External plugins are the components in Vault that can be implemented separately
|
|
from Vault's built-in plugins. These plugins can be either authentication or
|
|
secrets engines.
|
|
|
|
The [`api_addr`][api_addr] must be set in order for the plugin process to
|
|
establish communication with the Vault server during mount time. If the storage
|
|
backend has HA enabled and supports automatic host address detection (e.g.
|
|
Consul), Vault will automatically attempt to determine the `api_addr` as well.
|
|
|
|
Detailed information regarding the plugin system can be found in the
|
|
[internals documentation](/vault/docs/plugins).
|
|
|
|
## Registering external plugins
|
|
|
|
Before an external plugin can be mounted, it needs to be
|
|
[registered](/vault/docs/plugins/plugin-architecture#plugin-registration) in the
|
|
plugin catalog to ensure the plugin invoked by Vault is authentic and maintains
|
|
integrity:
|
|
|
|
```shell-session
|
|
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
|
|
secret \ # type
|
|
passthrough-plugin
|
|
|
|
Success! Registered plugin: passthrough-plugin
|
|
```
|
|
|
|
## Enabling/Disabling external plugins
|
|
|
|
After the plugin is registered, it can be mounted by specifying the registered
|
|
plugin name:
|
|
|
|
```shell-session
|
|
$ vault secrets enable -path=my-secrets passthrough-plugin
|
|
Success! Enabled the passthrough-plugin secrets engine at: my-secrets/
|
|
```
|
|
|
|
Listing secrets engines will display secrets engines that are mounted as
|
|
plugins:
|
|
|
|
```shell-session
|
|
$ vault secrets list
|
|
Path Type Accessor Plugin Default TTL Max TTL Force No Cache Replication Behavior Description
|
|
my-secrets/ plugin plugin_deb84140 passthrough-plugin system system false replicated
|
|
```
|
|
|
|
Disabling an external plugins is identical to disabling a built-in plugin:
|
|
|
|
```shell-session
|
|
$ vault secrets disable my-secrets
|
|
```
|
|
|
|
## Upgrading plugins
|
|
|
|
Upgrade instructions can be found in the [Upgrading Plugins - Guides][upgrading_plugins]
|
|
page.
|
|
|
|
[api_addr]: /vault/docs/configuration#api_addr
|
|
[upgrading_plugins]: /vault/docs/upgrading/plugins
|
|
|
|
## Plugin environment variables
|
|
|
|
An advantage for external plugins over builtin plugins is they can specify
|
|
additional environment variables because they are run in their own process.
|
|
|
|
-> Vault 1.16.0 changed the precedence given to plugin-specific environment
|
|
variables so they take priority over Vault's environment. See full details in
|
|
the [upgrade notes](/vault/docs/upgrading/upgrade-to-1.16.x).
|
|
|
|
Use the `-env` flag once per environment variable that a plugin should be
|
|
started with:
|
|
|
|
```shell-session
|
|
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
|
|
-env REGION=eu \
|
|
-env TOKEN_FILE=/var/run/token \
|
|
secret \ # type
|
|
passthrough-plugin
|
|
|
|
Success! Registered plugin: passthrough-plugin
|
|
```
|
|
|
|
### Plugin-specific HTTP proxy settings
|
|
|
|
Many tools and libraries automatically consume `HTTP_PROXY`, `HTTPS_PROXY`, and
|
|
`NO_PROXY` environment variables to configure HTTP proxy settings, including the
|
|
Go standard library's default HTTP client. You can use these environment
|
|
variables to configure different network proxies for different plugins:
|
|
|
|
-> You must be using an external plugin to take advantage of custom environment
|
|
variables. If you are using a builtin plugin, you can still download and register
|
|
an external version of it in order to use this workflow. Check the
|
|
[releases](https://releases.hashicorp.com/) page for the latest prebuilt plugin
|
|
binaries.
|
|
|
|
```shell-session
|
|
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
|
|
-env HTTP_PROXY=eu.example.com \
|
|
auth \
|
|
jwt-eu
|
|
|
|
Success! Registered plugin: jwt-eu
|
|
|
|
$ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
|
|
-env HTTP_PROXY=us.example.com \
|
|
auth \
|
|
jwt-us
|
|
|
|
Success! Registered plugin: jwt-us
|
|
```
|
|
|
|
You can then enable each plugin on its own path, and configure clients that
|
|
should be associated with one or the other appropriately:
|
|
|
|
```shell-session
|
|
$ vault auth enable jwt-eu
|
|
Success! Enabled the jwt-eu auth method at: auth/jwt-eu/
|
|
|
|
$ vault auth enable jwt-us
|
|
Success! Enabled the jwt-us auth method at: auth/jwt-us/
|
|
```
|