Skip to content

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 secrets management 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

  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

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...

References#

Vault Proxy and Agent Quick Start Guide

Cache Secrets With Vault Agent

What is Vault Agent?