add docs for external Enterprise plugins (#29738)

---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

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"
 }
 ```
 

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.

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
 

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
+[HashiCorp releases page](https://releases.hashicorp.com/) for the latest
-binaries.
+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/
 ```

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