Clarify api_addr related errors on VaultPluginTLSProvider (#3620)

* Mention api_addr on VaultPluginTLSProvider logs, update docs

* Clarify message and mention automatic api_address detection

* Change error message to use api_addr

* Change error messages to use api_addr

helper/pluginutil/tls.go

@@ -146,19 +146,19 @@ func VaultPluginTLSProvider(apiTLSConfig *api.TLSConfig) func() (*tls.Config, er
 
 		addrRaw := wt.Claims().Get("addr")
 		if addrRaw == nil {
-			return nil, errors.New("decoded token does not contain primary cluster address")
+			return nil, errors.New("decoded token does not contain the active node's api_addr")
 		}
 		vaultAddr, ok := addrRaw.(string)
 		if !ok {
-			return nil, errors.New("decoded token's address not valid")
+			return nil, errors.New("decoded token's api_addr not valid")
 		}
 		if vaultAddr == "" {
-			return nil, errors.New(`no address for the vault found`)
+			return nil, errors.New(`no vault api_addr found`)
 		}
 
 		// Sanity check the value
 		if _, err := url.Parse(vaultAddr); err != nil {
-			return nil, fmt.Errorf("error parsing the vault address: %s", err)
+			return nil, fmt.Errorf("error parsing the vault api_addr: %s", err)
 		}
 
 		// Unwrap the token

website/source/docs/configuration/index.html.md

@@ -121,9 +121,10 @@ to specify where the configuration is.
 
 The following parameters are used on backends that support [high availability][high-availability].
 
-- `api_addr` `(string: "")` - Specifies the address (full URL) to
-  advertise to other Vault servers in the cluster for client redirection. This
-  can also be provided via the environment variable `VAULT_API_ADDR`.
+- `api_addr` `(string: "")` - Specifies the address (full URL) to advertise to
+  other Vault servers in the cluster for client redirection. This value is also
+  used for [plugin backends][plugins]. This can also be provided via the
+  environment variable `VAULT_API_ADDR`.
 
 - `cluster_addr` `(string: "")` -  – Specifies the address to advertise to other
   Vault servers in the cluster for request forwarding. This can also be provided
@@ -141,3 +142,4 @@ The following parameters are used on backends that support [high availability][h
 [sealwrap]: /docs/enterprise/sealwrap/index.html
 [telemetry]: /docs/configuration/telemetry.html
 [high-availability]: /docs/concepts/ha.html
+[plugins]: /docs/plugin/index.html

website/source/docs/internals/plugins.html.md

@@ -32,6 +32,11 @@ plugin process' environment. This token is single use and has a short TTL. Once
 unwrapped, it provides the plugin with a uniquely generated TLS certificate and
 private key for it to use to talk to the original vault process.
 
+The [`api_addr`][api_addr] must be set in order for the plugin process 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.
+
 ~> Note: Reading the original connection's TLS connection state is not supported
 in plugins.
 
@@ -125,3 +130,5 @@ func main() {
 
 And that's basically it! You would just need to change MyPlugin to your actual
 plugin.
+
+[api_addr]: /docs/configuration/index.html#api_addr

website/source/docs/plugin/index.html.md

@@ -11,6 +11,11 @@ description: |-
 Plugin backends are the components in Vault that can be implemented separately from Vault's
 builtin backends. These backends can be either authentication or secret backends.
 
+The [`api_addr`][api_addr] must be set in order for the plugin process 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](https://www.vaultproject.io/docs/internals/plugins.html).
 
@@ -40,3 +45,5 @@ Unmounting a plugin backend is the identical to unmounting internal backends:
 ```
 $ vault unmount my-secrets
 ```
+
+[api_addr]: /docs/configuration/index.html#api_addr