Vault Agent Integration

HashiCorp Vault Agent is a lightweight, client-side daemon designed to simplify interactions with HashiCorp Vault, automating critical tasks like authentication, token renewal, caching, and dynamic secret rendering using templates that don't require changes to your application logic.

What Is HashiCorp Vault Agent?

Vault Agent acts as a local helper that abstracts much of the complexity involved in securely fetching and renewing secrets from Vault. Instead of requiring every application to implement complex authentication or secret retrieval logic, Vault Agent takes care of these repetitive tasks for you, allowing your applications to focus on business logic while maintaining a high standard of security.

Key Features of Vault Agent

Note

Agent can cache tokens and leases, but DOES NOT CACHE STATIC SECRETS. This feature is only available with the Vault Proxy

• Automated Authentication (Auto-Auth)
  • Supports multiple authentication methods such as AppRole, Kubernetes, and AWS. This auto-auth feature automatically handles the process of authenticating to Vault, eliminating manual steps.
• Token and Lease Management and Renewal
  • Once authenticated, Vault Agent continuously monitors token and lease expiration. It automatically renews tokens and leases as needed, ensuring applications maintain uninterrupted access to secrets.
• Caching
  • Allows client-side caching of responses containing newly created tokens and responses containing leased secrets generated off of these newly created tokens.
• Templating
  • Allows rendering of user-supplied templates into configuration files by Vault Agent, using the token generated by the Auto-Auth step.
• Windows Service
  • Allows running the Vault Agent as a Windows service.
• Process Supervisor Mode
  • Runs a child process with Vault secrets injected as environment variables.

Please view the Vault Agent Documentation for more information on features.

Potential Use Cases

Note

Vault Agent can integrate with AWS applications, kubernetes workloads, and much more. Please view the tutorials for these integrations at the HashiCorp Vendor Website

1. Secrets Injection in Containerized Environments

In modern deployments like Kubernetes or Docker, managing secrets can be challenging. Running Vault Agent as a sidecar enables seamless injection of secrets into your application containers. The agent automatically fetches and renews secrets, ensuring that containers always have the latest credentials without exposing them directly in code or configuration files.

2. Enhanced Application Resilience

By providing local caching and automated token renewal, Vault Agent improves overall application resilience. Applications can continue to operate with cached secrets even if connectivity to the central Vault server is temporarily lost.

QuickStart with Vault Agent

Note

If you are having issues with the Vault Agent, please make sure the $VAULT_NAMESPACE environmental variable has been correctly set

Pre-requisites

1. Ensure you have installed the Vault Enterprise Binary

Setup

1. Export an environmental variable for the Vault CLI to access the Vault server.

   Bash

   export VAULT_ADDR=<VAULT_ADDRESS>
   

2. Export an environmental variable for the Vault CESI Namespace.

   Bash

   export VAULT_NAMESPACE=admin/<CESI_NAMESPACE>
   

3. Login to Vault. Make sure to set the -namespace flag to admin

   Bash

   vault login -method=saml -namespace=admin
   
   Success! You are now authenticated. The token information displayed below
   is already stored in the token helper. You do NOT need to run "vault login"
   again. Future Vault requests will automatically use this token.
   
   Key                  Value
   ---                  -----
   token                hvs.token
   token_accessor       accessor
   token_duration       1h
   token_renewable      true
   token_policies       ["default"]
   identity_policies    ["default"]
   policies             ["default"]
   token_meta_role      saml_role
   

Create a Working Directory

1. Create a directory to store configuration and template files.

Bash

mkdir $HOME/vault-test && cd $HOME/vault-test

Create data

1. Create a data file

   Bash

   tee data.json -<<EOF
   {
      "organization": "ACME Inc.",
      "customer_id": "ABXX2398YZPIE7391",
      "region": "US-West",
      "zip_code": "94105",
      "type": "premium",
      "contact_email": "james@acme.com",
      "status": "active"
   }
   EOF
   

2. Create the data in a KV v2 Secrets Engine

   Bash

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

