HashiCorp Vault — Lease Management

2 minute read

Every dynamic secret in Vault has a lease — a time contract that controls how long the credentials are valid. Understanding lease management is critical for operating Vault at scale.

Lease Anatomy

Lease Created ──────────── TTL ──────────── Expiry
     │                                        │
     │   renewable? ──▶ vault lease renew     │
     │                        │                │
     │                   Extended TTL          │
     │                        │                │
     │            max_ttl ────┼──── Hard limit │
     │                        │                │
     └────────────────────────┘                │
                                               │
                                  Vault revokes credentials
                                  (drops DB user, deletes IAM user, etc.)

Lease Properties

Property Description
lease_id Unique identifier (e.g., database/creds/readonly/abc123)
lease_duration How long until expiry
lease_renewable Whether the lease can be renewed
ttl Current time-to-live
max_ttl Absolute maximum lifetime

Lookup a Lease

vault lease lookup database/creds/pg-readonly/abc123

Expected output:

Key             Value
---             -----
expire_time     2024-01-15T18:30:00Z
id              database/creds/pg-readonly/abc123
issue_time      2024-01-15T17:30:00Z
last_renewal    <nil>
renewable       true
ttl             55m30s

Renew a Lease

# Renew with default increment
vault lease renew database/creds/pg-readonly/abc123

# Renew with specific increment
vault lease renew -increment=2h database/creds/pg-readonly/abc123

Rules:

  • Can only renew up to max_ttl from the original issue time
  • Renewal resets the TTL counter
  • Once max_ttl is reached, the credential expires regardless
Issue Time: 10:00
TTL: 1h (expires 11:00)
Max TTL: 4h (hard limit: 14:00)

10:30 → renew -increment=1h → new expiry: 11:30 ✅
11:00 → renew -increment=2h → new expiry: 13:00 ✅
13:00 → renew -increment=2h → new expiry: 14:00 ✅ (capped at max_ttl)
14:00 → renew → DENIED (max_ttl reached, must get new credentials)

Revoke Leases

Revoke a Single Lease

vault lease revoke database/creds/pg-readonly/abc123

This immediately:

  • Drops the database user
  • Invalidates the credentials
  • Removes the lease from Vault

Revoke by Prefix

# Revoke ALL leases for a specific role
vault lease revoke -prefix database/creds/pg-readonly

# Revoke ALL database leases
vault lease revoke -prefix database/creds

# Revoke ALL AWS leases
vault lease revoke -prefix aws/creds

⚠️ Prefix revocation is powerful and immediate. Use with care.

Force Revoke

If normal revocation fails (e.g., database is down):

vault lease revoke -force database/creds/pg-readonly/abc123

Force revoke removes the lease from Vault even if the target system can’t be reached. The credential may still work on the target system until it’s cleaned up manually.

List Active Leases

# List leases for a role
vault list sys/leases/lookup/database/creds/pg-readonly

# Count active leases
vault list -format=json sys/leases/lookup/database/creds/pg-readonly | jq '. | length'

# List all database leases
vault list sys/leases/lookup/database/creds

Lease Management via API

# Lookup
curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
     --request PUT \
     --data '{"lease_id": "database/creds/pg-readonly/abc123"}' \
     "$VAULT_ADDR/v1/sys/leases/lookup" | jq

# Renew
curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
     --request PUT \
     --data '{"lease_id": "database/creds/pg-readonly/abc123", "increment": 3600}' \
     "$VAULT_ADDR/v1/sys/leases/renew" | jq

# Revoke
curl -s --header "X-Vault-Token: $VAULT_TOKEN" \
     --request PUT \
     --data '{"lease_id": "database/creds/pg-readonly/abc123"}' \
     "$VAULT_ADDR/v1/sys/leases/revoke"

Lease Best Practices

Practice Reasoning
Set short default TTLs (1h) Minimize exposure if credentials leak
Set reasonable max TTLs (8-24h) Don’t allow indefinite renewals
Applications should renew proactively Renew at 50-75% of TTL
Monitor lease counts High lease counts impact Vault performance
Use revoke -prefix for incident response Immediately invalidate all compromised credentials

Quick Reference

Command Description
vault lease lookup LEASE_ID Inspect a lease
vault lease renew LEASE_ID Renew a lease
vault lease renew -increment=2h LEASE_ID Renew with duration
vault lease revoke LEASE_ID Revoke single lease
vault lease revoke -prefix PREFIX Revoke all matching leases
vault lease revoke -force LEASE_ID Force revoke
vault list sys/leases/lookup/PREFIX List active leases

Next: Practice Exercises

You may also enjoy