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 for Vault, and can optionally allow or force interacting clients to use its automatically authenticated token.
Vault Proxy is a client daemon that provides the following features:
Auto-Auth - Automatically authenticate to Vault and manage the token renewal process for locally-retrieved dynamic secrets.
API Proxy - Acts as a proxy for Vault's API, optionally using (or forcing the use of) the Auto-Auth token.
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 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 for more information.
API Proxy functionality takes place within a defined listener
, and its behaviour can be configured with an api_proxy
stanza.
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 for information.
API
Quit
This endpoint triggers shutdown of the proxy. By default, it is disabled, and can be enabled per listener using the proxy_api
stanza. It is recommended to only enable this on trusted interfaces, as it does not require any authorization to use.
Method | Path |
---|---|
|
|
Cache
See the caching page for details on the cache API.
Configuration
Command options
-log-level
(string: "info")
- Log verbosity level. Supported values (in order of descending detail) aretrace
,debug
,info
,warn
, anderror
. This can also be specified via theVAULT_LOG_LEVEL
environment variable.-log-format
(string: "standard")
- Log format. Supported values arestandard
andjson
. This can also be specified via theVAULT_LOG_FORMAT
environment variable.-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, settinglog-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
and-log-rotate-duration
for a fine-grained log rotation experience.-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
- 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
- to specify the maximum number of older log file archives to keep. Defaults to0
(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
(vault: <optional>)
- Specifies the remote Vault server the Proxy connects to.auto_auth
(auto_auth: <optional>)
- Specifies the method and other options used for Auto-Auth functionality.api_proxy
(api_proxy: <optional>)
- Specifies options used for API Proxy functionality.cache
(cache: <optional>)
- Specifies options used for Caching functionality.listener
(listener: <optional>)
- 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 storedexit_after_auth
(bool: false)
- If set totrue
, the proxy will exit with code0
after a single successful auth, where success means that a token was retrieved and all sinks successfully wrote itdisable_idle_connections
(string array: [])
- A list of strings that disables idle connections for various features in Vault Proxy. Valid values include:auto-auth
, andproxying
. Can also be configured by setting theVAULT_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
, andproxying
. Can also be configured by setting theVAULT_PROXY_DISABLE_KEEP_ALIVES
environment variable as a comma separated string. This environment variable will override any values found in a configuration file.template
(template: <optional>)
- Specifies options used for templating Vault secrets to files.template_config
(template_config: <optional>)
- Specifies templating engine behavior.telemetry
(telemetry: <optional>)
– Specifies the telemetry reporting system. See the telemetry Stanza section below for a list of metrics specific to Proxy.log_level
- Equivalent to the-log-level
command-line flag.
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_file
- Equivalent to the-log-file
command-line flag.log_rotate_duration
- Equivalent to the-log-rotate-duration
command-line flag.log_rotate_bytes
- Equivalent to the-log-rotate-bytes
command-line flag.log_rotate_max_files
- Equivalent to the-log-rotate-max-files
command-line flag.
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 ashttps://vault-fqdn:8200
orhttps://172.16.9.8:8200
. This value can be overridden by setting theVAULT_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 theVAULT_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 theVAULT_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 theVAULT_CLIENT_CERT
environment variable.client_key
(string: <optional>)
- Path on the local disk to a single PEM-encoded private key matching the client certificate fromclient_cert
. This value can be overridden by setting theVAULT_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 theVAULT_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 theVAULT_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 of0
translates to the default, i.e. 12 retries. A value of-1
disables retries. The environment variableVAULT_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"); Requests coming from the template subsystem are retried regardless of the failure.
listener stanza
Vault Proxy supports one or more listener stanzas. Listeners can be configured with or without caching, but will use the cache if it has been configured, and will enable the API proxy. 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 anX-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 properX-Vault-Request
header will fail, with a HTTP response status code of412: Precondition Failed
.role
(string: default)
-role
determines which APIs the listener serves. It can be configured tometrics_only
to serve only metrics, or the default role,default
, which serves everything (including metrics). Therequire_request_header
does not apply tometrics_only
listeners.proxy_api
(proxy_api: <optional>)
- Manages optional Proxy API endpoints.
proxy_api stanza
enable_quit
(bool: false)
- If set totrue
, the Proxy will enable the quit API.
telemetry stanza
Vault Proxy supports the telemetry stanza and collects various runtime metrics about its performance, the auto-auth and the cache status:
Metric | Description | Type |
---|---|---|
| Number of authentication failures | counter |
| Number of authentication successes | counter |
| Number of requests successfully proxied | counter |
| Number of requests for which Vault returned an error | counter |
| Number of requests the proxy failed to proxy | counter |
| Number of cache hits | counter |
| Number of cache misses | counter |
Start Vault proxy
To run Vault Proxy:
Download the Vault binary where the client application runs (virtual machine, Kubernetes pod, etc.)
Create a Vault Proxy configuration file. (See the Example Configuration section for an example configuration.)
Start a Vault Proxy with the configuration file.
Example:
To get help, run:
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:
Last updated