Create an AppRole

Auto-auth authenticates with Vault to get a client token, store, and manage the token lifecycle. Vault Agent can heal from an invalid token error caused by unexpected incidence (for example, Vault admin revoked the client token used by the Vault Agent). We will be using an AppRole to configure the token and to enable this self-healing capability.

For easier implementation, AppRoles can also be configured with terraform from our examples repo.

Note

If installing multiple agents, please try to reduce the number of roles needed for the agent to preserve client count. Vault considers an AppRole to be only 1 client as long as the same Role ID is used.

Please contact the DevEx team for additional questions.

1. Create a policy for the approle auth method

   Bash

   vault policy write agent -<<EOL
   path "secret/*" {
      capabilities = ["read", "list"]
   }
   path "sys/leases/*" {
     capabilities = ["create", "update"]
   }
   path "auth/token/*" {
     capabilities = ["create", "update"]
   }
   EOL
   

2. Create a new role within your approle with the associated policy above

   Bash

   vault write auth/approle/role/agent policies=agent token_num_uses=5 secret_id_ttl="3600s"
   

   Understanding token_num_uses Parameter:

   The token_num_uses=5 parameter limits how many times a token can be used or renewed to make API requests before it becomes invalid. This setting is beneficial forr:

   • Security: Prevents unlimited token reuse and renewals, and reduces attack surface

   • Compliance: Ensures tokens have controlled usage patterns

   • Development/Testing: Allows predictable token lifecycle management

   When to use token_num_uses:

   • Production environments: Set to a reasonable limit (5-10) to balance security and functionality

   • High-security environments: Use lower values (1-3) for stricter control

   • Development/testing: May use higher values or remove entirely for convenience

   • Child token creation: Set to 0 if the token needs to create child tokens

   Important: If omitted, tokens have unlimited uses until they expire based on TTL. Setting this to 0 allows unlimited uses and is required when tokens need to create child tokens.

3. Retrieve your role ID and secret ID and store it locally

   Bash

   vault read -field=role_id auth/approle/role/agent/role-id > $HOME/vault-test/roleID.txt
   vault write -f -field=secret_id auth/approle/role/agent/secret-id > $HOME/vault-test/secretID.txt
   

Start a Vault Agent

You will be reading the secrets created above with the Vault Agent while using an AppRole for auto authentication

1. Create a Vault Agent configuration file

Bash

tee agent-config.hcl -<<EOF
pid_file = "./pidfile"

vault {
   address = "$VAULT_ADDR"
   tls_skip_verify = true
}

#Automatically authenticate using the token in the path
auto_auth {
   method {
      type = "approle"
      config = {
         role_id_file_path = "$HOME/vault-test/roleID.txt"
         secret_id_file_path = "$HOME/vault-test/secretID.txt"
      }
   }
   sink "file" {
      config = {
            path = "$HOME/vault-token-via-agent"
      }
   }
}

# Cache tokens and secret leases
cache { }
EOF

2. Start the Vault Agent

Bash

vault agent -config=agent-config.hcl

Example output:

Text Only

==> Vault Agent started! Log data will stream in below:

==> Vault Agent configuration:

                     Cgo: disabled
               Log Level:
               Version: Vault v1.13.0, built 2023-02-14T14:25:23Z
            Version Sha: c2d6b060c0eec60393e866b761a5990716cb45de

[INFO]  vault-agent.sink.file: creating file sink
[INFO]  vault-agent.sink.file: file sink configured: path=$HOME/vault-token-via-agent mode=-rw-r-----
[INFO]  vault-agent.template.server: starting template server
[INFO]  vault-agent.template.server: no templates found
[INFO]  vault-agent.auth.handler: starting auth handler
[INFO]  vault-agent.auth.handler: authenticating
[INFO]  vault-agent.sink.server: starting sink server
[INFO]  vault-agent.auth.handler: authentication successful, sending token to sinks
...snip...

Self-Healing Tokens

As we configured the AppRole above, it should now automatically refresh its token in an event that the TTL expires or the token is revoked. This can be viewed in the logs

