Use Vault Agent as an API proxy

Deprecation announced

Deprecated features are functional but marked for eventual removal or replacement. Refer to the deprecation announcements page for migration details and information on our deprecation process.

Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy for Vault's API.

Use Vault Proxy for static secret caching

Static secret caching (KVv1 and KVv2) with API proxy minimizes the number of requests forwarded to Vault. Vault Agent does not support static secret caching with API proxy. We recommend using Vault Proxy for API Proxy related workflows.

Functionality

The listener stanza for Vault Agent configures a listener for Vault Agent. If its role is not set to metrics_only, it will act as a proxy for the Vault server that has been configured in the vault stanza of Vault Agent. This enables access to the Vault API from the Agent API, and can be configured to optionally allow or force the automatic use of the Auto-Auth token for these requests, as described below.

If a listener has been configured alongside a cache stanza, the API Proxy will first attempt to utilize the cache subsystem for qualifying requests, before forwarding the request to Vault. See the caching docs for more information on caching.

Using Auto-Auth token

Vault Agent allows for easy authentication to Vault in a wide variety of environments using Auto-Auth. By setting the use_auto_auth_token (see below) configuration, clients will not be required to provide a Vault token to the requests made to the Agent. When this configuration is set, if the request doesn't already bear a token, then the auto-auth token will be used to forward the request to the Vault server. This configuration will be overridden if the request already has a token attached, in which case, the token present in the request will be used to forward the request to the Vault server.

Forcing Auto-Auth token

Vault Agent can be configured to force the use of the auto-auth token by using the value force for the use_auto_auth_token option. This configuration overrides the default behavior described above in Using Auto-Auth Token, and instead ignores any existing Vault token in the request and instead uses the auto-auth token.

Configuration (`api_proxy`)

The top level api_proxy block has the following configuration entries:

use_auto_auth_token (bool/string: false) - If set, the requests made to Agent without a Vault token will be forwarded to the Vault server with the auto-auth token attached. If the requests already bear a token, this configuration will be overridden and the token in the request will be used to forward the request to the Vault server. If set to "force" Agent will use the auto-auth token, overwriting the attached Vault token if set.

The following two api_proxy options are only useful when making requests to a Vault Enterprise cluster, and are documented as part of its Eventual Consistency page.

enforce_consistency (string: "never") - Set to one of "always" or "never".
when_inconsistent (string: optional) - Set to one of "fail", "retry", or "forward".

Example configuration

Here is an example of a listener configuration alongside api_proxy configuration to force the use of the auto_auth token and enforce consistency.

# Other Vault agent configuration blocks
# ...

api_proxy {
  use_auto_auth_token = "force"
  enforce_consistency = "always"
}

listener "tcp" {
    address = "127.0.0.1:8100"
    tls_disable = true
}