Docs: Plugin env priority updates for 1.16.0 (#25580)

website/content/docs/plugins/plugin-management.mdx

@@ -67,3 +67,65 @@ 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/
+```

website/content/docs/upgrading/upgrade-to-1.16.x.mdx

@@ -12,6 +12,32 @@ The Vault 1.16.x upgrade guide contains information on deprecations, important
 or breaking changes, and remediation recommendations for anyone upgrading from
 Vault 1.15. **Please read carefully**.
 
+## Plugin environment variables
+
+Starting in 1.16.0, plugin-specific environment variables take precedence when
+they conflict with the main Vault process' environment.
+
+For example, if an external plugin is registered with `SOURCE=child` in the
+[env](/vault/api-docs/system/plugins-catalog#env) parameter, but the main Vault
+process has `SOURCE=parent` in its environment, versions prior to 1.16.0 will
+start the plugin process with `SOURCE=parent`. 1.16.0+ will start the plugin
+process with `SOURCE=child`.
+
+For any users relying on the old behavior, you can opt out of this change by setting
+`VAULT_PLUGIN_USE_LEGACY_ENV_LAYERING=true` for the main Vault process. If this
+flag is detected, Vault will continue to prioritize Vault process environment
+variables when there is a conflict. Additionally, during unseal Vault will enumerate
+all plugins in the catalog and print a warning for any plugins whose environment
+conflicts with the main process. If the flag is set and you see an informational
+log that there are no conflicts, the flag can safely be removed.
+
+Note that containerized plugins do not inherit any environment variables from
+the main Vault process, so are unaffected. Builtin plugins and external plugins
+that do not specify additional environment variables are also unaffected.
+
+See [plugin management](/vault/docs/plugins/plugin-management) for more details
+on plugin environment variables.
+
 ## Known issues and workarounds
 
 @include 'known-issues/1_16-default-policy-needs-to-be-updated.mdx'