Text Only

...snip...
[INFO]  proxy.apiproxy: proxy received an invalid token error
[INFO]  proxy.auth.handler: invalid token found, re-authenticating
[INFO]  proxy.auth.handler: authenticating
[INFO]  proxy.auth.handler: authentication successful, sending token to sinks
[INFO]  proxy.auth.handler: starting renewal process
[INFO]  proxy.sink.file: token written: path=/user/vault-token-via-agent
[INFO]  proxy.auth.handler: renewed auth token

Token Persistence and Agent Restart

When Vault Agent restarts, it can utilize existing tokens from the sink file to maintain continuity without immediate re-authentication.

Example: Leveraging Persisted Tokens After Restart

1.Verify token persistence from previous run:

Bash

# Check if token file exists from previous agent session
if [ -f "$HOME/vault-token-via-agent" ]; then
   echo "Token file found - agent can use existing token on restart"
   # Verify token is still valid
   VAULT_TOKEN=$(cat $HOME/vault-token-via-agent) vault auth -method=token
else
   echo "No existing token - agent will perform fresh authentication"
fi

2.Agent configuration with existing token support:

Bash

tee agent-restart-config.hcl -<<EOF
pid_file = "./pidfile"
vault {
   address = "$VAULT_ADDR"
   tls_skip_verify = true
}

auto_auth {
   method {
      type = "approle"
      config = {
         role_id_file_path = "$HOME/vault-test/roleID.txt"
         secret_id_file_path = "$HOME/vault-test/secretID.txt"
      }
   }
   sink "file" {
      config = {
            path = "$HOME/vault-token-via-agent"
      }
   }
}

cache { }
EOF

3.Restart Vault Agent:

Bash

vault agent -config=agent-restart-config.hcl

Benefits of Token Persistence:

• Faster startup: Agent can use existing valid tokens before expiration
• Reduced authentication load: Fewer authentication requests to Vault
• Seamless transitions: Applications continue working during agent restarts

Note

Agent will automatically re-authenticate when the persisted token expires or becomes invalid, ensuring continuous operation.

Vault Agent Templates

In this scenario, the Vault Agent can use templates to quicky ingest secrets from Vault.

1. Press Ctrl + C to stop running the Vault Agent
2. If you are unsure if the Vault Agent process is still running, please run this command: pgrep -f vault | xargs kill

3. Create a customer.json.tmpl file. This will be the template file Vault Agent will run against to ingest secrets

   Bash

   tee customer.json.tmpl -<<EOF
   {
      {{ with secret "secret/data/customers/acme" }}
      "Organization": "{{ .Data.data.organization }}",
      "ID": "{{ .Data.data.customer_id }}",
      "Contact": "{{ .Data.data.contact_email }}"
      {{ end }}
   }
   EOF
   

4. Create a Vault Agent configuration file, but with a template stanza added.

   Bash

   tee agent-template.hcl -<<EOF
   template {
      source      = "$HOME/vault-test/customer.json.tmpl"
      destination = "$HOME/vault-test/customer.json"
   }
   EOF
   

5. Start Vault Agent again with the additional configuration applied

   Bash

   vault agent -config=agent-config.hcl \
      -config=agent-template.hcl
   

Example output:

Text Only

==> Vault Agent started! Log data will stream in below:

==> Vault Agent configuration:

         Api Address 1: http://bufconn
                     Cgo: disabled
               Log Level:
               Version: Vault v1.13.0-rc1+ent, built 2023-02-14T14:25:23Z
            Version Sha: c2d6b060c0eec60393e866b761a5990716cb45de

[INFO]  vault-agent.sink.file: creating file sink
[INFO]  vault-agent.sink.file: file sink configured: path=$HOME/vault-token-via-agent mode=-rw-r-----
[INFO]  vault-agent.auth.handler: starting auth handler
[INFO]  vault-agent.auth.handler: authenticating
[INFO]  vault-agent.template.server: starting template server
...snip...
[INFO] (runner) starting
[INFO] (runner) rendered "$HOME/vault-test/customer.json.tmpl" => "$HOME/vault-test/customer.json"

