Vault Agent Templates
The adoption of Vault is an incremental journey. First, you move your secrets into Vault so that they are securely encrypted and stored. The next step is to update your applications' behavior so that the secrets are read from Vault.
To establish a connection with Vault, clients must first authenticate with Vault and acquire a token. Vault Agent was introduced to reduce the burden from distributed applications to manage Vault client tokens.

The following guides demonstrate the Auto-Auth method of Vault Agent:
In addition, the Vault Agent Caching tutorial walked through the Caching feature introduced in Vault 1.1.
Challenge and solution
After the successful authentication, Vault clients can start interacting with the Vault. Many Vault users adopted the Consul Template tool to minimize the level of changes introduced to their existing applications.

The Direct Application Integration tutorial demonstrates the use of Consul Template for Vault users.
In this case, Consul Template is the client directly interacting with Vault; therefore, you had to configure Consul Template to read the token from the agent's sink location in order to interact with Vault. This requires you to operate two distinct tools to provide secrets to applications.
In Vault 1.3, Vault Agent introduced Vault Agent Templates allowing Vault secrets to be rendered to files using the Consul Template markup language. This significantly simplifies the workflow when you are integrating your applications with Vault.
Note
This tutorial focuses on the templates feature of Vault Agent assuming that you are already familiar with Vault Agent Auto-Auth. If you are new to Vault Agent, try the Vault Agent with AWS tutorial or the Vault Agent with Kubernetes tutorial before continuing with this tutorial.
Prerequisites
To complete this section of the tutorial, you will need:
- AWS account and associated credentials that allow for the creation of resources
- Vault version 1.3 or later
- Terraform installed
Provision the cloud resources
Clone the demo assets from the hashicorp/vault-guides GitHub repository to perform the steps described in this tutorial.
This repository contains supporting content for all of the Vault learn tutorials. The content specific to this tutorial can be found within a sub-directory.
Be sure to set your working directory to where the
/identity/vault-agent-templates/terraform-aws
directory is located.The following assets are located under this directory:
NOTE: The example Terraform in this repository is created for the demo purpose.
Set an
AWS_ACCESS_KEY_ID
environment variable to hold your AWS access key ID.Set an
AWS_SECRET_ACCESS_KEY
environment variable to hold your AWS secret access key.Tip
The above example uses IAM user authentication. You can use any authentication method described in the AWS provider documentation.
Create a file named
terraform.tfvars
and specify thekey_name
. (You can copy theterraform.tfvars.example
file and rename it asterraform.tfvars
.)Example
terraform.tfvars
:If you don't have an EC2 Key Pairs, refer to the AWS documentation and create one.
Perform a
terraform init
to pull down the necessary provider resources.Perform
terraform plan
to verify your changes and the resources that will be created.If all looks good, perform a
terraform apply
to provision the resources.The Terraform output will display the public IP address to SSH into your Vault server and client instances.
Configure AWS IAM auth method
Note
This step should be performed on the Vault Server instance.
In this step, you will configure Vault to allow AWS IAM authentication from specific IAM roles.
SSH into the Vault Server instance.
When you are prompted, enter "yes" to continue.
NOTE: If you received
Permissions 0664 for '<key_name>.pem' are too open
error, be sure to set the file permission appropriately.Run the
vault operator init
command to initialize the Vault server. For the convenience of this tutorial, save the generated recovery keys and an initial root token in a file named,key.txt
.The Vault server is configured to auto-unseal with AWS Key Management Service (KMS); therefore, once the server is initialized, it gets automatically unsealed. To learn how to auto-unseal Vault using AWS KMS, refer to the Auto-unseal using AWS KMS tutorial.
Log into Vault using the generated initial root token save in the
key.txt
Examine the
/home/ubuntu/aws_auth.sh
script.Execute the
/home/ubuntu/aws_auth.sh
script.The script enabled key/value v2 secrets engine at
secret
and wrote some data atsecret/customers/acme
. It also created anapp-pol
policy, enabled and configuredaws
auth method, and created a role namedapp-role
.View the
app-pol
policy.View the secrets written at
secret/customers/acme
Start Vault Agent
Note
This step should be performed on the Vault Client instance.
In the client node, Vault Agent authenticates with Vault via aws
auth method
you configured in the configure AWS IAM auth
method step. Using the acquired token, the
agent pulls secrets from Vault defined by the template file.

Now, SSH into the Vault Client instance.
When you are prompted, enter "yes" to continue.
Explore the Vault Agent configuration file,
/home/ubuntu/vault-agent.hcl
.The contents of the file looks as below.
The Vault Agent uses the
aws
auth method to authenticate with the Vault server running on the server instance asapp-role
. Also notice that there istemplate
block which sets/home/ubuntu/customer.tmpl
as the source template file and the output will be written to the destination,/home/ubuntu/customer.txt
.Execute the following command to start the Vault Agent with log level set to
debug
.You should find the following:
Open a second SSH terminal into the client machine.
Verify the client token stored in
/home/ubuntu/vault-token-via-agent
.Check the details about the token (e.g. attached policies, TTL, etc.).
The
app-pol
policy is attached to the token. Remember that theapp-pol
policy grants read operation against thesecret/data/*
path.Review the
customer.tmpl
file which is written using the Consul Templates markup language.Notice that the secret path is set to
secret/data/customers/acme
.Examine the resulting
customer.txt
file.Based on the
customer.tmpl
file, Vault Agent Templates read the secrets atsecret/data/customers/acme
and then generated thecustomer.txt
file.
Challenge
What happens if the data at secret/data/customers/acme
was updated?
On the server instance terminal, update the
contact_email
tojenn@acme.com
.Verify that the data was successfully updated.
Return to the client instance SSH session where the Vault Agent is running. Wait for a few minutes (about 4 minutes). The agent pulls the secrets again.
When reading secrets from Key/Value v2 secrets engine, omitting the
?version
parameter reads the latest version of the secrets at the path. If you want to always pull a specific version of the secret, specify the desired version number. For example,{{ with secret "secret/data/customers/acme?version=3" }}
will always read the version 3 of thesecret/data/customers/acme
values.
Clean up
Execute the following commands to destroy cloud resources.
At this point, you can delete the Terraform state files from the directory.
Summary and reference
Vault Agent is a client daemon that solves the secret-zero problem by authenticating with Vault and manage the client tokens on behalf of the client applications. The Consul Template tool is widely adopted by the Vault users since it allowed applications to be "Vault-unaware".
Vault Agent Templates combines the best of the two tools to make the end-to-end workflow even simpler.

Help and reference
- Blog post: Why Use the Vault Agent for Secrets Management?
- Video: Streamline Secrets Management with Vault Agent and Vault 0.11
- Vault Agent Templates
- Consul Template - Templating Language
- Direct Application Integration