luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

VAULT-15546 First pass at Vault Proxy docs (#20578) 

* VAULT-15546 First pass at Vault Proxy docs

* VAULT-15546 correct errors

* VAULT-15546 fully qualify paths

* VAULT-15546 remove index

* VAULT-15546 Some typos and clean up

* VAULT-15546 fix link

* VAULT-15546 Add redirects so old links stay working

* VAULT-15546 more explicit redirects

* VAULT-15546 typo fixes

* Suggestions for Vault Agent & Vault Proxy docs (#20612)

* Rename 'agentandproxy' to 'agent-and-proxy' for better URL

* Update the index pages for each section

* VAULT-15546 fix link typo

---------

Co-authored-by: Yoko Hyakuna <yoko@hashicorp.com>
This commit is contained in:
Violet Hynes 2023-05-19 13:11:39 -04:00 committed by GitHub
parent 7d0ae1622b
commit a47c0c7073
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
48 changed files with 1262 additions and 331 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
website/content/api-docs/index.mdx
View File

@ -179,7 +179,7 @@ For more examples, please look at the Vault API client.
## The `X-Vault-Request` Header
Requests that are sent to a [Vault Agent][agent] that is configured to use the
Requests that are sent to a [Vault Proxy][proxy] that is configured to use the
`require_request_header` option must include the `X-Vault-Request` header
entry, e.g.:
@ -314,4 +314,4 @@ A maximum request size of 32MB is imposed to prevent a denial of service attack
with arbitrarily large requests; this can be tuned per `listener` block in
Vault's server configuration file.
[agent]: /vault/docs/agent#listener-stanza
[proxy]: /vault/docs/agent-and-proxy/proxy#listener-stanza

13
website/content/docs/agent/apiproxy.mdx → website/content/docs/agent-and-proxy/agent/apiproxy.mdx
View File

@ -11,22 +11,25 @@ description: >-
Vault Agent's API Proxy functionality allows you to use Vault Agent's API as a proxy
for Vault's API.
~> Note: This functionality will be deprecated in a future release. Please
switch to using [Vault Proxy](/vault/docs/agent-and-proxy/proxy) for API proxying purposes, instead.
## Functionality
The [`listener` stanza](/vault/docs/agent#listener-stanza) for Vault Agent configures a listener for Vault Agent. If
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#vault-stanza) stanza of Vault Agent. This enables access to the Vault
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/caching) for more information on caching.
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/autoauth). By setting the
environments using [Auto-Auth](/vault/docs/agent-and-proxy/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
@ -40,7 +43,7 @@ request to the Vault server.
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/apiproxy#using-auto-auth-token), and instead ignores any
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.

10
website/content/docs/agent/caching/index.mdx → website/content/docs/agent-and-proxy/agent/caching/index.mdx
View File

@ -42,7 +42,7 @@ Vault Agent can restore tokens and leases from a persistent cache file created
by a previous Vault Agent process.
Refer to the [Vault Agent Persistent
Caching](/vault/docs/agent/caching/persistent-caches) page for more information on
Caching](/vault/docs/agent-and-proxy/agent/caching/persistent-caches) page for more information on
this functionality.
## Cache Evictions
@ -162,7 +162,7 @@ The top level `cache` block has the following configuration entry:
The `cache` block also supports the `use_auto_auth_token`, `enforce_consistency`, and
`when_inconsistent` configuration values of the `api_proxy` block
[described in the API Proxy documentation](/vault/docs/agent/apiproxy#configuration-api_proxy) only to
[described in the API Proxy documentation](/vault/docs/agent-and-proxy/agent/apiproxy#configuration-api_proxy) only to
maintain backwards compatibility. This configuration **cannot** be specified alongside `api_proxy` equivalents,
should not be preferred over configuring these values in the `api_proxy` block,
and `api_proxy` should be the preferred place to configure these values.
@ -171,8 +171,8 @@ and `api_proxy` should be the preferred place to configure these values.
[template][agent-template] or [listener][agent-listener] must also be defined
in the config, otherwise there is no way to utilize the cache.
[agent-template]: /vault/docs/agent/template
[agent-listener]: /vault/docs/agent#listener-stanza
[agent-template]: /vault/docs/agent-and-proxy/agent/template
[agent-listener]: /vault/docs/agent-and-proxy/agent#listener-stanza
### Configuration (Persist)
@ -200,7 +200,7 @@ Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`.
- `listener` `(array of objects: required)` - Configuration for the listeners.
There can be one or more `listener` blocks at the top level. Adding a listener enables
the [API Proxy](/vault/docs/agent/apiproxy) and enables the API proxy to use the cache, if configured.
the [API Proxy](/vault/docs/agent-and-proxy/agent/apiproxy) and enables the API proxy to use the cache, if configured.
These configuration values are common to both `tcp` and `unix` listener blocks. Blocks of type
`tcp` support the standard `tcp` [listener](/vault/docs/configuration/listener/tcp)
options. Additionally, the `role` string option is available as part of the top level

0
website/content/docs/agent/caching/persistent-caches/index.mdx → website/content/docs/agent-and-proxy/agent/caching/persistent-caches/index.mdx
View File

0
website/content/docs/agent/caching/persistent-caches/kubernetes.mdx → website/content/docs/agent-and-proxy/agent/caching/persistent-caches/kubernetes.mdx
View File

108
website/content/docs/agent/index.mdx → website/content/docs/agent-and-proxy/agent/index.mdx
View File

@ -6,80 +6,14 @@ description: |-
functionality automatically.
---
# Vault Agent
# What is Vault Agent?
A valid client token must accompany most requests to Vault. This
includes all API requests, as well as via the Vault CLI and other libraries.
Therefore, Vault clients must first authenticate with Vault to acquire a token.
Vault provides several different authentication methods to assist in
delivering this initial token.
Vault Agent aims to remove the initial hurdle to adopt Vault by providing a
more scalable and simpler way for applications to integrate with Vault, by
providing the ability to render [templates][template] containing the secrets
required by your application, without requiring changes to your application.
![Client authentication](/img/diagram-vault-agent.png)
If the client can securely acquire the token, all subsequent requests (e.g., request
database credentials, read key/value secrets) are processed based on the
trust established by a successful authentication.
This means that client application must invoke the Vault API to authenticate
with Vault and manage the acquired token, in addition to invoking the API to
request secrets from Vault. This implies code changes to client applications
along with additional testing and maintenance of the application.
The following code example implements Vault API to authenticate with Vault
through [AppRole auth method](/vault/docs/auth/approle#code-example), and then uses
the returned client token to read secrets at `kv-v2/data/creds`.
```go
package main
import (
...snip...
vault "github.com/hashicorp/vault/api"
)
// Fetches a key-value secret (kv-v2) after authenticating via AppRole
func getSecretWithAppRole() (string, error) {
config := vault.DefaultConfig()
client := vault.NewClient(config)
wrappingToken := ioutil.ReadFile("path/to/wrapping-token")
unwrappedToken := client.Logical().Unwrap(strings.TrimSuffix(string(wrappingToken), "\n"))
secretID := unwrappedToken.Data["secret_id"]
roleID := os.Getenv("APPROLE_ROLE_ID")
params := map[string]interface{}{
"role_id": roleID,
"secret_id": secretID,
}
resp := client.Logical().Write("auth/approle/login", params)
client.SetToken(resp.Auth.ClientToken)
secret, err := client.Logical().Read("kv-v2/data/creds")
if err != nil {
return "", fmt.Errorf("unable to read secret: %w", err)
}
data := secret.Data["data"].(map[string]interface{})
...snip...
}
```
For some Vault deployments, making (and maintaining) these changes to
applications may not be a problem, and may actually be preferred. This may be
applied to scenarios where you have a small number of applications or you want
to keep strict, customized control over how each application interacts with
Vault. However, in other situations where you have a large number of
applications, as in large enterprises, you may not have the resources or expertise
to update and maintain the Vault integration code for every application. When
third party applications are being deployed by the application, it is prohibited
to add the Vault integration code.
Vault Agent aims to remove this initial hurdle to adopt Vault by providing a
more scalable and simpler way for applications to integrate with Vault.
## What is Vault Agent?
![Vault Agent workflow](/img/vault-agent-workflow.png)
Vault Agent is a client daemon that provides the following features:
@ -111,7 +45,7 @@ the Auto-Auth token for these requests. Please see the [API Proxy docs][apiproxy
for more information.
API Proxy functionality takes place within a defined `listener`, and its behaviour can be configured with an
[`api_proxy` stanza](/vault/docs/agent/apiproxy#configuration-api_proxy).
[`api_proxy` stanza](/vault/docs/agent-and-proxy/agent/apiproxy#configuration-api_proxy).
## Caching
@ -123,7 +57,7 @@ Please see the [Caching docs][caching] for information.
### Quit
This endpoints triggers shutdown of the agent. By default, it is disabled, and can
This endpoint triggers shutdown of the agent. By default, it is disabled, and can
be enabled per listener using the [`agent_api`][agent-api] stanza. It is recommended
to only enable this on trusted interfaces, as it does not require any authorization to use.
@ -133,7 +67,7 @@ to only enable this on trusted interfaces, as it does not require any authorizat
### Cache
See the [caching](/vault/docs/agent/caching#api) page for details on the cache API.
See the [caching](/vault/docs/agent-and-proxy/agent/caching#api) page for details on the cache API.
## Configuration
@ -207,7 +141,7 @@ These are the currently-available general configuration options:
- `template_config` <code>([template_config][template-config]: <optional\>)</code> - Specifies templating engine behavior.
- `telemetry` <code>([telemetry][telemetry]: <optional\>)</code> – Specifies the telemetry
reporting system. See the [telemetry Stanza](/vault/docs/agent#telemetry-stanza) section below
reporting system. See the [telemetry Stanza](/vault/docs/agent-and-proxy/agent#telemetry-stanza) section below
for a list of metrics specific to Agent.
- `log_level` - Equivalent to the [`-log-level` command-line flag](#_log_level).
@ -322,7 +256,7 @@ listener configuration, an Agent's listener configuration also supports the foll
#### agent_api Stanza
- `enable_quit` `(bool: false)` - If set to `true`, the agent will enable the [quit](/vault/docs/agent#quit) API.
- `enable_quit` `(bool: false)` - If set to `true`, the agent will enable the [quit](/vault/docs/agent-and-proxy/agent#quit) API.
### telemetry Stanza
@ -442,15 +376,15 @@ template {
}
```
[vault]: /vault/docs/agent#vault-stanza
[autoauth]: /vault/docs/agent/autoauth
[caching]: /vault/docs/agent/caching
[apiproxy]: /vault/docs/agent/apiproxy
[persistent-cache]: /vault/docs/agent/caching/persistent-caches
[template]: /vault/docs/agent/template
[template-config]: /vault/docs/agent/template#template-configurations
[agent-api]: /vault/docs/agent/#agent_api-stanza
[listener]: /vault/docs/agent#listener-stanza
[vault]: /vault/docs/agent-and-proxy/agent#vault-stanza
[autoauth]: /vault/docs/agent-and-proxy/agent/autoauth
[caching]: /vault/docs/agent-and-proxy/agent/caching
[apiproxy]: /vault/docs/agent-and-proxy/agent/apiproxy
[persistent-cache]: /vault/docs/agent-and-proxy/agent/caching/persistent-caches
[template]: /vault/docs/agent-and-proxy/agent/template
[template-config]: /vault/docs/agent-and-proxy/agent/template#template-configurations
[agent-api]: /vault/docs/agent-and-proxy/agent/#agent_api-stanza
[listener]: /vault/docs/agent-and-proxy/agent#listener-stanza
[listener_main]: /vault/docs/configuration/listener/tcp
[winsvc]: /vault/docs/agent/winsvc
[winsvc]: /vault/docs/agent-and-proxy/agent/winsvc
[telemetry]: /vault/docs/configuration/telemetry

10
website/content/docs/agent/template.mdx → website/content/docs/agent-and-proxy/agent/template.mdx
View File

@ -115,7 +115,7 @@ template_config {
}
```
In another example `template_config` with [`error_on_missing_key` parameter in the template stanza](/vault/docs/agent/template#error_on_missing_key)
In another example `template_config` with [`error_on_missing_key` parameter in the template stanza](/vault/docs/agent-and-proxy/agent/template#error_on_missing_key)
as well as `exit_on_retry_failure` result in the agent exiting in case of no key
/ value issues instead of the default retry behavior.
@ -135,7 +135,7 @@ template {
### Interaction between `exit_on_retry_failure` and `error_on_missing_key`
The parameter
[`error_on_missing_key`](/vault/docs/agent/template#error_on_missing_key) can be
[`error_on_missing_key`](/vault/docs/agent-and-proxy/agent/template#error_on_missing_key) can be
specified within the `template` stanza which determines if a template should
error when a key is missing in the secret. When `error_on_missing_key` is not
specified or set to `false` and the key to render is not in the secret's
@ -184,7 +184,7 @@ can be used here:
- `error_on_missing_key` `(bool: false)` - Exit with an error when accessing
a struct or map field/key that does notexist. The default behavior will print `<no value>`
when accessing a field that does not exist. It is highly recommended you set this
to "true". Also see [`exit_on_retry_failure` in global Vault Agent Template Config](/vault/docs/agent/template#interaction-between-exit_on_retry_failure-and-error_on_missing_key).
to "true". Also see [`exit_on_retry_failure` in global Vault Agent Template Config](/vault/docs/agent-and-proxy/agent/template#interaction-between-exit_on_retry_failure-and-error_on_missing_key).
- `exec` `(object: optional)` - The exec block executes a command when the
template is rendered and the output has changed. The block parameters are
`command` `(string or array: required)` and `timeout` `(string: optional, defaults
@ -231,7 +231,7 @@ the `auto_auth` stanza in the agent configuration.
## Renewals and Updating Secrets
The Vault Agent templating automatically renews and fetches secrets/tokens.
Unlike [Vault Agent caching](/vault/docs/agent/caching), the behavior of how Vault Agent
Unlike [Vault Agent caching](/vault/docs/agent-and-proxy/agent/caching), the behavior of how Vault Agent
templating does this depends on the type of secret or token. The following is a
high level overview of different behaviors.
@ -243,7 +243,7 @@ of the secret's lease duration has elapsed.
### Non-Renewable Secrets
If a secret or token isn't renewable or leased, Vault Agent will fetch the secret every 5 minutes.
This can be configured using Template config [static_secret_render_interval](/vault/docs/agent/template#static_secret_render_interval) (requires Vault 1.8+).
This can be configured using Template config [static_secret_render_interval](/vault/docs/agent-and-proxy/agent/template#static_secret_render_interval) (requires Vault 1.8+).
Non-renewable secrets include (but not limited to) [KV Version 2](/vault/docs/secrets/kv/kv-v2).
### Non-Renewable Leased Secrets

0
website/content/docs/agent/versions.mdx → website/content/docs/agent-and-proxy/agent/versions.mdx
View File

0
website/content/docs/agent/winsvc.mdx → website/content/docs/agent-and-proxy/agent/winsvc.mdx
View File

64
website/content/docs/agent/autoauth/index.mdx → website/content/docs/agent-and-proxy/autoauth/index.mdx
View File

@ -1,15 +1,15 @@
---
layout: docs
page_title: Vault Agent Auto-Auth
page_title: Vault Agent and Vault Proxy Auto-Auth
description: |-
Vault Agent's Auto-Auth functionality allows easy and automatic
Vault Agent and Vault Proxy's Auto-Auth functionality allows easy and automatic
authentication to Vault in a variety of environments.
---
# Vault Agent Auto-Auth
# Vault Agent and Vault Proxy Auto-Auth
The Auto-Auth functionality of Vault Agent allows for easy authentication in a
wide variety of environments.
The Auto-Auth functionality of Vault Agent and Vault Proxy allow for
easy authentication in a wide variety of environments.
## Functionality
@ -18,7 +18,7 @@ that should be used in the current environment; and any number of Sinks, which
are locations where the agent should write a token any time the current token
value has changed.
When the agent is started with Auto-Auth enabled, it will attempt to acquire a
When Vault Agent or Vault Proxy are started with Auto-Auth enabled, it will attempt to acquire a
Vault token using the configured Method. On failure, it will exponentially back
off and then retry. On success, unless the auth method is configured to wrap
the tokens, it will keep the resulting token renewed until renewal is no longer
@ -38,21 +38,21 @@ response-wrapped, then encrypted.
### Response-Wrapping Tokens
There are two ways that tokens can be response-wrapped by the agent:
There are two ways that tokens can be response-wrapped:
1. By the auth method. This allows the end client to introspect the
`creation_path` of the token, helping prevent Man-In-The-Middle (MITM)
attacks. However, because the agent cannot then unwrap the token and rewrap
it without modifying the `creation_path`, the agent is not able to renew the
token; it is up to the end client to renew the token. The agent stays
daemonized in this mode since some auth methods allow for reauthentication
attacks. However, because auto-auth cannot then unwrap the token and rewrap
it without modifying the `creation_path`, we are not able to renew the
token; it is up to the end client to renew the token. Agent and Proxy both
stay daemonized in this mode since some auth methods allow for reauthentication
on certain events.
2. By any of the token sinks. Because more than one sink can be configured, the
token must be wrapped after it is fetched, rather than wrapped by Vault as
it's being returned. As a result, the `creation_path` will always be
`sys/wrapping/wrap`, and validation of this field cannot be used as
protection against MITM attacks. However, this mode allows the agent to keep
protection against MITM attacks. However, this mode allows auto-auth to keep
the token renewed for the end client and automatically reauthenticate when
it expires.
@ -76,17 +76,17 @@ public-key input files could attack this exchange. Using TLS to protect the
transit of tokens is highly recommended.
To help mitigate MITM attacks, additional authenticated data (AAD) can be
provided to the agent. This data is written as part of the AES-GCM tag and must
match on both the agent and the client. This of course means that protecting
provided to Agent and Proxy. This data is written as part of the AES-GCM tag and must
match on both Agent and Proxy and the client. This of course means that protecting
this AAD becomes important, but it provides another layer for an attacker to
have to overcome. For instance, if the attacker has access to the file system
where the token is being written, but not to read agent configuration or read
environment variables, this AAD can be generated and passed to the agent and
where the token is being written, but not to read configuration or read
environment variables, this AAD can be generated and passed to Agent or Proxy and
the client in ways that would be difficult for the attacker to find.
When using AAD, it is always a good idea for this to be as fresh as possible;
generate a value and pass it to your client and agent on startup. Additionally,
agent uses a Trust On First Use model; after it finds a generated public key,
generate a value and pass it to your client and Agent or Proxy on startup. Additionally,
Agent and Proxy a Trust On First Use model; after it finds a generated public key,
it will reuse that public key instead of looking for new values that have been
written.
@ -106,8 +106,8 @@ The top level `auto_auth` block has two configuration entries:
### Configuration (Method)
~> Auto-auth does not support using tokens with a limited number of uses. Vault
Agent does not track the number of uses remaining, and may allow the token to
~> Auto-auth does not support using tokens with a limited number of uses. Auto-auth
does not track the number of uses remaining, and may allow the token to
expire before attempting to renew it. For example, if using AppRole auto-auth,
you must use 0 (meaning unlimited) as the value for
[`token_num_uses`](/vault/api-docs/auth/approle#token_num_uses).
@ -130,14 +130,14 @@ These are common configuration values that live within the `method` block:
on the client created by auto-auth, they use the same namespace.
- `wrap_ttl` `(string or integer: optional)` - If specified, the written token
will be response-wrapped by the agent. This is more secure than wrapping by
sinks, but does not allow the agent to keep the token renewed or
will be response-wrapped by auto-auth. This is more secure than wrapping by
sinks, but does not allow the auto-auth to keep the token renewed or
automatically reauthenticate when it expires. Rather than a simple string,
the written value will be a JSON-encoded
[SecretWrapInfo](https://godoc.org/github.com/hashicorp/vault/api#SecretWrapInfo)
structure. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `min_backoff` `(string or integer: "1s")` - The minimum backoff time Agent
- `min_backoff` `(string or integer: "1s")` - The minimum backoff time auto-auth
will delay before retrying after a failed auth attempt. The backoff will start
at the configured value and double (with some randomness) after successive
failures, capped by `max_backoff.` If Agent templating is being used, this
@ -152,9 +152,9 @@ These are common configuration values that live within the `method` block:
duration between retries, and **not** the duration that retries will be
performed before giving up. Uses [duration format strings](/vault/docs/concepts/duration-format).
- `exit_on_err` `(bool: false)` - When set to true, Vault Agent will exit if any
errors occur during authentication. This configurable only affects login attempts
for new tokens (either intial or expired tokens) and will not exit for errors on
- `exit_on_err` `(bool: false)` - When set to true, Vault Agent and Vault Proxy
will exit if any errors occur during authentication. This configurable only affects login
attempts for new tokens (either initial or expired tokens) and will not exit for errors on
valid token renewals.
- `config` `(object: required)` - Configuration of the method itself. See the
@ -169,7 +169,7 @@ These configuration values are common to all Sinks:
- `wrap_ttl` `(string or integer: optional)` - If specified, the written token
will be response-wrapped by the sink. This is less secure than wrapping by
the method, but allows the agent to keep the token renewed and automatically
the method, but allows auto-auth to keep the token renewed and automatically
reauthenticate when it expires. Rather than a simple string, the written
value will be a JSON-encoded
[SecretWrapInfo](https://godoc.org/github.com/hashicorp/vault/api#SecretWrapInfo)
@ -180,7 +180,7 @@ These configuration values are common to all Sinks:
supported.
- `dh_path` `(string: required if dh_type is set)` - The path from which the
agent should read the client's initial parameters (e.g. curve25519 public
auto-auth should read the client's initial parameters (e.g. curve25519 public
key).
- `derive_key` `(bool: false)` - If specified, the final encryption key is
@ -213,7 +213,7 @@ The HCL format may define any number of sink objects with an optional wrapping
`"sinks" : [...]` array to encapsulate all `sink` JSON objects.
```hcl
// Other Vault Agent configuration blocks
// Other Vault Agent or Vault Proxy configuration blocks
// ...
auto_auth {
@ -242,7 +242,7 @@ The following valid HCL omits the wrapping `sinks` object while specifying
multiple sinks.
```hcl
// Other Vault Agent configuration blocks
// Other Vault Agent or Vault Proxy configuration blocks
// ...
auto_auth {
@ -278,7 +278,7 @@ auto_auth {
The following JSON configuration illustrates the need for a `sinks: [...]` array
wrapping any number of `sink` objects.
```json
```hcl
{
"auto_auth" : {
"method" : [
@ -309,7 +309,7 @@ wrapping any number of `sink` objects.
Multiple sinks are defined by appending more `sink` objects within the `sinks`
array:
```json
```hcl
{
"auto_auth" : {
"method" : [

6
website/content/docs/agent/autoauth/methods/alicloud.mdx → website/content/docs/agent-and-proxy/autoauth/methods/alicloud.mdx
View File

@ -1,7 +1,7 @@
---
layout: docs
page_title: Vault Agent Auto-Auth AliCloud Method
description: AliCloud Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth AliCloud Method
description: AliCloud Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth AliCloud Method
@ -11,7 +11,7 @@ method](/vault/docs/auth/alicloud).
## Credentials
The Vault agent will use the first credential it can successfully obtain in the following order:
Auto-auth will use the first credential it can successfully obtain in the following order:
1. [Environment variables](https://github.com/aliyun/alibaba-cloud-sdk-go/blob/master/sdk/auth/credentials/providers/env.go)
2. A static credential configuration

10
website/content/docs/agent/autoauth/methods/approle.mdx → website/content/docs/agent-and-proxy/autoauth/methods/approle.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth AppRole Method
description: AppRole Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth AppRole Method
description: AppRole Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth AppRole Method
# Vault Auto-Auth AppRole Method
The `approle` method reads in a role ID and a secret ID from files and sends
the values to the [AppRole Auth
@ -39,8 +39,8 @@ cached.
## Example Configuration
An example configuration, using approle to enable [auto-auth](/vault/docs/agent/autoauth)
and creating both a plaintext token sink and a [response-wrapped token sink file](/vault/docs/agent/autoauth#wrap_ttl), follows:
An example configuration, using approle to enable [auto-auth](/vault/docs/agent-and-proxy/autoauth)
and creating both a plaintext token sink and a [response-wrapped token sink file](/vault/docs/agent-and-proxy/autoauth#wrap_ttl), follows:
```hcl
pid_file = "./pidfile"

8
website/content/docs/agent/autoauth/methods/aws.mdx → website/content/docs/agent-and-proxy/autoauth/methods/aws.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth AWS Method
description: AWS Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth AWS Method
description: AWS Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth AWS Method
# Vault Auto-Auth AWS Method
The `aws` method performs authentication against the [AWS Auth
method](/vault/docs/auth/aws). Both `ec2` and `iam`
@ -63,4 +63,4 @@ parameters unset in your configuration.
## Tutorial
Refer to the [Vault Agent with
AWS](/vault/tutorials/vault-agent/agent-aws) tutorial to learn how to integrate Vault with IAM AWS' native authentication.
AWS](/vault/tutorials/vault-agent/agent-aws) tutorial to learn how to integrate Vault Agent with IAM AWS' native authentication.

6
website/content/docs/agent/autoauth/methods/azure.mdx → website/content/docs/agent-and-proxy/autoauth/methods/azure.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth Azure Method
description: Azure Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth Azure Method
description: Azure Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth Azure Method
# Vault Auto-Auth Azure Method
The `azure` method reads in Azure instance credentials and uses them to
authenticate with the [Azure Auth

10
website/content/docs/agent/autoauth/methods/cert.mdx → website/content/docs/agent-and-proxy/autoauth/methods/cert.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth Cert Method
description: Cert Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth Cert Method
description: Cert Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth Cert Method
# Vault Auto-Auth Cert Method
The `cert` method uses the configured TLS certificates from the `vault` stanza of
the agent configuration and takes an optional `name` parameter. There is no option
@ -13,8 +13,8 @@ to use certificates which differ from those used in the `vault` stanza.
It is strongly advised to provide TLS settings in the configuration stanza
within the auth method to avoid agent cache, if also enabled, from using the
same TLS settings when proxying requests. If TLS settings are not present in the
config stanza, Agent will fall back to using TLS settings from the [`vault`
Stanza](/vault/docs/agent#vault-stanza).
config stanza, Agent and Proxy will fall back to using TLS settings from their respective
[`vault` Stanzas](/vault/docs/agent#vault-stanza).
## Configuration

4
website/content/docs/agent/autoauth/methods/cf.mdx → website/content/docs/agent-and-proxy/autoauth/methods/cf.mdx
View File

@ -1,7 +1,7 @@
---
layout: docs
page_title: Vault Agent Auto-Auth CF Method
description: CF Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth CF Method
description: CF Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth CF Method

6
website/content/docs/agent/autoauth/methods/gcp.mdx → website/content/docs/agent-and-proxy/autoauth/methods/gcp.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth GCP Method
description: GCP Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth GCP Method
description: GCP Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth GCP Method
# Vault Auto-Auth GCP Method
The `gcp` method performs authentication against the [GCP Auth
method](/vault/docs/auth/gcp). Both `gce` and `iam`

12
website/content/docs/agent-and-proxy/autoauth/methods/index.mdx Normal file
View File

@ -0,0 +1,12 @@
---
layout: docs
page_title: Vault Auto-Auth Methods
description: Methods for Vault Auto-Auth
---
# Vault Auto-Auth Methods
Auto-auth is a mechanism used by Vault Agent and Vault Proxy to authenticate
to Vault in an automatic manner, given a set of parameters allowing the
authentication. Please see the sidebar for available methods and their
usage/configuration.

8
website/content/docs/agent/autoauth/methods/jwt.mdx → website/content/docs/agent-and-proxy/autoauth/methods/jwt.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth JWT Method
description: JWT Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth JWT Method
description: JWT Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth JWT Method
# Vault Auto-Auth JWT Method
The `jwt` method reads in a JWT from a file and sends it to the [JWT Auth
method](/vault/docs/auth/jwt).
@ -27,4 +27,4 @@ the symlink, not the JWT. Does nothing if `remove_jwt_after_reading` is false.
- `jwt_read_period` `(duration: "0.5s", optional)` - The duration after which
Agent will attempt to read the JWT stored at `path`. Defaults to `1m` if
`remove_jwt_after_reading` is set to `true`, or `0.5s` otherwise.
Uses [duration format strings](/docs/concepts/duration-format).
Uses [duration format strings](/vault/docs/concepts/duration-format).

10
website/content/docs/agent/autoauth/methods/kerberos.mdx → website/content/docs/agent-and-proxy/autoauth/methods/kerberos.mdx
View File

@ -1,14 +1,14 @@
---
layout: 'docs'
page_title: 'Vault Agent Auto-Auth Kerberos Method'
sidebar_current: 'docs-agent-autoauth-methods-kerberos'
page_title: 'Vault Auto-Auth Kerberos Method'
sidebar_current: 'docs-agent-and-proxy-autoauth-methods-kerberos'
description: |-
Kerberos Method for Vault Agent Auto-Auth
Kerberos Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth Kerberos Method
# Vault Auto-Auth Kerberos Method
The `kerberos` agent provides an automated mechanism to retrieve
The `kerberos` auto-auth method provides an automated mechanism to retrieve
a Vault token for Kerberos entities. It reads in configuration and
identification information from the surrounding environment, and uses
it to authenticate to Vault.

6
website/content/docs/agent/autoauth/methods/kubernetes.mdx → website/content/docs/agent-and-proxy/autoauth/methods/kubernetes.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth Kubernetes Method
description: Kubernetes Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth Kubernetes Method
description: Kubernetes Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth Kubernetes Method
# Vault Auto-Auth Kubernetes Method
The `kubernetes` method reads in a Kubernetes service account token from the
running pod (via `/var/run/secrets/kubernetes.io/serviceaccount/token`) and

8
website/content/docs/agent/autoauth/methods/oci.mdx → website/content/docs/agent-and-proxy/autoauth/methods/oci.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth OCI (Oracle Cloud Infrastructure) Method
description: OCI (Oracle Cloud Infrastructure) Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth OCI (Oracle Cloud Infrastructure) Method
description: OCI (Oracle Cloud Infrastructure) Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth OCI (Oracle Cloud Infrastructure) Method
# Vault Auto-Auth OCI (Oracle Cloud Infrastructure) Method
The `oci` method performs authentication against the [OCI Auth
method](/vault/docs/auth/oci).
@ -40,4 +40,4 @@ but from experience, credentials are rotated every 10 to 15 minutes.
- `role` `(string: required)` - The role to authenticate against on Vault.
- `credential_poll_interval` `(duration: "60s", optional)` - In seconds, how frequently the Vault agent should check for new credentials.
- `credential_poll_interval` `(duration: "60s", optional)` - In seconds, how frequently the Vault auto-auth method should check for new credentials.

20
website/content/docs/agent/autoauth/methods/token_file.mdx → website/content/docs/agent-and-proxy/autoauth/methods/token_file.mdx
View File

@ -1,23 +1,23 @@
---
layout: docs
page_title: Vault Agent Auto-Auth Token File Method
description: Token File Method for Vault Agent Auto-Auth
page_title: Vault Auto-Auth Token File Method
description: Token File Method for Vault Auto-Auth
---
# Vault Agent Auto-Auth Token File Method
# Vault Auto-Auth Token File Method
~> Note: This authentication method is tailored for the development experience,
and to facilitate getting started with Vault Agent. Vault Agent should never be configured to use
this auto-auth method in a production environment.
and to facilitate getting started with Vault Agent and Vault Proxy. Vault Agent and
Vault Proxy should never be configured to use this auto-auth method in a production environment.
The `token_file` method reads in an existing, valid Vault token from a file, and uses that
token in lieu of authenticating itself. While it's a first class auto-auth method for all intents
and purposes, it naturally doesn't authenticate itself, as it requires a token from elsewhere. Like
other auto-auth methods, Agent will attempt to renew the token, as appropriate.
other auto-auth methods, this method will attempt to renew the token, as appropriate.
This auto-auth method is especially useful when testing Vault Agent without needing to set up
any authentication methods in Vault. For long-running Agent processes, we strongly recommend another
auto-auth method, such that Agent is issuing its own authentication requests to Vault.
This auto-auth method is especially useful when testing Vault Agent or Vault Proxy without needing to set up
any authentication methods in Vault. For long-running Agent or Proxy processes, we strongly recommend another
auto-auth method, such that Agent and Proxy are issuing their own own authentication requests to Vault.
## Configuration
@ -25,7 +25,7 @@ auto-auth method, such that Agent is issuing its own authentication requests to
## Example Configuration
An example configuration, using the `token_file` method to enable [auto-auth](/vault/docs/agent/autoauth), follows:
An example configuration for Vault Agent, using the `token_file` method to enable [auto-auth](/vault/docs/agent-and-proxy/autoauth), follows:
```hcl
pid_file = "./pidfile"

8
website/content/docs/agent/autoauth/sinks/file.mdx → website/content/docs/agent-and-proxy/autoauth/sinks/file.mdx
View File

@ -1,10 +1,10 @@
---
layout: docs
page_title: Vault Agent Auto-Auth File Sink
description: File sink for Vault Agent Auto-Auth
page_title: Vault Agent and Vault Proxy Auto-Auth File Sink
description: File sink for Auto-Auth
---
# Vault Agent Auto-Auth File Sink
# Vault Agent and Vault Proxy Auto-Auth File Sink
The `file` sink writes tokens, optionally response-wrapped and/or encrypted, to
a file. This may be a local file or a file mapped via some other process (NFS,
@ -24,4 +24,4 @@ written with `0640` permissions as default, but can be overridden with the optio
- `mode` `(int: optional)` - A string containing an octal number representing the bit pattern for the file mode, similar to chmod. Set to `0000` to prevent Vault from modifying the file mode. Note: This configuration option is only available in Vault 1.3.0 and above.
~> Note: Configuration options for response-wrapping and encryption for the sink
file are located within the [options common to all sinks](/vault/docs/agent/autoauth#configuration-sinks) documentation.
file are located within the [options common to all sinks](/vault/docs/agent-and-proxy/autoauth#configuration-sinks) documentation.

11
website/content/docs/agent-and-proxy/autoauth/sinks/index.mdx Normal file
View File

@ -0,0 +1,11 @@
---
layout: docs
page_title: Vault Agent and Vault Proxy Auto-Auth Sinks
description: Sinks for Auto-Auth
---
# Vault Agent and Vault Proxy Auto-Auth Sinks
Every time an auto-auth authentication is successful, the token is written to the
enabled Sinks, subject to their configuration. Today, we only support one
type of sink, [file sink](/vault/docs/agent-and-proxy/sinks/file).

107
website/content/docs/agent-and-proxy/index.mdx Normal file
View File

@ -0,0 +1,107 @@
---
layout: docs
page_title: Vault Agent and Vault Proxy
description: |-
Vault Agent and Vault Proxy are daemons that can be used to perform some Vault
functionality automatically.
---
# Vault Agent and Vault Proxy
A valid client token must accompany most requests to Vault. This
includes all API requests, as well as via the Vault CLI and other libraries.
Therefore, Vault clients must first authenticate with Vault to acquire a token.
Vault provides several authentication methods to assist in
delivering this initial token.
![Client authentication](/img/diagram-vault-agent.png)
If the client can securely acquire the token, all subsequent requests (e.g., request
database credentials, read key/value secrets) are processed based on the
trust established by a successful authentication.
This means that client application must invoke the Vault API to authenticate
with Vault and manage the acquired token, in addition to invoking the API to
request secrets from Vault. This implies code changes to client applications
along with additional testing and maintenance of the application.
The following code example implements Vault API to authenticate with Vault
through [AppRole auth method](/vault/docs/auth/approle#code-example), and then uses
the returned client token to read secrets at `kv-v2/data/creds`.
```go
package main
import (
...snip...
vault "github.com/hashicorp/vault/api"
)
// Fetches a key-value secret (kv-v2) after authenticating via AppRole
func getSecretWithAppRole() (string, error) {
config := vault.DefaultConfig()
client := vault.NewClient(config)
wrappingToken := ioutil.ReadFile("path/to/wrapping-token")
unwrappedToken := client.Logical().Unwrap(strings.TrimSuffix(string(wrappingToken), "\n"))
secretID := unwrappedToken.Data["secret_id"]
roleID := os.Getenv("APPROLE_ROLE_ID")
params := map[string]interface{}{
"role_id": roleID,
"secret_id": secretID,
}
resp := client.Logical().Write("auth/approle/login", params)
client.SetToken(resp.Auth.ClientToken)
secret, err := client.Logical().Read("kv-v2/data/creds")
if err != nil {
return "", fmt.Errorf("unable to read secret: %w", err)
}
data := secret.Data["data"].(map[string]interface{})
...snip...
}
```
For some Vault deployments, making (and maintaining) these changes to
applications may not be a problem, and may actually be preferred. This may be
applied to scenarios where you have a small number of applications, or you want
to keep strict, customized control over how each application interacts with
Vault. However, in other situations where you have a large number of
applications, as in large enterprises, you may not have the resources or expertise
to update and maintain the Vault integration code for every application. When
third party applications are being deployed by the application, it is prohibited
to add the Vault integration code.
### Introduce Vault Agent and Vault Proxy to the workflow
[Vault Agent][vaultagent] and [Vault Proxy][vaultproxy] aim to remove this initial hurdle to adopt Vault by providing a
more scalable and simpler way for applications to integrate with Vault. Vault Agent can
obtain secrets and provide them to applications, and Vault Proxy can act as
a proxy between Vault and the application, optionally simplifying the authentication process
and caching requests.
| Capability | Vault Agent | Vault Proxy |
| -------------------------------------------------------- | :----------------: | :---------: |
| [Auto-Auth][autoauth] to authenticate with Vault | x | x |
| [Caching][caching] the newly created tokens and leases | x | x |
| Run as a [Windows Service][winsvc] | x | |
| [Templating][template] to render user-supplied templates | x | |
| [API Proxy][apiproxy] to act as a proxy for Vault API | Will be deprecated | x |
To learn more, refer to the [Vault Agent][vaultagent] or [Vault
Proxy][vaultproxy] documentation page.
[autoauth]: /vault/docs/agent-and-proxy/autoauth
[caching]: /vault/docs/agent-and-proxy/agent/caching
[apiproxy]: /vault/docs/agent-and-proxy/proxy/apiproxy
[template]: /vault/docs/agent-and-proxy/agent/template
[template-config]: /vault/docs/agent-and-proxy/agent/template#template-configurations
[vaultagent]: /vault/docs/agent-and-proxy/agent
[vaultproxy]: /vault/docs/agent-and-proxy/proxy
[winsvc]: /vault/docs/agent-and-proxy/agent/winsvc

87
website/content/docs/agent-and-proxy/proxy/apiproxy.mdx Normal file
View File

@ -0,0 +1,87 @@
---
layout: docs
page_title: Vault Proxy API Proxy
description: >-
Vault Proxy's API Proxy functionality allows you to use Vault Proxy's API as a proxy
for Vault's API.
---
# Vault Proxy API Proxy
Vault Proxy's API Proxy functionality allows you to use Vault Proxy's API as a proxy
for Vault's API.
## Functionality
The [`listener` stanza](/vault/docs/agent#listener-stanza) for Vault Proxy configures a listener for Vault Proxy. 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/proxy#vault-stanza) of Proxy Agent. This enables access to the Vault
API from the Proxy 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/proxy/caching) for more information on caching.
## Using Auto-Auth Token
Vault Proxy 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 Proxy 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/proxy/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-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 Proxy configuration blocks
# ...
api_proxy {
use_auto_auth_token = "force"
enforce_consistency = "always"
}
listener "tcp" {
address = "127.0.0.1:8100"
tls_disable = true
}
```

242
website/content/docs/agent-and-proxy/proxy/caching/index.mdx Normal file
View File

@ -0,0 +1,242 @@
---
layout: docs
page_title: Vault Proxy Caching
description: |-
Vault Proxy Caching allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these
newly created tokens.
---
# Vault Proxy Caching
Vault Proxy Caching allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these
newly created tokens. The renewals of the cached tokens and leases are also
managed by the proxy.
-> **Note:** Vault Proxy Caching works best with servers/clusters that are
running on Vault 1.1 and above due to changes that were introduced
alongside this feature, such as the exposure of the `orphan` field in token
creation responses.
## Caching and Renewals
Response caching and renewals are managed by the proxy only under these
specific scenarios.
1. Token creation requests are made through the proxy. This means that any
login operations performed using various auth methods and invoking the token
creation endpoints of the token auth method via the proxy will result in the
response getting cached by the proxy. Responses containing new tokens will
be cached by the proxy only if the parent token is already being managed by
the proxy or if the new token is an orphan token.
2. Leased secret creation requests are made through the proxy using tokens that
are already managed by the proxy. This means that any dynamic credentials
that are issued using the tokens managed by the proxy, will be cached and
its renewals are taken care of.
## Persistent Cache
Vault Proxy can restore tokens and leases from a persistent cache file created
by a previous Vault Proxy process.
Refer to the [Vault Proxy Persistent
Caching](/vault/docs/agent-and-proxy/proxy/caching/persistent-caches) page for more information on
this functionality.
## Cache Evictions
The eviction of cache entries pertaining to secrets will occur when the proxy
can no longer renew them. This can happen when the secrets hit their maximum
TTL or if the renewals result in errors.
Vault Proxy does some best-effort cache evictions by observing specific request types
and response codes. For example, if a token revocation request is made via the
proxy and if the forwarded request to the Vault server succeeds, then proxy
evicts all the cache entries associated with the revoked token. Similarly, any
lease revocation operation will also be intercepted by the proxy and the
respective cache entries will be evicted.
Note that while proxy evicts the cache entries upon secret expirations and upon
intercepting revocation requests, it is still possible for the proxy to be
completely unaware of the revocations that happen through direct client
interactions with the Vault server. This could potentially lead to stale cache
entries. For managing the stale entries in the cache, an endpoint
`/proxy/v1/cache-clear`(see below) is made available to manually evict cache
entries based on some of the query criteria used for indexing the cache entries.
## Request Uniqueness
In order to detect repeat requests and return cached responses, proxy will need
to have a way to uniquely identify the requests. This computation as it stands
today takes a simplistic approach (may change in future) of serializing and
hashing the HTTP request along with all the headers and the request body. This
hash value is then used as an index into the cache to check if the response is
readily available. The consequence of this approach is that the hash value for
any request will differ if any data in the request is modified. This has the
side-effect of resulting in false negatives if say, the ordering of the request
parameters are modified. As long as the requests come in without any change,
caching behavior should be consistent. Identical requests with differently
ordered request values will result in duplicated cache entries. A heuristic
assumption that the clients will use consistent mechanisms to make requests,
thereby resulting in consistent hash values per request is the idea upon which
the caching functionality is built upon.
## Renewal Management
The tokens and leases are renewed by the proxy using the secret renewer that is
made available via the Vault server's [Go
API](https://godoc.org/github.com/hashicorp/vault/api#Renewer). Proxy performs
all operations in memory and does not persist anything to storage. This means
that when the proxy is shut down, all the renewal operations are immediately
terminated and there is no way for the proxy to resume renewals after the fact.
Note that shutting down the proxy does not indicate revocations of the secrets,
instead it only means that renewal responsibility for all the valid unrevoked
secrets are no longer performed by the Vault proxy.
## API
### Cache Clear
This endpoint clears the cache based on given criteria. To use this
API, some information on how the proxy caches values should be known
beforehand. Each response that is cached in the proxy will be indexed on some
factors depending on the type of request. Those factors can be the `token` that
is belonging to the cached response, the `token_accessor` of the token
belonging to the cached response, the `request_path` that resulted in the
cached response, the `lease` that is attached to the cached response, the
`namespace` to which the cached response belongs to, and a few more. This API
exposes some factors through which associated cache entries are fetched and
evicted. For listeners without caching enabled, this API will still be available,
but will do nothing (there is no cache to clear) and will return a `200` response.
| Method | Path | Produces |
| :----- | :---------------------- | :--------------------- |
| `POST` | `/proxy/v1/cache-clear` | `200 application/json` |
#### Parameters
- `type` `(strings: required)` - The type of cache entries to evict. Valid
values are `request_path`, `lease`, `token`, `token_accessor`, and `all`.
If the `type` is set to `all`, the _entire cache_ is cleared.
- `value` `(string: required)` - An exact value or the prefix of the value for
the `type` selected. This parameter is optional when the `type` is set
to `all`.
- `namespace` `(string: optional)` - This is only applicable when the `type` is set to
`request_path`. The namespace of which the cache entries to be evicted for
the given request path.
### Sample Payload
```json
{
"type": "token",
"value": "hvs.rlNjegSKykWcplOkwsjd8bP9"
}
```
### Sample Request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:1234/proxy/v1/cache-clear
```
## Configuration (`cache`)
The presence of the top level `cache` block in any way (including an empty `cache` block) will enable the cache.
The top level `cache` block has the following configuration entry:
- `persist` `(object: optional)` - Configuration for the persistent cache.
-> **Note:** When the `cache` block is defined, a [listener][proxy-listener] must also be defined
in the config, otherwise there is no way to utilize the cache.
[proxy-listener]: /vault/docs/agent-and-proxy/proxy#listener-stanza
### Configuration (Persist)
These are common configuration values that live within the `persist` block:
- `type` `(string: required)` - The type of the persistent cache to use,
e.g. `kubernetes`. _Note_: when using HCL this can be used as the key for
the block, e.g. `persist "kubernetes" {...}`.
- `path` `(string: required)` - The path on disk where the persistent cache file
should be created or restored from.
- `keep_after_import` `(bool: optional)` - When set to true, a restored cache file
is not deleted. Defaults to `false`.
- `exit_on_err` `(bool: optional)` - When set to true, if any errors occur during
a persistent cache restore, Vault Proxy will exit with an error. Defaults to `true`.
- `service_account_token_file` `(string: optional)` - When `type` is set to `kubernetes`,
this configures the path on disk where the Kubernetes service account token can be found.
Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`.
## Configuration (`listener`)
- `listener` `(array of objects: required)` - Configuration for the listeners.
There can be one or more `listener` blocks at the top level. Adding a listener enables
the [API Proxy](/vault/docs/agent-and-proxy/proxy/apiproxy) and enables the API proxy to use the cache, if configured.
These configuration values are common to both `tcp` and `unix` listener blocks. Blocks of type
`tcp` support the standard `tcp` [listener](/vault/docs/configuration/listener/tcp)
options. Additionally, the `role` string option is available as part of the top level
of the `listener` block, which can be configured to `metrics_only` to serve only metrics,
or the default role, `default`, which serves everything (including metrics).
- `type` `(string: required)` - The type of the listener to use. Valid values
are `tcp` and `unix`.
_Note_: when using HCL this can be used as the key for the block, e.g.
`listener "tcp" {...}`.
- `address` `(string: required)` - The address for the listener to listen to.
This can either be a URL path when using `tcp` or a file path when using
`unix`. For example, `127.0.0.1:8200` or `/path/to/socket`. Defaults to
`127.0.0.1:8200`.
- `tls_disable` `(bool: false)` - Specifies if TLS will be disabled.
- `tls_key_file` `(string: optional)` - Specifies the path to the private key
for the certificate.
- `tls_cert_file` `(string: optional)` - Specifies the path to the certificate
for TLS.
### Example Configuration
Here is an example of a cache configuration with the optional `persist` block,
alongside a regular listener, and a listener that only serves metrics.
```hcl
# Other Vault Proxy configuration blocks
# ...
cache {
persist = {
type = "kubernetes"
path = "/vault/proxy-cache/"
keep_after_import = true
exit_on_err = true
service_account_token_file = "/tmp/serviceaccount/token"
}
}
listener "tcp" {
address = "127.0.0.1:8100"
tls_disable = true
}
listener "tcp" {
address = "127.0.0.1:3000"
tls_disable = true
role = "metrics_only"
}
```

42
website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/index.mdx Normal file
View File

@ -0,0 +1,42 @@
---
layout: docs
page_title: Vault Proxy Persistent Caching
description: Vault Proxy Caching
---
# Vault Proxy Persistent Caching
Vault Proxy can restore tokens and leases from a persistent cache file created
by a previous Vault Proxy process. The persistent cache is a BoltDB file that
includes tuples encrypted by a generated encryption key. The encrypted tuples
include the Vault token used to retrieve secrets, leases for tokens/secrets, and
secret values.
-> **Note:** Vault Proxy Persistent Caching will only restore _leased_
secrets. Secrets that are not renewable, such as KV v2, will not be persisted.
In order to use Vault Proxy persistent cache, auto-auth must be used. If the
auto-auth token has expired by the time the cache is restored, the cache will
be invalidated and secrets will need to be re-fetched from Vault.
-> **Note** Vault Proxy persistent cache is currently supported only in a
Kubernetes environment.
## Vault Proxy Persistent Cache Types
Please see the sidebar for available types and their usage/configuration.
## Persistent Cache Example Configuration
Here is an example of a persistent cache configuration.
```hcl
# Other Vault Proxy configuration blocks
# ...
cache {
persist "kubernetes" {
path = "/vault/proxy-cache"
}
}
```

22
website/content/docs/agent-and-proxy/proxy/caching/persistent-caches/kubernetes.mdx Normal file
View File

@ -0,0 +1,22 @@
---
layout: docs
page_title: Kubernetes - Vault Proxy Persistent Cache
description: Kubernetes Persistent Cache for Vault Proxy Caching
---
# Vault Proxy Kubernetes Persistent Cache
When `kubernetes` is configured for the persistent cache type, Vault Proxy will optimize the
persistent cache specifically for Kubernetes. This type of persistent cache requires a Kubernetes
service account token. The service account token is used during encryption and decryption of the
persistent cache as an additional integrity check.
The Vault Proxy persistent cache file in Kubernetes should only be used for handing off Vault tokens
and leases between initialization and sidecar Vault Proxy containers. This cache file should be shared
using a memory volume between the Vault Proxy containers.
## Configuration
- `service_account_token_file` `(string: optional)` - When type is set to `kubernetes`,
this configures the path on disk where the Kubernetes service account token can be found.
Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`.

354
website/content/docs/agent-and-proxy/proxy/index.mdx Normal file
View File

@ -0,0 +1,354 @@
---
layout: docs
page_title: Vault Proxy
description: |-
Vault Proxy is a daemon that can be used to perform some Vault
functionality automatically, and act as a proxy for Vault's APIs.
---
# What is Vault Proxy?
Vault Proxy aims to remove the initial hurdle to adopt Vault by providing a
more scalable and simpler way for applications to integrate with Vault.
Vault Proxy acts as an [API Proxy][apiproxy] for Vault, and can optionally allow
or force interacting clients to use its [automatically authenticated token][autoauth].
Vault Proxy is a client daemon that provides the following features:
- [Auto-Auth][autoauth] - Automatically authenticate to Vault and manage the
token renewal process for locally-retrieved dynamic secrets.
- [API Proxy][apiproxy] - Acts as a proxy for Vault's API,
optionally using (or forcing the use of) the Auto-Auth token.
- [Caching][caching] - Allows client-side caching of responses containing newly
created tokens and responses containing leased secrets generated off of these
newly created tokens. The agent also manages the renewals of the cached tokens and leases.
## Auto-Auth
Vault Proxy allows easy authentication to Vault in a wide variety of
environments. Please see the [Auto-Auth docs][autoauth]
for information.
Auto-Auth functionality takes place within an `auto_auth` configuration stanza.
## API Proxy
Vault Proxy's primary purpose is to act as an API proxy for Vault, allowing you to talk to Vault's
API via a listener. It can be configured to optionally allow or force the automatic use of
the Auto-Auth token for these requests. Please see the [API Proxy docs][apiproxy]
for more information.
API Proxy functionality takes place within a defined `listener`, and its behaviour can be configured with an
[`api_proxy` stanza](/vault/docs/agent-and-proxy/proxy/apiproxy#configuration-api_proxy).
## Caching
Vault Proxy allows client-side caching of responses containing newly created tokens
and responses containing leased secrets generated off of these newly created tokens.
Please see the [Caching docs][caching] for information.
## API
### Quit
This endpoint triggers shutdown of the proxy. By default, it is disabled, and can
be enabled per listener using the [`agent_api`][agent-api] stanza. It is recommended
to only enable this on trusted interfaces, as it does not require any authorization to use.
| Method | Path |
| :----- | :--------------- |
| `POST` | `/proxy/v1/quit` |
### Cache
See the [caching](/vault/docs/agent-and-proxy/proxy/caching#api) page for details on the cache API.
## Configuration
### Command Options
- `-log-level` ((#\_log_level)) `(string: "info")` - Log verbosity level. Supported values (in
order of descending detail) are `trace`, `debug`, `info`, `warn`, and `error`. This can
also be specified via the `VAULT_LOG_LEVEL` environment variable.
- `-log-format` ((#\_log_format)) `(string: "standard")` - Log format. Supported values
are `standard` and `json`. This can also be specified via the
`VAULT_LOG_FORMAT` environment variable.
- `-log-file` ((#\_log_file)) - writes all the Vault proxy log messages
to a file. This value is used as a prefix for the log file name. The current timestamp
is appended to the file name. If the value ends in a path separator, `vault-proxy`
will be appended to the value. If the file name is missing an extension, `.log`
is appended. For example, setting `log-file` to `/var/log/` would result in a log
file path of `/var/log/vault-proxy-{timestamp}.log`. `log-file` can be combined with
[`-log-rotate-bytes`](#_log_rotate_bytes) and [`-log-rotate-duration`](#_log_rotate_duration)
for a fine-grained log rotation experience.
- `-log-rotate-bytes` ((#\_log_rotate_bytes)) - to specify the number of
bytes that should be written to a log before it needs to be rotated. Unless specified,
there is no limit to the number of bytes that can be written to a log file.
- `-log-rotate-duration` ((#\_log_rotate_duration)) - to specify the maximum
duration a log should be written to before it needs to be rotated. Must be a duration
value such as 30s. Defaults to 24h.
- `-log-rotate-max-files` ((#\_log_rotate_max_files)) - to specify the maximum
number of older log file archives to keep. Defaults to `0` (no files are ever deleted).
Set to `-1` to discard old log files when a new one is created.
### Configuration File Options
These are the currently-available general configuration options:
- `vault` <code>([vault][vault]: <optional\>)</code> - Specifies the remote Vault server the Proxy connects to.
- `auto_auth` <code>([auto_auth][autoauth]: <optional\>)</code> - Specifies the method and other options used for Auto-Auth functionality.
- `api_proxy` <code>([api_proxy][apiproxy]: <optional\>)</code> - Specifies options used for API Proxy functionality.
- `cache` <code>([cache][caching]: <optional\>)</code> - Specifies options used for Caching functionality.
- `listener` <code>([listener][listener]: <optional\>)</code> - Specifies the addresses and ports on which the Proxy will respond to requests.
~> **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof vault)`), Vault Proxy will attempt to reload listener TLS configuration.
This method can be used to refresh certificates used by Vault Proxy without having to restart its process.
- `pid_file` `(string: "")` - Path to the file in which the Proxy's Process ID
(PID) should be stored
- `exit_after_auth` `(bool: false)` - If set to `true`, the proxy will exit
with code `0` after a single successful auth, where success means that a
token was retrieved and all sinks successfully wrote it
- `disable_idle_connections` `(string array: [])` - A list of strings that disables idle connections for various features in Vault Proxy.
Valid values include: `auto-auth`, and `proxying`. Can also be configured by setting the `VAULT_PROXY_DISABLE_IDLE_CONNECTIONS`
environment variable as a comma separated string. This environment variable will override any values found in a configuration file.
- `disable_keep_alives` `(string array: [])` - A list of strings that disables keep alives for various features in Vault Agent.
Valid values include: `auto-auth`, and `proxying`. Can also be configured by setting the `VAULT_PROXY_DISABLE_KEEP_ALIVES`
environment variable as a comma separated string. This environment variable will override any values found in a configuration file.
- `template` <code>([template][template]: <optional\>)</code> - Specifies options used for templating Vault secrets to files.
- `template_config` <code>([template_config][template-config]: <optional\>)</code> - Specifies templating engine behavior.
- `telemetry` <code>([telemetry][telemetry]: <optional\>)</code> – Specifies the telemetry
reporting system. See the [telemetry Stanza](/vault/docs/agent-and-proxy/proxy#telemetry-stanza) section below
for a list of metrics specific to Proxy.
- `log_level` - Equivalent to the [`-log-level` command-line flag](#_log_level).
~> **Note:** On `SIGHUP` (`kill -SIGHUP $(pidof vault)`), Vault Proxy will update the log level to the value
specified by configuration file (including overriding values set using CLI or environment variable parameters).
- `log_format` - Equivalent to the [`-log-format` command-line flag](#_log_format).
- `log_file` - Equivalent to the [`-log-file` command-line flag](#_log_file).
- `log_rotate_duration` - Equivalent to the [`-log-rotate-duration` command-line flag](#_log_rotate_duration).
- `log_rotate_bytes` - Equivalent to the [`-log-rotate-bytes` command-line flag](#_log_rotate_bytes).
- `log_rotate_max_files` - Equivalent to the [`-log-rotate-max-files` command-line flag](#_log_rotate_max_files).
### vault Stanza
There can at most be one top level `vault` block, and it has the following
configuration entries:
- `address` `(string: <optional>)` - The address of the Vault server to
connect to. This should be a Fully Qualified Domain Name (FQDN) or IP
such as `https://vault-fqdn:8200` or `https://172.16.9.8:8200`.
This value can be overridden by setting the `VAULT_ADDR` environment variable.
- `ca_cert` `(string: <optional>)` - Path on the local disk to a single PEM-encoded
CA certificate to verify the Vault server's SSL certificate. This value can
be overridden by setting the `VAULT_CACERT` environment variable.
- `ca_path` `(string: <optional>)` - Path on the local disk to a directory of
PEM-encoded CA certificates to verify the Vault server's SSL certificate.
This value can be overridden by setting the `VAULT_CAPATH` environment
variable.
- `client_cert` `(string: <optional>)` - Path on the local disk to a single
PEM-encoded CA certificate to use for TLS authentication to the Vault server.
This value can be overridden by setting the `VAULT_CLIENT_CERT` environment
variable.
- `client_key` `(string: <optional>)` - Path on the local disk to a single
PEM-encoded private key matching the client certificate from `client_cert`.
This value can be overridden by setting the `VAULT_CLIENT_KEY` environment
variable.
- `tls_skip_verify` `(string: <optional>)` - Disable verification of TLS
certificates. Using this option is highly discouraged as it decreases the
security of data transmissions to and from the Vault server. This value can
be overridden by setting the `VAULT_SKIP_VERIFY` environment variable.
- `tls_server_name` `(string: <optional>)` - Name to use as the SNI host when
connecting via TLS. This value can be overridden by setting the
`VAULT_TLS_SERVER_NAME` environment variable.
#### retry Stanza
The `vault` stanza may contain a `retry` stanza that controls how failing Vault
requests are handled. Auto-auth, however, has its own notion of retrying and is not
affected by this section.
Here are the options for the `retry` stanza:
- `num_retries` `(int: 12)` - Specify how many times a failing request will
be retried. A value of `0` translates to the default, i.e. 12 retries.
A value of `-1` disables retries. The environment variable `VAULT_MAX_RETRIES`
overrides this setting.
Requests originating
from the proxy cache will only be retried if they resulted in specific HTTP
result codes: any 50x code except 501 ("not implemented"), as well as 412
("precondition failed"); 412 is used in Vault Enterprise 1.7+ to indicate a
stale read due to eventual consistency. Requests coming from the template
subsystem are retried regardless of the failure.
### listener Stanza
Vault Proxy supports one or more [listener][listener_main] stanzas. Listeners
can be configured with or without [caching][caching], but will use the cache if it
has been configured, and will enable the [API proxy][apiproxy]. In addition to the standard
listener configuration, a Proxy's listener configuration also supports the following:
- `require_request_header` `(bool: false)` - Require that all incoming HTTP
requests on this listener must have an `X-Vault-Request: true` header entry.
Using this option offers an additional layer of protection from Server Side
Request Forgery attacks. Requests on the listener that do not have the proper
`X-Vault-Request` header will fail, with a HTTP response status code of `412: Precondition Failed`.
- `role` `(string: default)` - `role` determines which APIs the listener serves.
It can be configured to `metrics_only` to serve only metrics, or the default role, `default`,
which serves everything (including metrics). The `require_request_header` does not apply
to `metrics_only` listeners.
- `proxy_api` <code>([proxy_api][proxy-api]: <optional\>)</code> - Manages optional Proxy API endpoints.
#### proxy_api Stanza
- `enable_quit` `(bool: false)` - If set to `true`, the Proxy will enable the [quit](/vault/docs/agent-and-proxy/proxy#quit) API.
### telemetry Stanza
Vault Proxy supports the [telemetry][telemetry] stanza and collects various
runtime metrics about its performance, the auto-auth and the cache status:
| Metric | Description | Type |
| -------------------------------- | ---------------------------------------------------- | ------- |
| `vault.proxy.auth.failure` | Number of authentication failures | counter |
| `vault.proxy.auth.success` | Number of authentication successes | counter |
| `vault.proxy.proxy.success` | Number of requests successfully proxied | counter |
| `vault.proxy.proxy.client_error` | Number of requests for which Vault returned an error | counter |
| `vault.proxy.proxy.error` | Number of requests the proxy failed to proxy | counter |
| `vault.proxy.cache.hit` | Number of cache hits | counter |
| `vault.proxy.cache.miss` | Number of cache misses | counter |
## Start Vault Proxy
To run Vault Proxy:
1. [Download](/vault/downloads) the Vault binary where the client application runs
(virtual machine, Kubernetes pod, etc.)
1. Create a Vault Proxy configuration file. (See the [Example
Configuration](#example-configuration) section for an example configuration.)
1. Start a Vault Proxy with the configuration file.
**Example:**
```shell-session
$ vault proxy -config=/etc/vault/proxy-config.hcl
```
To get help, run:
```shell-session
$ vault proxy -h
```
As with Vault, the `-config` flag can be used in three different ways:
- Use the flag once to name the path to a single specific configuration file.
- Use the flag multiple times to name multiple configuration files, which will be composed at runtime.
- Use the flag to name a directory of configuration files, the contents of which will be composed at runtime.
## Example Configuration
An example configuration, with very contrived values, follows:
```hcl
pid_file = "./pidfile"
vault {
address = "https://vault-fqdn:8200"
retry {
num_retries = 5
}
}
auto_auth {
method "aws" {
mount_path = "auth/aws-subaccount"
config = {
type = "iam"
role = "foobar"
}
}
sink "file" {
config = {
path = "/tmp/file-foo"
}
}
sink "file" {
wrap_ttl = "5m"
aad_env_var = "TEST_AAD_ENV"
dh_type = "curve25519"
dh_path = "/tmp/file-foo-dhpath2"
config = {
path = "/tmp/file-bar"
}
}
}
cache {
// An empty cache stanza still enables caching
}
api_proxy {
use_auto_auth_token = true
}
listener "unix" {
address = "/path/to/socket"
tls_disable = true
agent_api {
enable_quit = true
}
}
listener "tcp" {
address = "127.0.0.1:8100"
tls_disable = true
}
```
[vault]: /vault/docs/agent-and-proxy/proxy#vault-stanza
[autoauth]: /vault/docs/agent-and-proxy/proxy/autoauth
[caching]: /vault/docs/agent-and-proxy/proxy/caching
[apiproxy]: /vault/docs/agent-and-proxy/proxy/apiproxy
[persistent-cache]: /vault/docs/agent-and-proxy/proxy/caching/persistent-caches
[template]: /vault/docs/agent-and-proxy/proxy/template
[template-config]: /vault/docs/agent-and-proxy/proxy/template#template-configurations
[proxy-api]: /vault/docs/agent-and-proxy/proxy/#proxy_api-stanza
[listener]: /vault/docs/agent-and-proxy/proxy#listener-stanza
[listener_main]: /vault/docs/configuration/listener/tcp
[telemetry]: /vault/docs/configuration/telemetry

39
website/content/docs/agent-and-proxy/proxy/versions.mdx Normal file
View File

@ -0,0 +1,39 @@
---
layout: docs
page_title: Vault Proxy Version Compatibility
description: |-
Guidelines for running different versions of Proxy and Server
---
# Running different versions of Proxy and Server
There is no requirement to run identical versions of Vault Proxy and Vault Server.
It is safe to run different versions, however you may not be able to take advantage of all the newest features in Vault if you do not upgrade to the most recent versions of Proxy and Server. We recognize that this isn’t always possible, so we do support version mismatch as best as possible.
Proxy will write a note to its logs when it detects a mismatch between Proxy and Server. This is purely informative, intended to assist with debugging in case the mismatch is given rise to problems, e.g. because a newer Proxy version is trying to make use of functionality that doesn't exist in the Server version it's talking to. If Proxy is behaving acceptably, the message may be ignored.
This document describes the common cases. There may be occasional exceptions, which if intentional will be called out in the CHANGELOG in a `CHANGES` section. If unintentional/undocumented these should be treated as bugs and reported.
## Older version of Proxy than Server
We do not anticipate any problems stemming from continuing to run an older Proxy version after the server nodes are upgraded to a later version. Existing deployments using Proxy should not be impacted, as we don't generally make backwards-incompatible changes to Vault Server.
Auto-auth:
- new auth methods that have been introduced since Proxy was built will be unavailable
- existing auth methods should continue to function normally
Proxy:
- since Proxy simply mirrors the incoming requests, even if an incoming request uses an endpoint that didn't exist when that version of Proxy was compiled, that won't impede Proxy's ability to proxy the request
## Newer version of Proxy than Server
It is possible that an Proxy could depend on features that don’t exist in older Server versions.
Auto-auth:
- Proxy may claim to support newer auth methods that have been introduced since Server was built, but they won't work due to Server not supporting them
- Proxy may make use of new functionality for existing auth methods that isn't available in an older Server you're using
- Generally we will try to make such a change be opt-in, or to gracefully degrade when connecting to an older Server instance, unless there's a very good reason (such as a serious security flaw being patched)
Proxy:
- since Proxy simply mirrors the incoming requests, it is unlikely that incompatibilities would surface in proxying, but new functionality may not be available
- example: When client-controlled consistency support was added to Proxy, it started looking for X-Vault-Index headers in responses, and started providing X-Vault-Index headers in proxied requests. Older Vault Enterprise servers that don't make use of these headers would ignore the new request header and not emit them either. Proxy proxying behaviour continued unchanged, unable to take advantage of the new functionality, but also not impeded in its previously existing behavior.

9
website/content/docs/agent/autoauth/methods/index.mdx
View File

@ -1,9 +0,0 @@
---
layout: docs
page_title: Vault Agent Auto-Auth Methods
description: Methods for Vault Agent Auto-Auth
---
# Vault Agent Auto-Auth Methods
Please see the sidebar for available methods and their usage/configuration.

9
website/content/docs/agent/autoauth/sinks/index.mdx
View File

@ -1,9 +0,0 @@
---
layout: docs
page_title: Vault Agent Auto-Auth Sinks
description: Sinks for Vault Agent Auto-Auth
---
# Vault Agent Auto-Auth Sinks
Please see the sidebar for available sinks and their usage/configuration.

2
website/content/docs/concepts/client-count/index.mdx
View File

@ -25,7 +25,7 @@ There can be many different types of clients that authenticate and communicate w
2. **Applications or Microservices:** 2-Factor Authentication methods such as AppRole, or by LDAP, Active Directory, or based on the platform’s identity, such as credentials from AWS, Azure, GCP, AliCloud, OCI, Kubernetes, Cloud Foundry, etc.
3. **[Servers and Platforms](/vault/tutorials/recommended-patterns/pattern-centralized-secrets#machine-programmatic-authentication):** VMs, Containers, Pods (Identified by LDAP, Active Directory service accounts, AWS, Azure, GCP, AliCloud, OCI, Kubernetes, TLS Certs
4. **Orchestrators:** Nomad, Terraform, Ansible, or Continuous Integration Continuous Delivery (CI/CD) Pipelines where each pipeline usually identified by 2FA
5. **[Vault Agents](/vault/docs/agent/autoauth):** acting on behalf of a app/microservice, typically identified by App role, Cloud credentials, Kubernetes, TLS Certs
5. **[Vault Agents and Vault Proxies](/vault/docs/agent-and-proxy/autoauth):** acting on behalf of a app/microservice, typically identified by App role, Cloud credentials, Kubernetes, TLS Certs
6. **Tokens**: which are not tied to any identities at all. **_These should be used sparingly._**
Hashicorp recommends always associating tokens to an entity alias and token role.

2
website/content/docs/deprecation/index.mdx
View File

@ -34,7 +34,7 @@ This announcement page is maintained and updated periodically to communicate imp
| Optional `api_token` parameter in Okta Auth Method | v1.4 | 1.11 | v1.12 | The `api_token` parameter on the Okta Auth Method will change from being optional to being required. | [API Documentation](/vault/api-docs/auth/okta#api_token) |
| SHA-1 certificate signing | v1.11 | v1.11 | v1.12 | Go version 1.18 removes support for SHA-1 by default. As Vault updates its Go version to 1.18, you should plan to move off SHA-1 for certficate signing. Operators can set a Go [environmental variable](/vault/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1) to restore SHA-1 support if they need to continue using SHA-1. It is unknown at this time when Go will remove the environmental variable support. Therefore, we highly encourage you to migrate off of SHA-1 for certificate signing. |[FAQ](/vault/docs/deprecation/faq#q-what-is-the-impact-of-removing-support-for-x-509-certificates-with-signatures-that-use-sha-1)|
| Consul secrets engine parameter changes | v1.11 | N/A | N/A | The `policies` parameter on the Consul secrets engine has been changed in favor of `consul_policies`. The `token_type` and `policy` parameters have been deprecated as the latest versions of Consul no longer support the older ACL system they were used for. | [Consul secrets engine API documentation](/vault/api-docs/secret/consul) |
| Vault Agent API proxy support | v1.14 | v1.16 | v1.17 | Migrate to [Vault Proxy](/vault/docs/proxy/index) by v1.17|
*If you use **Standalone DB Engines** or **AppID (OSS)**, you should actively plan to migrate away from their usage. If you use these features and upgrade to Release 1.12, Vault will log error messages and shut down, and any attempts to add new mounts will result in an error.
This behavior may temporarily be overridden when starting the Vault server by using the `VAULT_ALLOW_PENDING_REMOVAL_MOUNTS` environment variable until they are officially removed in Vault version 1.13.

16
website/content/docs/enterprise/consistency.mdx
View File

@ -97,7 +97,7 @@ There are now a variety of other mitigations available:
- per-request option to conditionally forward the request to the active node
if it would otherwise result in a stale read
- per-request option to fail requests if they might result in a stale read
- Vault Agent configuration to do the above for proxied requests
- Vault Proxy configuration to do the above for proxied requests
The remainder of this document describes the tradeoffs of these mitigations and
how to use them.
@ -173,22 +173,22 @@ methods for propagating the X-Vault-Index response header into the request
header of subsequent requests. Those not using the Vault Go API will want
to build equivalent functionality into their client library.
### Vault Agent and consistency headers
### Vault Proxy and consistency headers
When configured, the [Vault Agent API Proxy](/vault/docs/agent/apiproxy) will proxy incoming requests to Vault. There is
Agent configuration available in the `api_proxy` stanza that allows making use
When configured, the [Vault API Proxy](/vault/docs/agent-and-proxy/proxy/apiproxy) will proxy incoming requests to Vault. There is
Proxy configuration available in the `api_proxy` stanza that allows making use
of some of the above mitigations without modifying clients.
By setting `enforce_consistency="always"`, Agent will always provide
By setting `enforce_consistency="always"`, Proxy will always provide
the `X-Vault-Index` consistency header. The value it uses for the header
will be based on the responses that have passed through the Agent previously.
will be based on the responses that have passed through the Proxy previously.
The option `when_inconsistent` controls how stale reads are prevented:
- `"fail"` means that when a `412` response is seen, it is returned to the client
- `"retry"` means that `412` responses will be retried automatically by Agent,
- `"retry"` means that `412` responses will be retried automatically by Proxy,
so the client doesn't have to deal with them
- `"forward"` makes Agent provide the
- `"forward"` makes Proxy provide the
`X-Vault-Inconsistent: forward-active-node` header as described above under
Conditional Forwarding

2
website/content/docs/partnerships.mdx
View File

@ -46,7 +46,7 @@ HSM (Hardware Security Module) are specific types of runtime integrations and ca
**Secrets Engines**: Secrets engines are plugin components which store, generate, or encrypt data. Secrets engines are provided with some set of data, that take some action on that data, and then return a result. Some secrets engines store and read data, like encrypted in-memory data structure, other secrets engines connect to other services. Examples of Secrets Engines include identity modules of Cloud providers like AWS, Azure IAM models, Cloud (LDAP), database or certificate management. You can find more information about Vault Secrets Engines [here](/vault/docs/secrets/).
-> **Note:** Integrations related Vault’s [storage](/vault/docs/concepts/storage) backend, [auto auth](/vault/docs/agent/autoauth), and [auto unseal](/vault/docs/concepts/seal#auto-unseal) functionality are not encouraged. Please reach out to [technologypartners@hashicorp.com](mailto:technologypartners@hashicorp.com) for any questions related to this.
-> **Note:** Integrations related Vault’s [storage](/vault/docs/concepts/storage) backend, [auto auth](/vault/docs/agent-and-proxy/autoauth), and [auto unseal](/vault/docs/concepts/seal#auto-unseal) functionality are not encouraged. Please reach out to [technologypartners@hashicorp.com](mailto:technologypartners@hashicorp.com) for any questions related to this.
### HCP Vault

4
website/content/docs/platform/k8s/helm/configuration.mdx
View File

@ -100,11 +100,11 @@ and consider if they're appropriate for your deployment.
- `template` (`string: "map"`) - The default template type for rendered secrets if no custom templates are defined.
Possible values include `map` and `json`.
- `templateConfig` - Default values within Agent's [`template_config` stanza](/vault/docs/agent/template).
- `templateConfig` - Default values within Agent's [`template_config` stanza](/vault/docs/agent-and-proxy/agent/template).
- `exitOnRetryFailure` (`boolean: true`) - Controls whether Vault Agent exits after it has exhausted its number of template retry attempts due to failures.
- `staticSecretRenderInterval` (`string: ""`) - Configures how often Vault Agent Template should render non-leased secrets such as KV v2. See the [Vault Agent Templates documentation] (/docs/agent/template#non-renewable-secrets) for more details.
- `staticSecretRenderInterval` (`string: ""`) - Configures how often Vault Agent Template should render non-leased secrets such as KV v2. See the [Vault Agent Templates documentation](/vault/docs/agent-and-proxy/agent/template#non-renewable-secrets) for more details.
- `metrics` - Values that configure the Vault Agent Injector metric exporter.

4
website/content/docs/platform/k8s/injector-csi.mdx
View File

@ -81,7 +81,7 @@ Now that you understand the similarities, there are differences between these tw
- In contrast, the Vault CSI Driver is deployed as a daemonset on every node in the Kubernetes cluster and uses the Secret Provider Class specified and the pod’s service account to retrieve the secrets from Vault and mount them into the pod’s CSI volume.
- The Sidecar Agent Injector supports [all](/vault/docs/platform/k8s/injector/annotations#vault-hashicorp-com-auth-path) Vault [auto-auth](/vault/docs/agent/autoauth/methods) methods. The Sidecar CSI driver supports only Vault’s [Kubernetes auth method](/vault/docs/platform/k8s/csi/configurations#vaultkubernetesmountpath).
- The Sidecar Agent Injector supports [all](/vault/docs/platform/k8s/injector/annotations#vault-hashicorp-com-auth-path) Vault [auto-auth](/vault/docs/agent-and-proxy/autoauth/methods) methods. The Sidecar CSI driver supports only Vault’s [Kubernetes auth method](/vault/docs/platform/k8s/csi/configurations#vaultkubernetesmountpath).
- The Sidecar container launched with every application pod uses [Vault Agent](https://www.hashicorp.com/blog/why-use-the-vault-agent-for-secrets-management), which provides a powerful set of capabilities such as auto-auth, templating, and caching. The CSI driver does not use the Vault Agent and therefore lacks these functionalities.
@ -89,7 +89,7 @@ Now that you understand the similarities, there are differences between these tw
- The CSI driver uses `hostPath` to mount ephemeral volumes into the pods, which some container platforms (e.g., OpenShift) disable by default. On the other hand, Sidecar Agent Service uses in-memory _tmpfs_ volumes.
- Sidecar Injector Service [automatically](/vault/docs/agent/template#renewals-and-updating-secrets) renews, rotates, and fetches secrets/tokens while the CSI Driver does not support that.
- Sidecar Injector Service [automatically](/vault/docs/agent-and-proxy/agent/template#renewals-and-updating-secrets) renews, rotates, and fetches secrets/tokens while the CSI Driver does not support that.
## Comparison chart

22
website/content/docs/platform/k8s/injector/annotations.mdx
View File

@ -95,11 +95,11 @@ them, optional commands to run, etc.
- `vault.hashicorp.com/template-config-exit-on-retry-failure` - controls whether
Vault Agent exits after it has exhausted its number of template retry attempts
due to failures. Defaults to `true`. See [Vault Agent Template
Config](/vault/docs/agent/template#template-configurations) for more details.
Config](/vault/docs/agent-and-proxy/agent/template#template-configurations) for more details.
- `vault.hashicorp.com/template-static-secret-render-interval` - If specified,
configures how often Vault Agent Template should render non-leased secrets such as KV v2.
See [Vault Agent Template Config](/vault/docs/agent/template#template-configurations) for more details.
See [Vault Agent Template Config](/vault/docs/agent-and-proxy/agent/template#template-configurations) for more details.
- `vault.hashicorp.com/agent-extra-secret` - mounts Kubernetes secret as a volume at
`/vault/custom` in the sidecar/init containers. Useful for custom Agent configs with
@ -197,7 +197,7 @@ them, optional commands to run, etc.
Defaults to `false`.
- `vault.hashicorp.com/agent-cache-enable` - configures Vault Agent to enable
[caching](/vault/docs/agent/caching). In Vault 1.7+ this annotation will also enable
[caching](/vault/docs/agent-and-proxy/agent/caching). In Vault 1.7+ this annotation will also enable
a Vault Agent persistent cache. This persistent cache will be shared between the init
and sidecar container to reuse tokens and leases retrieved by the init container.
Defaults to `false`.
@ -215,7 +215,7 @@ them, optional commands to run, etc.
- `vault.hashicorp.com/agent-service-account-token-volume-name` - the optional name of a projected volume containing a service account token for use with auto-auth against Vault's Kubernetes auth method. If the volume is mounted to another container in the deployment, the token volume will be mounted to the same location in the vault-agent containers. Otherwise it will be mounted at the default location of `/var/run/secrets/vault.hashicorp.com/serviceaccount/`.
- `vault.hashicorp.com/agent-enable-quit` - enable the [`/agent/v1/quit` endpoint](/vault/docs/agent#quit) on an injected agent. This option defaults to false, and if true will be set on the existing cache listener, or a new localhost listener with a basic cache stanza configured. The [agent-cache-listener-port annotation](/vault/docs/platform/k8s/injector/annotations#vault-hashicorp-com-agent-cache-listener-port) can be used to change the port.
- `vault.hashicorp.com/agent-enable-quit` - enable the [`/agent/v1/quit` endpoint](/vault/docs/agent-and-proxy/agent#quit) on an injected agent. This option defaults to false, and if true will be set on the existing cache listener, or a new localhost listener with a basic cache stanza configured. The [agent-cache-listener-port annotation](/vault/docs/platform/k8s/injector/annotations#vault-hashicorp-com-agent-cache-listener-port) can be used to change the port.
- `vault.hashicorp.com/agent-telemetry` - specifies the [telemetry](/vault/docs/configuration/telemetry) configuration for the
Vault Agent sidecar. The name of the config is any unique string after
@ -244,20 +244,20 @@ etc.
This annotation can be reused multiple times to configure multiple settings for the authentication
method. Some authentication methods may require additional secrets and should be mounted via the
`vault.hashicorp.com/agent-extra-secret` annotation. For a list of valid authentication configurations,
see the Vault Agent [auto-auth documentation](/vault/docs/agent/autoauth/methods).
see the Vault Agent [auto-auth documentation](/vault/docs/agent-and-proxy/autoauth/methods).
- `vault.hashicorp.com/auth-path` - configures the authentication path for the Kubernetes
auth method. Defaults to `auth/kubernetes`.
- `vault.hashicorp.com/auth-type` - configures the authentication type for Vault Agent.
Defaults to `kubernetes`. For a list of valid authentication methods, see the Vault Agent
[auto-auth documentation](/vault/docs/agent/autoauth/methods).
[auto-auth documentation](/vault/docs/agent-and-proxy/autoauth/methods).
- `vault.hashicorp.com/auth-min-backoff` - set the [min_backoff](/vault/docs/agent/autoauth#min_backoff) option in the auto-auth config. Requires Vault 1.11+.
- `vault.hashicorp.com/auth-min-backoff` - set the [min_backoff](/vault/docs/agent-and-proxy/autoauth#min_backoff) option in the auto-auth config. Requires Vault 1.11+.
- `vault.hashicorp.com/auth-max-backoff` - set the [max_backoff](/vault/docs/agent/autoauth#max_backoff) option in the auto-auth config
- `vault.hashicorp.com/auth-max-backoff` - set the [max_backoff](/vault/docs/agent-and-proxy/autoauth#max_backoff) option in the auto-auth config
- `vault.hashicorp.com/agent-auto-auth-exit-on-err` - set the [exit_on_err](/vault/docs/agent/autoauth#exit_on_err) option in the auto-auth config
- `vault.hashicorp.com/agent-auto-auth-exit-on-err` - set the [exit_on_err](/vault/docs/agent-and-proxy/autoauth#exit_on_err) option in the auto-auth config
- `vault.hashicorp.com/ca-cert` - path of the CA certificate used to verify Vault's
TLS.
@ -314,14 +314,14 @@ etc.
value to true in a production environment.
- `vault.hashicorp.com/agent-disable-idle-connections` - Comma-separated [list
of Vault Agent features](/vault/docs/agent#disable_idle_connections) where idle
of Vault Agent features](/vault/docs/agent-and-proxy/agent#disable_idle_connections) where idle
connections should be disabled. Also available as a command-line option
(`-disable-idle-connections`) or environment variable
(`AGENT_INJECT_DISABLE_IDLE_CONNECTIONS`) to set the default for all injected
Agents.
- `vault.hashicorp.com/agent-disable-keep-alives` - Comma-separated [list of
Vault Agent features](/vault/docs/agent#disable_keep_alives) where keep-alives
Vault Agent features](/vault/docs/agent-and-proxy/agent#disable_keep_alives) where keep-alives
should be disabled. Also available as a command-line option
(`-disable-keep-alives`) or environment variable
(`AGENT_INJECT_DISABLE_KEEP_ALIVES`) to set the default for all injected

2
website/content/docs/platform/k8s/injector/examples.mdx
View File

@ -144,7 +144,7 @@ spec:
The following example creates a deployment that mounts a Kubernetes ConfigMap
containing Vault Agent configuration files. For a complete list of the Vault
Agent configuration settings, [see the Agent documentation](/vault/docs/agent/template#vault-agent-templates).
Agent configuration settings, [see the Agent documentation](/vault/docs/agent-and-proxy/agent/template#vault-agent-templates).
```yaml
---

4
website/content/docs/platform/k8s/injector/index.mdx
View File

@ -10,7 +10,7 @@ description: >-
The Vault Agent Injector alters pod specifications to include Vault Agent
containers that render Vault secrets to a shared memory volume using
[Vault Agent Templates](/vault/docs/agent/template).
[Vault Agent Templates](/vault/docs/agent-and-proxy/agent/template).
By rendering secrets to a shared volume, containers within the pod can consume
Vault secrets without being Vault aware.
@ -174,7 +174,7 @@ username: v-kubernet-pg-app-q0Z7WPfVNqqTJuoDqCTY-1576529094
### Renewals and Updating Secrets
For more information on when Vault Agent fetches and renews secrets, see the
[Agent documentation](/vault/docs/agent/template#renewals-and-updating-secrets).
[Agent documentation](/vault/docs/agent-and-proxy/agent/template#renewals-and-updating-secrets).
### Vault Agent Configuration Map

4
website/content/docs/platform/servicenow/installation.mdx
View File

@ -15,7 +15,7 @@ description: Installation steps for the Vault ServiceNow Credential Resolver.
## Installing Vault Agent
* Select your desired auth method from Agent's [supported auth methods](/vault/docs/agent/autoauth/methods)
* Select your desired auth method from Agent's [supported auth methods](/vault/docs/agent-and-proxy/autoauth/methods)
and set it up in Vault
* For example, to set up AppRole auth and a role called `role1` with the `demo` policy attached:
@ -65,7 +65,7 @@ description: Installation steps for the Vault ServiceNow Credential Resolver.
```
* Install Vault Agent as a service running `vault agent -config=/path/to/agent.hcl`
* Documentation for Windows service installation [here](/vault/docs/agent/winsvc)
* Documentation for Windows service installation [here](/vault/docs/agent-and-proxy/agent/winsvc)
## Uploading JAR file to MID server

2
website/content/docs/secrets/pki/considerations.mdx
View File

@ -430,7 +430,7 @@ between OCSP and CRLs.
To manage certificates for services at scale, it is best to automate the
certificate renewal as much as possible. Vault Agent [has support for
automatically renewing requested certificates](/vault/docs/agent/template#certificates)
automatically renewing requested certificates](/vault/docs/agent-and-proxy/agent/template#certificates)
based on the `validTo` field. Other solutions might involve using
[cert-manager](https://cert-manager.io/) in Kubernetes or OpenShift, backed
by the Vault CA.

98
website/data/docs-nav-data.json
View File

@ -884,73 +884,73 @@
]
},
{
"title": "Vault Agent",
"title": "Vault Agent and Vault Proxy",
"routes": [
{
"title": "Overview",
"path": "agent"
"path": "agent-and-proxy"
},
{
"title": "Auto-Auth",
"routes": [
{
"title": "Overview",
"path": "agent/autoauth"
"path": "agent-and-proxy/autoauth"
},
{
"title": "Methods",
"routes": [
{
"title": "Overview",
"path": "agent/autoauth/methods"
"path": "agent-and-proxy/autoauth/methods"
},
{
"title": "AliCloud",
"path": "agent/autoauth/methods/alicloud"
"path": "agent-and-proxy/autoauth/methods/alicloud"
},
{
"title": "AppRole",
"path": "agent/autoauth/methods/approle"
"path": "agent-and-proxy/autoauth/methods/approle"
},
{
"title": "AWS",
"path": "agent/autoauth/methods/aws"
"path": "agent-and-proxy/autoauth/methods/aws"
},
{
"title": "Azure",
"path": "agent/autoauth/methods/azure"
"path": "agent-and-proxy/autoauth/methods/azure"
},
{
"title": "Cert",
"path": "agent/autoauth/methods/cert"
"path": "agent-and-proxy/autoauth/methods/cert"
},
{
"title": "CF",
"path": "agent/autoauth/methods/cf"
"path": "agent-and-proxy/autoauth/methods/cf"
},
{
"title": "GCP",
"path": "agent/autoauth/methods/gcp"
"path": "agent-and-proxy/autoauth/methods/gcp"
},
{
"title": "JWT",
"path": "agent/autoauth/methods/jwt"
"path": "agent-and-proxy/autoauth/methods/jwt"
},
{
"title": "Kerberos",
"path": "agent/autoauth/methods/kerberos"
"path": "agent-and-proxy/autoauth/methods/kerberos"
},
{
"title": "Kubernetes",
"path": "agent/autoauth/methods/kubernetes"
"path": "agent-and-proxy/autoauth/methods/kubernetes"
},
{
"title": "Oracle Cloud Infrastructure",
"path": "agent/autoauth/methods/oci"
"path": "agent-and-proxy/autoauth/methods/oci"
},
{
"title": "Token File",
"path": "agent/autoauth/methods/token_file"
"path": "agent-and-proxy/autoauth/methods/token_file"
}
]
},
@ -959,37 +959,83 @@
"routes": [
{
"title": "Overview",
"path": "agent/autoauth/sinks"
"path": "agent-and-proxy/autoauth/sinks"
},
{
"title": "File",
"path": "agent/autoauth/sinks/file"
"path": "agent-and-proxy/autoauth/sinks/file"
}
]
}
]
},
{
"title": "Vault Proxy",
"routes": [
{
"title": "Overview",
"path": "agent-and-proxy/proxy"
},
{
"title": "API Proxy",
"path": "agent/apiproxy"
"path": "agent-and-proxy/proxy/apiproxy"
},
{
"title": "Caching",
"routes": [
{
"title": "Overview",
"path": "agent/caching"
"path": "agent-and-proxy/proxy/caching"
},
{
"title": "Persistent Caching",
"routes": [
{
"title": "Overview",
"path": "agent/caching/persistent-caches"
"path": "agent-and-proxy/proxy/caching/persistent-caches"
},
{
"title": "Kubernetes",
"path": "agent/caching/persistent-caches/kubernetes"
"path": "agent-and-proxy/proxy/caching/persistent-caches/kubernetes"
}
]
}
]
},
{
"title": "Version compatibility",
"path": "agent-and-proxy/proxy/versions"
}
]
},
{
"title": "Vault Agent",
"routes": [
{
"title": "Overview",
"path": "agent-and-proxy/agent"
},
{
"title": "API Proxy",
"path": "agent-and-proxy/agent/apiproxy"
},
{
"title": "Caching",
"routes": [
{
"title": "Overview",
"path": "agent-and-proxy/agent/caching"
},
{
"title": "Persistent Caching",
"routes": [
{
"title": "Overview",
"path": "agent-and-proxy/agent/caching/persistent-caches"
},
{
"title": "Kubernetes",
"path": "agent-and-proxy/agent/caching/persistent-caches/kubernetes"
}
]
}
@ -997,15 +1043,17 @@
},
{
"title": "Templates",
"path": "agent/template"
"path": "agent-and-proxy/agent/template"
},
{
"title": "Windows service",
"path": "agent/winsvc"
"path": "agent-and-proxy/agent/winsvc"
},
{
"title": "Version compatibility",
"path": "agent/versions"
"path": "agent-and-proxy/agent/versions"
}
]
}
]
},

BIN
website/public/img/vault-agent-workflow.png (Stored with Git LFS) Normal file
View File

Binary file not shown.

45
website/redirects.js
View File

@ -14,5 +14,50 @@ module.exports = [
source: '/vault/docs/plugins/plugin-portal',
destination: '/vault/integrations',
permanent: true,
},
{
source: '/vault/docs/agent/autoauth',
destination: '/vault/docs/agent-and-proxy/autoauth',
permanent: true,
},
{
source: '/vault/docs/agent/autoauth/:slug',
destination: '/vault/docs/agent-and-proxy/autoauth/:slug',
permanent: true,
},
{
source: '/vault/docs/agent/template',
destination: '/vault/docs/agent-and-proxy/agent/template',
permanent: true,
},
{
source: '/vault/docs/agent/winsvc',
destination: '/vault/docs/agent-and-proxy/agent/winsvc',
permanent: true,
},
{
source: '/vault/docs/agent/versions',
destination: '/vault/docs/agent-and-proxy/agent/versions',
permanent: true,
},
{
source: '/vault/docs/agent/apiproxy',
destination: '/vault/docs/agent-and-proxy/agent/apiproxy',
permanent: true,
},
{
source: '/vault/docs/agent',
destination: '/vault/docs/agent-and-proxy/agent',
permanent: true,
},
{
source: '/vault/docs/agent/caching',
destination: '/vault/docs/agent-and-proxy/agent/caching',
permanent: true,
},
{
source: '/vault/docs/agent/caching/:slug',
destination: '/vault/docs/agent-and-proxy/agent/caching/:slug',
permanent: true,
}
]