Vault agent's process supervisor mode
Vault Agent's Process Supervisor Mode allows Vault secrets to be injected into a process via environment variables using Consul Template markup.
If you are running your applications in a Kubernetes cluster, we recommend evaluating the Vault Secrets Operator and the Vault Agent Sidecar Injector.
Vault Agent's Process Supervisor Mode is in public beta. Please provide your feedback by opening a GitHub issue here.
Functionality
Vault Agent will inject secrets referenced in the env_template
configuration
blocks as environment variables into the child process specified in the exec
block.
When you start Vault Agent in process supervisor mode, it will wait until each
environment variable template has rendered at least once before starting the
process. If restart_on_secret_changes
is set to always
(default), Agent
will restart the process whenever an update to an injected secret is detected.
This could be either a static secret update (done on
static_secret_render_interval
)
or dynamic secret being close to its expiration.
In many ways, Vault Agent will mirror the child process. Standard intput and
output streams (stdin
/ stdout
/ stderr
) are all forwarded to the child
process. Additionally, Vault Agent will exit when the child process exits on
its own with the same exit code.
Configuration
Agent's generate-config tool will help you get started by generating a valid agent configuration file from the given inputs.
The process supervisor mode requires at least one env_template
block and
exactly one top level exec
block. It is incompatible with regular file
template
entries.
env_template
env_template
stanza maps the template specified in the contents
field or
referenced in the source
field to the environment variable name in the title
of the stanza. It uses the same
templating language
as file templates but permits only a subset of
its configuration parameters:
environment variable name
(string: <required>)
- the name of the environment variable to which the contents of the template should map.contents
(string: "")
- This option allows embedding the contents of a template in the configuration file rather then supplying thesource
path to the template file. This is useful for short templates. This option is mutually exclusive with thesource
option.source
(string: "")
- Path on disk to use as the input template. This option is required if not using thecontents
option.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 seeexit_on_retry_failure
in global Vault Agent Template Config.left_delimiter
(string: "{{")
- Delimiter to use in the template. The default is "{{" but for some templates, it may be easier to use a different delimiter that does not conflict with the output file itself.right_delimiter
(string: "}}")
- Delimiter to use in the template. The default is "}}" but for some templates, it may be easier to use a different delimiter that does not conflict with the output file itself.
exec
The top level exec
block has the following configuration entries.
command
(string array: required)
- Specify the command for the child process with optional arguments. The executable's path must be either absolute or relative to the current working directory.restart_on_secret_changes
(string: "always")
- Controls whether agent will restart the child process on secret changes. There are two types of secret changes relevant to this configuration: a static secret update (on static_secret_render_interval`) and dynamic secret being close to its expiration. The configuration supports two options:always
andnever
.restart_stop_signal
(string: "SIGTERM")
- Signal to send to the child process when a secret has been updated and the process needs to be restarted. The process has 30 seconds after this signal is sent untilSIGKILL
is sent to force the child process to stop.
Configuration example
The following example was generated using
vault agent generate-config
,
a configuration helper tool. Given this configuration, Vault Agent will run
the child process (./my-app arg1 arg2
) with two additional environment
variables (FOO_USER
and FOO_PASSWORD
) populated with secrets from Vault.
Tutorial
Refer to the Vault Agent - secrets as environment variables tutorial for an end-to-end example.