diff --git a/website/content/api-docs/system/plugins-catalog.mdx b/website/content/api-docs/system/plugins-catalog.mdx index c2f912c920..86e495b347 100644 --- a/website/content/api-docs/system/plugins-catalog.mdx +++ b/website/content/api-docs/system/plugins-catalog.mdx @@ -142,7 +142,8 @@ supplied name. - `name` `(string: )` – Specifies the name for this plugin. The name is what is used to look up plugins in the catalog. This is part of the request - URL. + URL. Enterprise plugin names must match the name listed on the + [HashiCorp releases page](https://releases.hashicorp.com/) - `type` `(string: )` – Specifies the type of this plugin. May be "auth", "database", or "secret". @@ -157,13 +158,15 @@ supplied name. - `version` `(string: "")` - Specifies the semantic version of the plugin. Used as the tag when specifying `oci_image`, but with any leading 'v' trimmed. -- `sha256` `(string: )` – This is the SHA256 sum of the plugin's +- `sha256` `(string: )` – The SHA256 sum of a Community plugin binary or the OCI image. Before a plugin is run, its SHA will be checked against this value. - If they do not match the plugin can not be run. + If the actual SHA of the plugin binary and the SHA provided in `sha256` do not match, Vault will not run the plugin. The `sha256` parameter is only required for Community plugins. Enterprise plugins do not require SHA confirmation. - `command` `(string: )` - Specifies the command used to execute the plugin. This is relative to the plugin directory. e.g. `"myplugin"`, or if `oci_image` is also specified, it is relative to the image's working directory. + The `command` parameter is only required for Community plugins as + the run command is known for Enterprise plugins. - `args` `(array: [])` – Specifies the arguments used to execute the plugin. If the arguments are provided here, the `command` parameter should only contain @@ -175,10 +178,23 @@ supplied name. ### Sample payload +#### Community plugins + ```json { "sha256": "d130b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961e9", - "command": "mysql-database-plugin" + "command": "mysql-database-plugin", + "type": "database" +} +``` + +#### Enterprise plugins + +```json +{ + "version": "0.16.0+ent", + "name": "vault-plugin-secrets-keymgmt", + "type": "secret" } ``` diff --git a/website/content/docs/commands/plugin/register.mdx b/website/content/docs/commands/plugin/register.mdx index 7750ae60b6..668e1b7c28 100644 --- a/website/content/docs/commands/plugin/register.mdx +++ b/website/content/docs/commands/plugin/register.mdx @@ -13,7 +13,7 @@ The plugin's type of "auth", "database", or "secret" must be included. ## Examples -Register a plugin: +Register a Community or custom plugin: ```shell-session $ vault plugin register \ @@ -22,7 +22,24 @@ $ vault plugin register \ Success! Registered plugin: my-custom-plugin ``` -Register a plugin with custom args: +Register an Enterprise plugin: + +-> **Note:** See [Plugin managment for Enterprise plugins](/vault/docs/plugins/plugin-management#enterprise-plugins) +for details on Vault Enterprise compatible versions. + +Before registering Key Management secrets engine v0.16.0+ent for the linux/amd64 system that runs Vault Enterprise, +`vault-plugin-secrets-keymgmt_v0.16.0+ent_linux_amd64.zip` needs to be downloaded from +https://releases.hashicorp.com/vault-plugin-secrets-keymgmt and placed in the plugin directory. + +```shell-session +$ vault plugin register + -version=0.16.0+ent \ # version must match the plugin version on the releases page + secret \ + vault-plugin-secrets-keymgmt # name must match the plugin name on the releases page +Success! Registered plugin: vault-plugin-secrets-keymgmt +``` + +Register a Community or custom plugin with custom args: ```shell-session $ vault plugin register \ @@ -31,6 +48,16 @@ $ vault plugin register \ auth my-custom-plugin ``` +Register an Enterprise plugin with custom args: + +```shell-session +$ vault plugin register + -version=0.16.0+ent \ # version must match the plugin version on the releases page + -args=--with-glibc,--with-curl-bindings \ + secret \ + vault-plugin-secrets-keymgmt # name must match the plugin name on the releases page +``` + ## Usage The following flags are available in addition to the [standard set of @@ -45,7 +72,8 @@ flags](/vault/docs/commands) included on all commands. ### Command options - `-sha256` `(string: )` - SHA256 of the plugin binary or the OCI image - provided. This is required for all plugins. + provided. This is required for all Community plugins. + If the plugin is Enterprise, the value is not required. - `-args` `([]string: [])` - Argument to pass to the plugin when starting. This flag can be specified multiple times to specify multiple args. diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/plugins/index.mdx index 66c2d57f26..c8a206d755 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/plugins/index.mdx @@ -32,12 +32,6 @@ and can be used without any prerequisite steps. External plugins are not shipped with Vault and require additional operator intervention to run. -To run an external plugin, a binary or container image of the plugin is required. Plugin -binaries can be obtained from [releases.hashicorp.com](https://releases.hashicorp.com/) -or they can be [built from source](/vault/docs/plugins/plugin-development#building-a-plugin-from-source). -Containerized plugins are not yet available from a registry and must currently -be built. - Vault's external plugins are completely separate, standalone applications that Vault executes and communicates with over RPC. Each time a Vault secret engine, auth method, or database plugin is mounted, a new process or container is spawned. However, @@ -46,7 +40,24 @@ to improve performance. Plugin multiplexing allows plugin instances to be reused across all mounts of a given type. -> **NOTE:** See the [Vault Integrations](/vault/integrations) page to find a -curated collection of official, partner, and community Vault plugins. +curated collection of official, partner, and community Vault plugins. + +### Community plugins + +To run an external Community plugin, a binary or container image of the plugin is required. +Plugin binaries can be obtained from the [HashiCorp releases page](https://releases.hashicorp.com/) +or they can be [built from source](/vault/docs/plugins/plugin-development#building-a-plugin-from-source). +Some containerized plugins can be obtained from [HashiCorp Docker Registry](https://hub.docker.com/u/hashicorp) +or [HashiCorp AWS Elastic Container Registry (ECR)](https://gallery.ecr.aws/hashicorp). +Containerized plugins can also be built. + +### Enterprise plugins + +@include 'alerts/enterprise-and-hcp.mdx' + +To run an external Enterprise plugin, a `.zip` plugin artifact is required. +Enterprise plugin artifacts can be obtained from the +[HashiCorp releases page](https://releases.hashicorp.com/). ## Plugin versioning diff --git a/website/content/docs/plugins/plugin-management.mdx b/website/content/docs/plugins/plugin-management.mdx index f7df7ea2fe..fe149f01ab 100644 --- a/website/content/docs/plugins/plugin-management.mdx +++ b/website/content/docs/plugins/plugin-management.mdx @@ -5,6 +5,7 @@ description: >- Learn how to manage external plugins that are implemented using Vault's plugin system. --- + # Plugin management External plugins are the components in Vault that can be implemented separately @@ -26,6 +27,8 @@ Before an external plugin can be mounted, it needs to be plugin catalog to ensure the plugin invoked by Vault is authentic and maintains integrity: +### Community plugins + ```shell-session $ vault plugin register -sha256= \ secret \ # type @@ -34,6 +37,37 @@ $ vault plugin register -sha256= \ Success! Registered plugin: passthrough-plugin ``` +### Enterprise plugins + +@include 'alerts/enterprise-and-hcp.mdx' + +#### Compatible Vault Enterprise versions +- 1.16.16+ +- 1.17.12+ +- 1.18.5+ +- 1.19.0+ + +Before registering an enterprise plugin, ensure that the plugin artifact +compatible with the system that runs Vault Enterprise is downloaded from +[HashiCorp releases page](https://releases.hashicorp.com/) and placed +in the plugin directory. + +~> Note: Enterprise plugins artifacts should not be unzipped or modified +in any way. Vault Enterprise will verify the plugin's integrity +and compatibility and unzip during the registration process. + +```shell-session +$ vault plugin register + -version= # version must match the plugin version on the releases page + secret \ # type + vault-plugin-secrets-keymgmt # name must match the plugin name on the releases page + +Success! Registered plugin: vault-plugin-secrets-keymgmt +``` + +See [plugin register](/vault/docs/commands/plugin/register) for more details on +how to register Enterprise plugins. + ## Enabling/Disabling external plugins After the plugin is registered, it can be mounted by specifying the registered @@ -99,9 +133,10 @@ 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. +[HashiCorp releases page](https://releases.hashicorp.com/) for the latest +prebuilt plugin binaries. +#### Community plugins ```shell-session $ vault plugin register -sha256= \ -env HTTP_PROXY=eu.example.com \ @@ -118,6 +153,16 @@ $ vault plugin register -sha256= \ Success! Registered plugin: jwt-us ``` +#### Enterprise plugins +```shell-session +$ vault plugin register -version= \ + -env HTTP_PROXY=example.com \ + secret \ + vault-plugin-secrets-keymgmt + +Success! Registered plugin: vault-plugin-secrets-keymgmt +``` + You can then enable each plugin on its own path, and configure clients that should be associated with one or the other appropriately: @@ -127,4 +172,7 @@ 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/ + +$ vault secrets enable vault-plugin-secrets-keymgmt +Success! Enabled the vault-plugin-secrets-keymgmt secrets engine at: vault-plugin-secrets-keymgmt/ ``` diff --git a/website/content/docs/secrets/key-management/index.mdx b/website/content/docs/secrets/key-management/index.mdx index 1835186767..a35371b6ac 100644 --- a/website/content/docs/secrets/key-management/index.mdx +++ b/website/content/docs/secrets/key-management/index.mdx @@ -26,6 +26,10 @@ recovery means for the complete lifecycle of the key in the KMS provider. Key material will always be securely transferred in accordance with the [key import specification](#kms-providers) of the supported KMS providers. +-> **Note:** Key Management secrets engine can be run as an external plugin. +See [Plugin managment for Enterprise plugins](/vault/docs/plugins/plugin-management#enterprise-plugins) +for details on Vault Enterprise compatible versions and how to register Enterprise plugins. + ## Setup Most secrets engines must be configured in advance before they can perform their