88 lines
3.4 KiB
Plaintext
88 lines
3.4 KiB
Plaintext
|
---
|
||
|
|
layout: docs
|
||
|
|
page_title: Vault Agent API Proxy
|
||
|
|
description: >-
|
||
|
|
Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
|
||
|
|
for Vault's API.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Vault Agent API Proxy
|
||
|
|
|
||
|
|
Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
|
||
|
|
for Vault's API.
|
||
|
|
|
||
|
|
## Functionality
|
||
|
|
|
||
|
|
The [`listener` stanza](/docs/agent#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](/docs/agent#vault-stanza) 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](/docs/agent/caching) 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](/docs/agent/autoauth). 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](/docs/agent/apiproxy#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](/docs/enterprise/consistency#vault-agent-and-consistency-headers)
|
||
|
|
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.
|
||
|
|
|
||
|
|
```hcl
|
||
|
|
# 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
|
||
|
|
}
|
||
|
|
```
|