Vault Agent aims to remove the initial hurdle to adopt Vault by providing amore scalable and simpler way for applications to integrate with Vault, byproviding the ability to render templates containing the secretsrequired by your application, without requiring changes to your application.
Vault Agent is a client daemon that provides the following features:
- Auto-Auth - Automatically authenticate to Vault and manage thetoken renewal process for locally-retrieved dynamic secrets.
- API Proxy - Allows Vault Agent to act 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 newlycreated tokens and responses containing leased secrets generated off of thesenewly created tokens. The agent also manages the renewals of the cached tokens and leases.
- Windows Service - Allows running the Vault Agent as a Windowsservice.
- Templating - Allows rendering of user-supplied templates by VaultAgent, using the token generated by the Auto-Auth step.
- Process Supervisor Mode - Runs a child process with Vaultsecrets injected as environment variables.
Vault Agent allows easy authentication to Vault in a wide variety ofenvironments. Please see the Auto-Auth docsfor information.
Auto-Auth functionality takes place within an auto_auth
configuration stanza.
API proxy
Vault Agent can act as an API proxy for Vault, allowing you to talk to Vault'sAPI via a listener defined for Agent. It can be configured to optionally allow or force the automatic use ofthe Auto-Auth token for these requests. Please see the API Proxy docsfor more information.
API Proxy functionality takes place within a defined listener
, and its behaviour can be configured with anapi_proxy stanza.
Vault Agent allows client-side caching of responses containing newly created tokensand 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 agent. By default, it is disabled, and canbe enabled per listener using the agent_api stanza. It is recommendedto only enable this on trusted interfaces, as it does not require any authorization to use.
Method | Path |
---|---|
POST | /agent/v1/quit |
Cache
See the caching page for details on the cache API.
Command options
-log-level
(string: "info")
- Log verbosity level. Supported values (inorder of descending detail) aretrace
,debug
,info
,warn
, anderror
. This canalso be specified via theVAULT_LOG_LEVEL
environment variable.-log-format
(string: "standard")
- Log format. Supported valuesarestandard
andjson
. This can also be specified via theVAULT_LOG_FORMAT
environment variable.-log-file - the absolute path where Vault Agent should savelog messages. Paths that end with a path separator use the default file name,
agent.log
. Paths that do not end with a file extension use the default.log
extension. If the log file rotates, Vault Agent appends the currenttimestamp to the file name at the time of rotation. For example:log-file
Full log file Rotated log file /var/log
/var/log/agent.log
/var/log/agent-{timestamp}.log
/var/log/my-diary
/var/log/my-diary.log
/var/log/my-diary-{timestamp}.log
/var/log/my-diary.txt
/var/log/my-diary.txt
/var/log/my-diary-{timestamp}.txt
-log-rotate-bytes - to specify the number ofbytes 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 maximumduration a log should be written to before it needs to be rotated. Must be a durationvalue such as 30s. Defaults to 24h.
-log-rotate-max-files - to specify the maximumnumber 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
(vault: <optional>)
- Specifies the remote Vault server the Agent 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 Agent will respond to requests.Note: On
SIGHUP
(kill -SIGHUP $(pidof vault)
), Vault Agent will attempt to reload listener TLS configuration.This method can be used to refresh certificates used by Vault Agent without having to restart its process.pid_file
(string: "")
- Path to the file in which the agent's Process ID(PID) should be storedexit_after_auth
(bool: false)
- If set totrue
, the agent will exitwith code0
after a single successful auth, where success means that atoken was retrieved and all sinks successfully wrote it. If you havetemplate
stanzas defined in your agent configuration, the agentwaits for the configured templates to render successfully beforeexiting. If you use environment templates (env_template
) and setexit_after_auth
to true, Vault agent will not run the child processesdefined in yourexec
stanza.disable_idle_connections
(string array: [])
- A list of strings that disables idle connections for various features in Vault Agent.Valid values include:auto-auth
,caching
,proxying
, andtemplating
.proxying
configures this for the API proxy, which isidentical in function tocaching
for historical reasons. Can also be configured by setting theVAULT_AGENT_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
,caching
,proxying
, andtemplating
.proxying
configures this for the API proxy, which isidentical in function tocaching
for historical reasons. Can also be configured by setting theVAULT_AGENT_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.exec
(exec: <optional>)
- Specifies options for vault agent to run a child processthat injects secrets (viaenv_template
stanzas) as environment variables.env_template
(env_template: <optional>)
- Multiple blocks accepted. Each block containsthe options used for templating Vault secrets as environment variables via theprocess supervisor mode.telemetry
(telemetry: <optional>)
– Specifies the telemetryreporting system. See the telemetry Stanza section belowfor a list of metrics specific to Agent.log_level - Equivalent to the -log-level command-line flag.
Note: On
SIGHUP
(kill -SIGHUP $(pidof vault)
), Vault Agent will update the log level to the valuespecified 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 followingconfiguration entries:
address
(string: <optional>)
- The address of the Vault server toconnect to. This should be a Fully Qualified Domain Name (FQDN) or IPsuch 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-encodedCA certificate to verify the Vault server's SSL certificate. This value canbe overridden by setting theVAULT_CACERT
environment variable.ca_path
(string: <optional>)
- Path on the local disk to a directory ofPEM-encoded CA certificates to verify the Vault server's SSL certificate.This value can be overridden by setting theVAULT_CAPATH
environmentvariable.client_cert
(string: <optional>)
- Path on the local disk to a singlePEM-encoded CA certificate to use for TLS authentication to the Vault server.This value can be overridden by setting theVAULT_CLIENT_CERT
environmentvariable.client_key
(string: <optional>)
- Path on the local disk to a singlePEM-encoded private key matching the client certificate fromclient_cert
.This value can be overridden by setting theVAULT_CLIENT_KEY
environmentvariable.tls_skip_verify
(string: <optional>)
- Disable verification of TLScertificates. Using this option is highly discouraged as it decreases thesecurity of data transmissions to and from the Vault server. This value canbe overridden by setting theVAULT_SKIP_VERIFY
environment variable.tls_server_name
(string: <optional>)
- Name to use as the SNI host whenconnecting via TLS. This value can be overridden by setting theVAULT_TLS_SERVER_NAME
environment variable.namespace
(string: <optional>)
- Namespace to use for all of Vault Agent'srequests to Vault. This can also be specified by command line or environment variable.The order of precedence is: this setting lowest, followed by the environment variableVAULT_NAMESPACE
, and then the highest precedence command-line option-namespace
.If none of these are specified, defaults to the root namespace.
retry stanza
The vault
stanza may contain a retry
stanza that controls how failing Vaultrequests are handled, whether these requests are issued in order to rendertemplates, or are proxied requests coming from the api proxy subsystem.Auto-auth, however, has its own notion of retrying and is not affected by thissection.
For requests from the templating engine, Vaul Agent will reset its retry counter andperform retries again once all retries are exhausted. This means that templatingwill retry on failures indefinitely unless exit_on_retry_failure
from thetemplate_config stanza is set to true
.
Here are the options for the retry
stanza:
- num_retries
(int: 12)
- Specify how many times a failing request willbe 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.
There are a few subtleties to be aware of here. First, requests originatingfrom the proxy cache will only be retried if they resulted in specific HTTPresult codes: any 50x code except 501 ("not implemented"), as well as 412("precondition failed"); 412 is used in Vault Enterprise 1.7+ to indicate astale read due to eventual consistency. Requests coming from the templatesubsystem are retried regardless of the failure.
Second, templating retries may be performed by both the templating engine andthe cache proxy if Vault Agent persistentcache is enabled. This is due to thefact that templating requests go through the cache proxy when persistence isenabled.
Third, the backoff algorithm used to set the time between retries differs forthe template and cache subsystems. This is a technical limitation we hopeto address in the future.
listener stanza
Vault Agent supports one or more listener stanzas. Listenerscan be configured with or without caching, but will use the cache if ithas been configured, and will enable the API proxy. In addition to the standardlistener configuration, an Agent's listener configuration also supports the following:
require_request_header
(bool: false)
- Require that all incoming HTTPrequests on this listener must have anX-Vault-Request: true
header entry.Using this option offers an additional layer of protection from Server SideRequest 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 applytometrics_only
listeners.agent_api
(agent_api: <optional>)
- Manages optional Agent API endpoints.
agent_api stanza
- enable_quit
(bool: false)
- If set totrue
, the agent will enable the quit API.
telemetry stanza
Vault Agent supports the telemetry stanza and collects variousruntime metrics about its performance, the auto-auth and the cache status:
Metric | Description | Type |
---|---|---|
vault.agent.auth.failure | Number of authentication failures | counter |
vault.agent.auth.success | Number of authentication successes | counter |
vault.agent.proxy.success | Number of requests successfully proxied | counter |
vault.agent.proxy.client_error | Number of requests for which Vault returned an error | counter |
vault.agent.proxy.error | Number of requests the agent failed to proxy | counter |
vault.agent.cache.hit | Number of cache hits | counter |
vault.agent.cache.miss | Number of cache misses | counter |
Start Vault agent
To run Vault Agent:
Download the Vault binary where the client application runs(virtual machine, Kubernetes pod, etc.)
Create a Vault Agent configuration file. (See the ExampleConfiguration section for an example configuration.)
Start a Vault Agent with the configuration file.
Example:
$ vault agent -config=/etc/vault/agent-config.hcl
To get help, run:
$ vault agent -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.
An example configuration, with very contrived values, follows:
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}template { source = "/etc/vault/server.key.ctmpl" destination = "/etc/vault/server.key"}template { source = "/etc/vault/server.crt.ctmpl" destination = "/etc/vault/server.crt"}