HashiCorp Vault — Agent Caching

2 minute read

Vault Agent’s caching layer reduces load on Vault servers by locally caching token and lease renewals, and optionally caching secret responses.

Why Caching?

Without Caching With Caching
Every request hits Vault Repeated reads served from cache
Token renewal per-request Agent manages one token
Network latency on every call Sub-millisecond local responses
Vault overloaded at scale Cache absorbs read traffic

Basic Caching Configuration

# vault-agent.hcl

vault {
  address = "http://vault.service.internal:8200"
}

auto_auth {
  method "approle" {
    config = {
      role_id_file_path   = "/etc/vault/role-id"
      secret_id_file_path = "/etc/vault/secret-id"
    }
  }
}

cache {
  # Cache uses in-memory storage by default
  use_auto_auth_token = true
}

# Expose a local listener for applications
listener "tcp" {
  address     = "127.0.0.1:8100"
  tls_disable = true
}

How Apps Use It

Applications connect to the agent’s local listener instead of Vault directly:

# Instead of talking to Vault:
# VAULT_ADDR=http://vault.service.internal:8200

# Applications talk to the local agent:
export VAULT_ADDR=http://127.0.0.1:8100

# Requests are proxied through the cache
vault kv get secret/myapp/config

Persistent Caching

Keep the cache across agent restarts:

cache {
  use_auto_auth_token = true

  persist "kubernetes" {
    path                     = "/vault/agent-cache"
    keep_after_import        = true
    exit_on_err              = true
    service_account_token_file = "/var/run/secrets/kubernetes.io/serviceaccount/token"
  }
}

Static Secret Caching

Cache KV secrets with automatic refresh:

cache {
  use_auto_auth_token = true
}

# Static secrets can be cached and refreshed
# Agent handles lease renewal for dynamic secrets automatically

Cache Eviction

# Clear the agent cache via API
curl -X POST http://127.0.0.1:8100/agent/v1/cache-clear \
  -d '{"type": "all"}'

# Clear by request path
curl -X POST http://127.0.0.1:8100/agent/v1/cache-clear \
  -d '{"type": "request_path", "value": "/v1/secret/data/myapp"}'

# Clear by token
curl -X POST http://127.0.0.1:8100/agent/v1/cache-clear \
  -d '{"type": "token"}'

# Clear by lease
curl -X POST http://127.0.0.1:8100/agent/v1/cache-clear \
  -d '{"type": "lease"}'

Complete Agent with Cache

vault {
  address = "http://vault.service.internal:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "approle" {
    config = {
      role_id_file_path   = "/etc/vault/role-id"
      secret_id_file_path = "/etc/vault/secret-id"
      remove_secret_id_file_after_reading = true
    }
  }

  sink "file" {
    config = {
      path = "/etc/vault/agent-token"
      mode = 0640
    }
  }
}

cache {
  use_auto_auth_token = true
}

listener "tcp" {
  address     = "127.0.0.1:8100"
  tls_disable = true
}

listener "unix" {
  address     = "/etc/vault/agent.sock"
  tls_disable = true
}

Applications can connect via TCP or Unix socket:

# TCP
export VAULT_ADDR=http://127.0.0.1:8100

# Unix socket
export VAULT_AGENT_ADDR=unix:///etc/vault/agent.sock

Quick Reference

Feature Description
cache {} block Enables caching
use_auto_auth_token Attach auto-auth token to proxied requests
listener "tcp" Expose local HTTP endpoint
listener "unix" Expose Unix socket endpoint
Cache eviction API /agent/v1/cache-clear

Next: Templating

You may also enjoy