Learn Vault - Lease, TTL, Renewal & Revocation (Dynamic Token Lifecycle)

#Introduction

After covering the Identity Engine in episode 11 and how Vault unifies identities from various auth methods, we now enter one of Vault's greatest advantages that most distinguishes it from ordinary secret managers: the dynamic, destructible lifecycle of every access.

Recall the dynamic secrets material from episode 5: Vault creates database credentials on-demand with short TTLs. Now the deeper question: how does Vault remember those credentials? When do they "die"? And how can we kill them instantly if a leak occurs? The answer lies in three interrelated concepts: Lease, TTL (Time-To-Live), and Revocation.

For an SRE, understanding this isn't just theoretical knowledge. Imagine an incident: a production database credential leaks into application logs. In a traditional system, you'd have to log in to the database, find the user, and revoke their access — which can take hours. With Vault, a single vault lease revoke command destroys that credential in seconds. That's why this topic is a must-master before you run real production systems.

Let's start with the Lease concept.

#Main Discussion

#What Is a Lease and Why Vault Needs It

A lease is a time contract between Vault and the secret holder. Every time Vault issues something that "lives" — dynamic database credentials, dynamic IAM keys, PKI certificates, or even tokens — it records a lease that defines how long the secret may be used.

Why a lease? Because Vault must have a way to track and revoke the access it has granted. Once Vault issues a credential to a database, it must be able to find that credential again to revoke it when the TTL expires or when a revoke is commanded. The Lease ID is the unique "receipt" that enables all of this.

When you read a lease-bearing secret, note two important fields in the output:

vault read database/creds/app-db

Key                Value
---                -----
lease_id           database/creds/app-db/Z9wXc8Kv...7Gq
lease_duration     1h
lease_renewable    true
 
Data
----
password           Vp5mQ8sZ...
username           v-app-db-AJ4kLp3R...

