add docs for external Enterprise plugins (#29738)

--------- Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
2025-10-28 17:22:41 +00:00 · 2025-02-27 16:00:23 -08:00
parent 1091474e4d
commit 6d9543158d
5 changed files with 123 additions and 16 deletions
--- 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: <required>)` – 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: <required>)` – 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: <required>)` – This is the SHA256 sum of the plugin's
+- `sha256` `(string: <required>)` – 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: <required>)` - 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"
 }
 ```

--- 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: <required>)` - 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.
--- 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

--- 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=<SHA256 Hex value of the plugin binary> \
    secret \                  # type
@@ -34,6 +37,37 @@ $ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
 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 of the plugin> # 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=<SHA256 Hex value of the plugin binary> \
    -env HTTP_PROXY=eu.example.com \
@@ -118,6 +153,16 @@ $ vault plugin register -sha256=<SHA256 Hex value of the plugin binary> \
 Success! Registered plugin: jwt-us
 ```

+#### Enterprise plugins
+```shell-session
+$ vault plugin register -version=<version of the plugin> \
+    -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/
 ```
--- 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