1. Open a new terminal or text editor and verify that the customer.json file has the secrets retrieved from Vault.
   Bash

   cat customer.json
   

Example output:

Text Only

{

   "Organization": "ACME Inc.",
   "ID": "ABXX2398YZPIE7391",
   "Contact": "james@acme.com"

}

This data should match the values stored in secret/customers/acme

Text Only

vault kv get secret/customers/acme

======= Secret Path =======
secret/data/customers/acme

======= Metadata =======
Key                Value
---                -----
created_time       2025-02-23T16:25:46.030960819Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

======== Data ========
Key              Value
---              -----
contact_email    james@acme.com
customer_id      ABXX2398YZPIE7391
organization     ACME Inc.
...snip...

Process Supervisor Mode with Environment Variables

Vault Agent can launch child processes with secrets injected as environment variables using env_template and exec blocks.

Note

Process Supervisor Mode is incompatible with regular file template entries. When using env_template, you cannot use standard template stanzas in the same configuration.

Example: Launching a Process with Injected Secrets

1.Create a sample application script:

Bash

tee sample-app.sh -<<EOF
#!/bin/bash
echo "Application started with injected secrets:"
echo "Organization: \$ACME_ORG"
echo "Customer ID: \$ACME_CUSTOMER_ID"
echo "Contact Email: \$ACME_CONTACT_EMAIL"
echo "Region: \$ACME_REGION"
# Simulate application work
while true; do
   echo "Application running... (secrets available as env vars)"
   sleep 30
done
EOF

Text Only

chmod +x sample-app.sh

2.Create agent configuration with env_template and exec:

Bash

tee agent-exec-config.hcl -<<EOF
pid_file = "./pidfile"
vault {
   address = "$VAULT_ADDR"
   tls_skip_verify = true
}

auto_auth {
   method {
      type = "approle"
      config = {
         role_id_file_path = "$HOME/vault-test/roleID.txt"
         secret_id_file_path = "$HOME/vault-test/secretID.txt"
      }
   }
   sink "file" {
      config = {
            path = "$HOME/vault-token-via-agent"
      }
   }
}

cache { }

env_template "ACME_ORG" {
   contents = "{{ with secret \"secret/data/customers/acme\" }}{{ .Data.data.organization }}{{ end }}"
}

env_template "ACME_CUSTOMER_ID" {
   contents = "{{ with secret \"secret/data/customers/acme\" }}{{ .Data.data.customer_id }}{{ end }}"
}

env_template "ACME_CONTACT_EMAIL" {
   contents = "{{ with secret \"secret/data/customers/acme\" }}{{ .Data.data.contact_email }}{{ end }}"
}

env_template "ACME_REGION" {
   contents = "{{ with secret \"secret/data/customers/acme\" }}{{ .Data.data.region }}{{ end }}"
}

exec {
   command                   = ["$HOME/vault-test/sample-app.sh"]
   restart_on_secret_changes = "always"
   restart_stop_signal       = "SIGINT"
}
EOF

3.Start Vault Agent with process supervision:

Bash

vault agent -config=agent-exec-config.hcl

Key Features of Process Supervisor Mode:

• Automatic Secret Injection: Secrets are automatically injected as environment variables
• Process Management: Vault Agent manages the child process lifecycle
• Auto-restart: Process automatically restarts when secrets change
• Signal Handling: Configurable stop signals for graceful shutdown
• Named Variables: Each env_template block name becomes the environment variable name

Example Output:

Text Only

Application started with injected secrets:
Organization: ACME Inc.
Customer ID: ABXX2398YZPIE7391
Contact Email: james@acme.com
Region: US-West
Application running... (secrets available as env vars)

This approach eliminates the need for applications to directly interact with Vault APIs, as secrets are provided through standard environment variables.

References

Vault Proxy and Agent Quick Start Guide

Cache Secrets With Vault Agent

What is Vault Agent?