Difficulty: beginner
Estimated Time: 5 minutes

Vault logo

This scenario supplements the Vault Agent Templates guide.

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.

Vault Agent Auto-Auth was introduced to reduce the burden from distributed applications to manage Vault client tokens. Once acquired a token, 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. But they still had to manage those two tools.

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.


This scenario assumes that you have some working knowledge of Vault Agent and Consul Templates. If you are not familiar with Vault Agent and/or Consul Template, complete the following scenario before continuing with this scenario:

This scenario gave you a quick introduction to Vault Agent Templates which was introduced in Vault 1.3.

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.

Visit the learn.hashicorp.com and check out the Vault Agent Templates guide!


Vault Agent Templates

Step 1 of 2

Vault Agent Templates

First, login with root token.

Click on the command () will automatically copy it into the terminal and execute it.

vault login root

Write some secrets at secret paths. The test data is provided in the data.json file.

  "organization": "ACME Inc.",
  "customer_id": "ABXX2398YZPIE7391",
  "region": "US-West",
  "zip_code": "94105",
  "type": "premium",
  "contact_email": "[email protected]",
  "status": "active"

Execute the following commands to write the data:

vault kv put secret/customers/acme @data.json

Check to verify the secrets at secret/customers/acme:

vault kv get secret/customers/acme

Setup Auth Method

Setup the auth method on the Vault server. In this example, you are going to enable approle auth method.

vault auth enable approle

Create a policy named, "app-pol" which is defined by the app-pol.hcl file.

vault policy write app-pol app-pol.hcl

Execute the following command to create a role named, "apps" with app-pol policy attached.

vault write auth/approle/role/apps policies="app-pol"

Now, generate a role ID and stores it in a file named, "roleID".

vault read -format=json auth/approle/role/apps/role-id \
        | jq  -r '.data.role_id' > roleID

The approle auth method allows machines or apps to authenticate with Vault using Vault-defined roles. The generated roleID is equivalent to a username.

Also, generate a secret ID and stores it in the "secretID" file.

vault write -f -format=json auth/approle/role/apps/secret-id \
        | jq -r '.data.secret_id' > secretID

Vault Agent Configuration

Vault Agent runs on the client side to automate leases and tokens lifecycle management.

Examine the Vault Agent configuration file, agent-config.hcl.

pid_file = "./pidfile"

vault {
   address = ""

auto_auth {
   method "approle" {
       mount_path = "auth/approle"
       config = {
           role_id_file_path = "roleID"
           secret_id_file_path = "secretID"
           remove_secret_id_file_after_reading = false

   sink "file" {
       config = {
           path = "approleToken"

template {
  source      = "./customer.tmpl"
  destination = "./customer.txt"

Notice the template block. This defines the path on disk to use as the input template which uses Consul Templates markup. The destination specifies the desired rendered output file.

View the customer.tmpl file.

Execute the following command to start the Vault Agent with debug logs.

vault agent -config=agent-config.hcl -log-level=debug

The agent log should include the following messages:

[DEBUG] (runner) checking template c6c6b1e5bb647223b68c4e2f66b9f182
[DEBUG] (runner) rendering "./customer.tmpl" => "./customer.txt"
[INFO]  (runner) rendered "./customer.tmpl" => "./customer.txt"
[DEBUG] (runner) diffing and updating dependencies
[DEBUG] (runner) vault.read(secret/data/customers/acme) is still needed
[DEBUG] (runner) watching 1 dependencies
[DEBUG] (runner) all templates rendered

Vault Agent read the secrets at secret/customer/acme based on the customer.tmpl file and outputed the rendered data into the customer.txt file.

Organization: ACME Inc.
Contact: [email protected]