mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 23:21:08 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
102 lines
4.4 KiB
Plaintext
102 lines
4.4 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Use Vault Agent as an API proxy
|
|
description: >-
|
|
Use auto-authentication and configure Vault Agent as a proxy for the Vault API.
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
|
|
|
# Use Vault Agent as an API proxy
|
|
|
|
@include 'alerts/deprecated.mdx'
|
|
|
|
Vault Agent's API proxy functionality allows you to use Vault Agent's API as a proxy
|
|
for Vault's API.
|
|
|
|
<Warning title="Use Vault Proxy">
|
|
|
|
[Static secret caching](/vault/docs/agent-and-proxy/proxy/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](/vault/docs/agent-and-proxy/proxy) for API proxy
|
|
workflows.
|
|
|
|
</Warning>
|
|
|
|
## Functionality
|
|
|
|
The [`listener` stanza](/vault/docs/agent-and-proxy/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](/vault/docs/agent-and-proxy/agent#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](/vault/docs/agent-and-proxy/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](/vault/docs/agent-and-proxy/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](/vault/docs/agent-and-proxy/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](/vault/docs/enterprise/consistency#vault-proxy-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
|
|
}
|
|
```
|