scottk/vault
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/vault.git synced 2025-11-02 03:27:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* 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 d054ede7b3
commit f48c70a449
48 changed files with 1259 additions and 331 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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.