Vault Agent quick start
What is Vault Agent?
Vault Agent behaves as a client-side daemon to make requests to Vault on behalf of the client application. This includes the authentication to Vault.
Vault clients (human users, applications, etc.) must authenticate with Vault and get a client token to make API requests. Because tokens have time-to-live (TTL), the clients must renew the token's TTL or re-authenticate to Vault based on its TTL. Vault Agent authenticates with Vault and manage the token's lifecycle so that the client application doesn't have to.
In addition, you can inject the Consul Template markup into Vault Agent so that secrets can be rendered to files where the client application load data from.

This eliminates the need to change your application code to invoke the Vault API. Your existing applications can remain Vault-unaware.
Prerequisites
To complete this tutorial, you will need:
Lab setup
Open a terminal and start a Vault dev server with
root
as the root token.The Vault dev server defaults to running at
127.0.0.1:8200
. The server is also initialized and unsealed.Insecure operation: Do not run a Vault dev server in production. This approach is only used here to simplify the unsealing process for this demonstration.
Export an environment variable for the
vault
CLI to address the Vault server.Log into Vault.
Tip
Vault server is ready and the token value (
root
) is store in the$HOME/.vault-token
file.
Create a working directory
Create a directory where you generate test files.
You will read the created secrets using Vault Agent.
Create test data
Create a mock data file.
Create the mock data in the KV v2 secrets engine.
Start a Vault Agent
Start a Vault Agent instance that connects to the Vault server running at
VAULT_ADDR
.
Create the Vault Agent configuration file.
Note
As of Vault 1.13.0, you can use the client token stored in a file (
token_file_path
). This is a convenient way to authenticate the Vault Agent with Vault server during development. For production deployment, use one of the supported auth methods.Start a Vault Agent.
Example output:
At this point, you still need to change your client application to make Vault
requests targeting to VAULT_ADDR
using the Vault token stored in the sink
location ($HOME/vault-token-via-agent
).
Next, explore other Vault Agent features.
Modify the Vault Agent configuration
Starting Vault 1.13.0, you can specify multiple Vault Agent configuration files.
Or, point to a directory where configuration files are located.
In this section, you are going to define additional Vault Agent configurations.
Define Vault Agent template
In the following scenario, the client application loads data read from customer.json
.
Press Ctrl + C to stop the running Vault Agent.
Create a
customer.json.tmpl
file.Create a Vault Agent configuration file with
tempalte
stanza.Start Vault Agent again with additional configuration.
Example output:
Open a new browser or text editor and verify that the
customer.json
file has the secrets retrieved from Vault.This should match to the data stored in
secret/
.If the template fails, make sure that the
VAULT_NAMESPACE
variable is set.
The client application was designed to load data from the customer.json
file.
By leveraging the Vault Agent Template feature, you did not have to make any
code change to the client application while your secrets are managed by Vault.
Add a listener
You can define an API endpoint that the Vault Agent listens to. The client
application can send requests to the endpoint rather than VAULT_ADDR
.
Press Ctrl + C to stop the running Vault Agent.
Create a file that defines the
listener
stanza andapi_proxy
stanza.This configuration adds two Vault Agent API endpoints,
127.0.0.1:8100
and127.0.0.1:3000
. The secondlistener
stanza defines a role set tometrics_only
to use the API endpoint only to collect Vault Agent metrics. (See the Vault Agent documentation.)The
api_proxy
stanza enables theuse_auto_auth_token
parameter. When enabled, Vault Agent will use the auto-auth token for proxied requests that do not carry their own token. Therefore, requests will use the auto-auth token without needing to provide theX-Vault-Token
header.Note
To leverage the
metrics_only
setting and theapi_proxy
stanza, you need Vault binary version 1.13.0 or later.Start the Vault Agent again with additional configuration.
Example output:
Now, Vault Agent listens to the API endpoints
http://127.0.0.1:8100
andhttp://127.0.0.1:3000
(metrics only) and behaves as a Vault proxy.
Vault Agent logs
You can specify the behavior of Vault Agent logs using command flag, environment variable, or configuration parameters.
Start Vault Agent with the
-log-file
command flags which defines the prefix for the log file.The command generates a log file named
$HOME/vault-test/vault-agent-{timestamp}.log
.Verify the generated log file.
You can open the file to verify its content.
Tip
To see the full list of available parameters, refer to the Vault Agent documentation.
Vault proxy
In the add a listener section, you added the api_proxy
stanza to the Vault Agent configuration (agent-listener-config.hcl
). This
allows the Vault clients to send API requests to Vault through the proxy
address.
Vault 1.14 introduced the new vault proxy
command to start a Vault Proxy.
If you are not using other features such as templating, and want to scale the
adoption of Vault by having Vault Agent to manage the client tokens, the vault
proxy
command may meet your usage requirement.
Press Ctrl + C to stop the running Vault Agent.
Start a Vault API proxy.
Vault Agent is now listening to the proxy addresses
http://127.0.0.1:8100
andhttp://127.0.0.1:3000
(for role,metrics_only
).Open another command terminal, and send an API request to through the Vault proxy.
This example uses jq to process the JSON output for readability.
Example output:
Note
Although no client token was provided in the API request, a token was automatically attached to the request by the Vault Agent. This was because the
use_auto_auth_token
parameter was set totrue
in the configuration.
For a quick demonstration, this tutorial used the token_file_path
for
auto-auth with no role associated with the authentication. When you configure
other auth methods with role
concept, you can send requests to http://127.0.0.1:3000
if the authentication
was made with metrics_only
role.
Clean up
Press Ctrl + C to stop the running Vault Agent.
You can stop the Vault dev server by pressing Ctrl+C where the server is running. Or, execute the following command.
Unset the
VAULT_ADDR
environment variable.Delete the
$HOME/vault-test
directory.
Summary
This tutorial demonstrated the basics of Vault Agent. You learned:
- Minimum Vault Agent configuration
- Used templates to read secrets from Vault
- Define an API address that Vault Agent listens to
The use of Vault token file is an convenient way to quickly start the Vault Agent. For a production deployment, use one of the supported auth methods so that the Vault Agent can manage the lifecycle of the token properly.
See the following tutorials for auto auth examples:
The Vault Agent Template demonstrated that the client application can remain Vault-unaware while Vault manages the secrets.
See the following tutorials to see more template examples:
- Vault Agent Templates
- Read Secrets From Vault Using Vault Agent
- Using HashiCorp Vault Agent with .NET Core