• lease_id — the unique identity of this lease, used for renewal and revocation.
• lease_duration — how long the secret is valid (in seconds; 1h here because of the role's default TTL).
• lease_renewable — whether the lease can be extended (true for dynamic creds).

Not all secrets carry leases. Static secrets in KV have no lease — they exist until you change or delete them. Leases exist on dynamic outputs: credentials, tokens, certs, and the like. This is the fundamental difference between "storing secrets" and "issuing secrets."

#TTL: Time Limits at Every Layer

TTL (Time-To-Live) determines the maximum age of a lease. In Vault, TTLs work in layers, and the effective TTL is the shortest among all applicable layers. Here are the most common layers:

Concrete example: a database role has default_ttl=1h and max_ttl=24h, and the token fetching it has token_ttl=30m. The credential's effective TTL is 30 minutes (the shortest value). Understanding this prevents you from wondering why a credential configured as "1 hour" dies in 30 minutes.

#The Lease Lifecycle: Issue → Renew → Expire/Revoke

A lease goes through several phases:

Issue (read creds)
   │
   ├──► Renew ──► Renew ──► ... ──► Max TTL reached / stop renewing
   │
   └──► Expire (TTL exhausted) ──► Credential auto-revoked
   │
   └──► Manual revoke (vault lease revoke) ──► Destroyed instantly

1. Issue — a lease is born when the secret is read.

vault read database/creds/app-db

2. Renew — extend before expiry.

vault lease renew database/creds/app-db/Z9wXc8Kv...7Gq

Key                Value
---                -----
lease_id           database/creds/app-db/Z9wXc8Kv...7Gq
lease_duration     1h
lease_renewable    true

The renewal succeeds, and lease_duration resets back to 1 hour. But remember: total renewals must not exceed the role's max_ttl (24 hours in our example role).

3. Expire — TTL exhausted without renewal, Vault revokes automatically.

If the application never renews and the lease reaches its TTL, Vault automatically revokes the credential at the backend (for example, deleting the user in PostgreSQL). Applications still using the old credential will start getting connection errors.

4. Revoke — instant manual revocation.

vault lease revoke database/creds/app-db/Z9wXc8Kv...7Gq

All revocation operations queued successfully!

#Emergency Revocation: Destroying Access in Seconds

This is the most operationally important moment. When a credential leaks — for example, pushed to GitHub, lost to a keylogger, or appearing in public logs — you must revoke access instantly, not wait for the TTL. Vault provides several levels of revocation:

1. Revoke a specific lease

vault lease revoke database/creds/app-db/Z9wXc8Kv...7Gq

2. Revoke all leases under a prefix — the kill switch

vault lease revoke -prefix database/creds/

All revocation operations queued successfully!

The command above destroys every database credential ever issued from the database/ mount — all applications using dynamic credentials will be cut off instantly and must fetch new ones. This is the nuclear weapon for handling mass leaks.

3. Revoke by role

vault lease revoke -prefix database/creds/app-db

4. Revoke an entire token and its descendant leases

vault token revoke hvs.CAESILf...

vault token revoke -mode=all -accessor <accessor>

#Automatic Renewal Patterns in Applications

Short-TTL secrets mean applications must be lifecycle-aware: renew before expiry, or re-login if already expired. There are three common patterns:

A common rule of thumb: refresh the lease at around 67% of the TTL — don't wait until near expiry, because a failed renewal right before expiry risks the application using dead credentials. A simple illustration of the loop:

TTL = 1 hour
while lease is active:
    sleep TTL * 2/3          # sleep 40 minutes
    vault lease renew $LEASE_ID

When the last renewal is rejected (because the max TTL is reached), the application should fetch new credentials, not force using the old ones:

vault read database/creds/app-db

This pattern becomes automatic and tidy with Vault Agent in episodes 14 and 15, but the manual understanding in this episode lets you know what the Agent is actually doing behind the scenes.

#Incident Scenario: Production Credential Leak

Let's train your reflexes with a real scenario. At 03:00, monitoring sends an alert: a database credential with the username v-app-db-AJ4kLp3R... appears in the public logs of a third-party logging service.

The correct steps (in order):

1. Revoke first — don't panic over diagnosis.

vault lease revoke database/creds/app-db/Z9wXc8Kv...7Gq

2. Revoke the source token (if known).

vault token revoke hvs.CAESILf...

3. Rotate remaining credentials under the same prefix.

vault lease revoke -prefix database/creds/app-db

4. Verify at the backend: the database user is gone.

SELECT usename FROM pg_user WHERE usename LIKE 'v-app-db-%';

5. Let the application fetch new credentials, then audit.

Because the credentials are dynamic, the application just reads database/creds/app-db again and gets a healthy new user. No old password to change manually, no long downtime. This is the difference between secret management and static passwords.

#Tracking Active Leases: vault lease list

In a production system, active leases can number in the thousands. The ability to monitor them is crucial for keeping the backend healthy and ensuring no "orphaned leases" accumulate.

vault lease list -prefix database/creds/

Keys
----
database/creds/app-db/Z9wXc8Kv...7Gq
database/creds/app-db/Aj8Lm4Rt...2Xb
database/creds/analytics/Kp1Qs6Wd...9Nc

With vault lease list you can see all leases still recorded on a given mount, check their cleanliness, and identify whether any credentials were forgotten to be revoked after their app was shut down. Leases that keep growing without ever decreasing are a sign that an application uses the "fetch credentials but never revoke" pattern — not immediately fatal since the TTL will finish them, but still wasteful of backend resources (e.g. database users continuously created).

#The Token-Lease Relationship: Revoke Token = Revoke Subtree

Tokens and leases are connected in a hierarchy. When a token is issued from another token (for example, an AppRole login produces a token, then that token creates additional tokens for other processes), all descendant tokens and the leases they produce are part of one subtree.

Revoking the parent token has a chain effect:

vault token revoke hvs.CAESILf...

The output will list that revocation was queued for all descendant leases:

All revocation operations queued successfully!

This is why using per-application tokens (not shared tokens) matters: when an application is deemed contaminated, you just revoke its token, and all credentials produced through that token are destroyed with it. One door, and all its keys break.

#Common Lease, TTL & Revocation Mistakes

#Conclusion

In this episode we've covered Lease, TTL, Renewal & Revocation: the lease concept as a time contract for every dynamic secret, the TTL layers that constrain each other, how to extend leases with vault lease renew, and instant access revocation with vault lease revoke — both per-lease and per-prefix. We also learned automatic renewal patterns and the correct sequence of steps during a credential leak incident.

The essence of this episode: Vault's greatest advantage isn't just storing secrets, but its ability to make secrets "alive" (TTL-bound) and destroy them instantly. As an SRE, this revoke capability is what turns a credential incident from a multi-hour nightmare into a one-minute operation.

In episode 13, we'll cover how to deliver secrets — including the AppRole SecretID — securely to a new server: Response Wrapping & Cubbyhole for secret delivery without plaintext transit. Keep your enthusiasm up!