HashiCorp Vault Leases - Complete Lifecycle Management Guide
🎯 Prerequisites:
Vault Fundamentals →
Authentication Methods →
Policies & Access Control →
Token Management →
Secrets Engines
📚 What You'll Master:
Complete lease lifecycle management: renewal strategies, revocation patterns, TTL inheritance, prefix operations, production use cases
📚 What You'll Master:
Complete lease lifecycle management: renewal strategies, revocation patterns, TTL inheritance, prefix operations, production use cases
Table of Contents
Vault Leases Overview
What Are Vault Leases?
One of the key features of dynamic secrets is their limited lifetime. But how is that lifetime enforced by Vault? Through vault leases - the mechanism that controls the lifecycle of dynamically generated credentials.
🔑 Core Purpose:
Leases control the lifecycle of dynamic secrets by either:
Leases control the lifecycle of dynamic secrets by either:
- Renewing - Extending the lifetime of a dynamic secret
- Revoking - Terminating the dynamic secret before expiration
Leases Apply to Both Secrets and Tokens
Leases are a construct that exists for both dynamic secrets and service tokens:
| Aspect | Dynamic Secrets | Service Tokens |
|---|---|---|
| Terminology | Leases | TTL (Time to Live) |
| Lifecycle | Managed via lease commands | Managed via token commands |
| Common Feature | Both have limited lifetime and managed lifecycle | |
📊 Key Difference:
Same concept, different language. Dynamic secrets use "lease" terminology while service tokens use "TTL" terminology, but both represent a limited lifetime that you can manage through renewal or revocation.
Same concept, different language. Dynamic secrets use "lease" terminology while service tokens use "TTL" terminology, but both represent a limited lifetime that you can manage through renewal or revocation.
Lease Properties & Metadata
Three Core Lease Properties
Every lease includes metadata that defines its characteristics and behavior:
✅ Lease Metadata Components:
- lease_id - Unique identifier constructed from path + unique ID
- lease_duration - Countdown timer showing remaining validity period
- renewable - Boolean indicating whether lease can be extended
Lease ID Structure
The lease_id is a construct that combines:
Format: <path_to_secret>/<unique_id>
Example: consul/creds/web/a1b2c3d4-e5f6-7890-abcd-ef1234567890
Components:
• Path: consul/creds/web
• Unique ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Lease Duration
Lease duration functions as a countdown timer:
- Initial Value - Set from default TTL at creation time
- Countdown - Continuously decreases until expiration
- Example - Starts at 30 minutes, counts down to zero
- Expiration Behavior - When duration reaches zero, lease and secret are revoked
Renewable Property
The renewable Boolean determines lease extension capability:
- true - Lease can be renewed/extended before expiration
- false - Fixed lifetime from creation, cannot be extended
- Configuration - Set at object level (role, group, user) within secrets engine
⚠️ No Direct Lookup Command:
Unlike tokens which have
Unlike tokens which have
vault token lookup, there is no vault lease lookup command. You must use the special path /sys/leases/lookup to retrieve lease information.
Lease Duration & TTL Inheritance
Understanding Lease Duration
Lease duration is essentially the Time to Live (TTL) for a dynamic secret. Just like tokens have TTLs, dynamic secrets have lease durations that determine their validity period.
TTL Value Sources
When a dynamic secret or token is created, it inherits TTL values from multiple potential sources. The lease derives two critical values:
- Default TTL - Initial lease duration when secret is created
- Max TTL - Maximum allowable lifetime for the lease
TTL Inheritance Hierarchy
TTL values are inherited in a specific precedence order, from most general to most specific:
🎯 TTL Precedence (Lowest to Highest):
- System-Wide Defaults - Vault server configuration settings
- Mount Point Configuration - Secrets engine mount settings
- Object-Level Settings - Role, group, or user configuration
1. System-Wide Default TTL
Definition: Global default and max TTL defined in Vault server configuration
Scope: Applies to all leases and tokens unless overridden
Priority: Lowest - Used only when no other TTL is specified
Configuration: Set in Vault server config file
2. Mount Point TTL
Definition: Default and max TTL configured on secrets engine mount
Scope: Applies to all secrets from that specific engine
Priority: Medium - Overrides system-wide settings
Configuration: Set during engine enablement or via tune command
Example: vault secrets tune -default-lease-ttl=30m aws
3. Object-Level TTL
Definition: TTL configured on specific objects within secrets engine
Scope: Applies only to secrets generated from that object
Priority: Highest - Overrides both system and mount settings
Object Types: Roles, groups, users (depends on engine type)
Example: vault write consul/roles/web ttl=1h max_ttl=2h
TTL Inheritance Example
| Level | Default TTL | Max TTL | Applied? |
|---|---|---|---|
| System | 32 days | 32 days | ❌ Overridden |
| Mount Point | 30 minutes | 2 hours | ❌ Overridden |
| Role (Object) | 1 hour | 4 hours | ✅ Applied |
🎯 Key Concept:
The most specific configuration wins. Object-level settings override mount settings, which override system settings. This allows granular control over lease lifetimes for different use cases.
The most specific configuration wins. Object-level settings override mount settings, which override system settings. This allows granular control over lease lifetimes for different use cases.
Renewable Property Configuration
The renewable property is set at the object level within the secrets engine:
Configuration Example:
vault write consul/roles/web \
policies="web" \
ttl=1h \
max_ttl=2h \
renewable=false
Result: Secrets from this role cannot be renewed
Lease Actions: Renewal & Revocation
Two Primary Lease Operations
When working with leases, you can perform two fundamental operations:
- Renew - Extend the lease lifetime
- Revoke - Terminate the lease before expiration
Lease Renewal
Renewal Characteristics:
✅ How Renewal Works:
- Time Basis - Renewal is based on current time, not creation time
- Increment Specification - Request renewal for specific duration (e.g., 30 minutes)
- Countdown Reset - Lease duration resets to specified increment from now
- Max TTL Constraint - Total duration from creation cannot exceed max TTL
Renewal Example:
Initial State:
• Created: 12:00 PM
• Default TTL: 1 hour
• Max TTL: 2 hours
• Current Time: 12:30 PM (30 minutes elapsed)
• Remaining: 30 minutes
Renewal Request at 12:30 PM:
vault lease renew -increment=30m <lease_id>
Result:
• New expiration: 1:00 PM (30 minutes from now)
• Total lifetime: 1 hour (within max TTL of 2 hours) ✅
Invalid Renewal Request at 12:30 PM:
vault lease renew -increment=2h <lease_id>
Result:
• Requested expiration: 2:30 PM (2 hours from now)
• Total lifetime: 2.5 hours (exceeds max TTL) ❌
• Vault response: Lease extended to max available (1:30 PM)
⚠️ Max TTL Enforcement:
If your renewal request would push the total lease lifetime beyond the max TTL (calculated from creation time), Vault will extend the lease only to the maximum allowable duration.
If your renewal request would push the total lease lifetime beyond the max TTL (calculated from creation time), Vault will extend the lease only to the maximum allowable duration.
Lease Revocation
Revocation Process:
🔴 Revocation Sequence:
- Lease Revocation - Vault immediately invalidates the lease
- Queue Deletion Request - Vault queues request to secrets engine
- External Cleanup - Secrets engine deletes credential in external system
Example Scenario:
AWS Secrets Engine:
1. You revoke AWS credentials lease
2. Vault immediately marks lease as invalid
3. Vault queues deletion request to AWS
4. AWS secrets engine contacts AWS API
5. IAM credentials deleted from AWS account
Note: Add -sync flag to wait for external confirmation
Token Revocation Cascade
🎯 Important Behavior:
When you revoke a token, Vault automatically revokes all dynamic secrets generated by that token.
Example:
• Token generates 5 AWS credentials
• Token generates 3 database credentials
• Revoke the token
• Result: All 8 credentials are automatically revoked
When you revoke a token, Vault automatically revokes all dynamic secrets generated by that token.
Example:
• Token generates 5 AWS credentials
• Token generates 3 database credentials
• Revoke the token
• Result: All 8 credentials are automatically revoked
Prefix Revocation
Prefix revocation allows mass revocation of all leases matching a specific path prefix.
🚨 Critical Warnings:
- Requires Elevated Permissions - Sudo capability needed
- Extremely Destructive - Revokes ALL leases on path
- No Confirmation Prompt - Immediate execution
- Use Case - Security breach response, credential rotation
Prefix Revocation Example:
vault lease revoke -prefix consul/creds/web/
Effect: Revokes all Consul credentials from web role
Impact: All applications using these credentials lose access
Recovery: Applications must request new credentials
CLI Commands for Lease Management
Lease Command Overview
All lease management at the CLI uses the vault lease command set.
Renew a Lease
Syntax:
vault lease renew [options] <lease_id>
Example:
vault lease renew -increment=30m consul/creds/web/a1b2c3d4
Options:
• -increment=<duration> - Requested extension duration
• -format=json - Output in JSON format
Revoke a Single Lease
Syntax:
vault lease revoke [options] <lease_id>
Example:
vault lease revoke consul/creds/web/a1b2c3d4
Options:
• -sync - Wait for external system confirmation
Revoke by Prefix
Syntax:
vault lease revoke -prefix <path_prefix>
Example:
vault lease revoke -prefix consul/creds/web/
Effect: Revokes ALL leases starting with specified prefix
⚠️ Warning: Requires sudo permissions, extremely destructive
List Leases
Syntax:
vault list sys/leases/lookup/<path>
Example:
vault list sys/leases/lookup/consul/creds/web/
Output: List of active lease IDs at specified path
Note: Returns unique IDs only, prepend path to get full lease_id
Lookup Lease Properties
Syntax:
vault write sys/leases/lookup lease_id=<lease_id>
Example:
vault write sys/leases/lookup lease_id=consul/creds/web/a1b2c3d4
Output Properties:
• expire_time - When lease expires (calculated from last renewal)
• issue_time - Original creation timestamp
• last_renewal - Most recent renewal timestamp
• renewable - Boolean indicating if lease can be renewed
• ttl - Current remaining time to live
⚠️ Lookup Command Quirk:
Unlike most operations, lease lookup requires
Unlike most operations, lease lookup requires
vault write (not vault read) because you must submit data (the lease_id) as part of the request.
Complete Command Reference
| Operation | Command | Purpose |
|---|---|---|
| Renew | vault lease renew -increment=30m <id> |
Extend lease lifetime |
| Revoke | vault lease revoke <id> |
Terminate single lease |
| Prefix Revoke | vault lease revoke -prefix <path> |
Mass revocation by path |
| List | vault list sys/leases/lookup/<path> |
Get active lease IDs |
| Lookup | vault write sys/leases/lookup lease_id=<id> |
Get lease properties |
Production Use Cases
Use Case 1: AWS Credentials with Auto-Renewal
🎯 Globomantics Scenario:
Requirement: Application needs AWS resource access with automatic credential lifecycle management.
Requirements:
Requirement: Application needs AWS resource access with automatic credential lifecycle management.
Requirements:
- On-demand credential generation
- Automatic revocation after 12 hours of inactivity
- Application remains active with credential renewal
Solution Architecture:
- Enable AWS Secrets Engine
vault secrets enable aws - Configure Role with 12-Hour Lease
vault write aws/roles/app-role \
credential_type=iam_user \
policy_document=@policy.json \
default_ttl=12h \
max_ttl=24h - Application Behavior
- Request AWS credentials at startup
- Renew credentials every 11 hours (before expiration)
- If inactive for 12 hours, credentials auto-revoke
- On activity resume, request new credentials
🎯 Benefits:
- No permanent credentials stored in application
- Automatic cleanup of inactive application credentials
- Active applications maintain access through renewal
- 12-hour inactivity threshold ensures security
Use Case 2: Consul Tokens with Fixed Expiration
🎯 Globomantics Scenario:
Requirement: Multiple users need Consul tokens with strict expiration and breach response capability.
Requirements:
Requirement: Multiple users need Consul tokens with strict expiration and breach response capability.
Requirements:
- Regular Consul token access for multiple users
- Fixed 60-minute token lifetime (non-renewable)
- Ability to revoke all tokens instantly if breach detected
Solution Architecture:
- Enable Consul Secrets Engine
vault secrets enable consul - Configure Role with Non-Renewable 60-Minute TTL
vault write consul/roles/user-role \
policies="user-policy" \
ttl=60m \
max_ttl=60m \
renewable=false - Normal Operations
- Users request Consul tokens as needed
- Tokens expire after exactly 60 minutes
- Users request new tokens when needed
- Breach Response
vault lease revoke -prefix consul/creds/user-role/- Instantly revokes ALL user tokens
- Users request new tokens after incident resolution
🎯 Benefits:
- Fixed 60-minute maximum exposure window
- No token renewal prevents indefinite access
- Prefix revocation enables rapid breach response
- Forces regular credential rotation through expiration
Complete Hands-On Lab
Lab Environment Setup
Terminal 1 - Start Vault Server:
vault server -dev
Terminal 2 - Configure Environment:
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='<root_token>'
vault login ${VAULT_TOKEN}
Terminal 3 - Start Consul Agent:
consul agent -dev -config-dir=./config
Lab Prerequisites
This lab assumes you have already completed the Consul secrets engine setup from the previous module:
- Consul agent running with ACL enabled
- Consul secrets engine enabled in Vault
- Consul role configured with 1h TTL and 2h max TTL
Lab 1: Generate Leases
Generate Multiple Consul Credentials:
# Generate first credential
vault read consul/creds/web
# Output shows:
# lease_id: consul/creds/web/a1b2c3d4-e5f6-7890...
# lease_duration: 3600 (1 hour)
# lease_renewable: true
# token: <consul_token>
# Generate three more credentials
vault read consul/creds/web
vault read consul/creds/web
vault read consul/creds/web
📊 Lease ID Structure:
• Path:
• Unique ID:
consul/creds/web/a1b2c3d4-e5f6-7890-abcd-ef1234567890• Path:
consul/creds/web• Unique ID:
a1b2c3d4-e5f6-7890-abcd-ef1234567890
Lab 2: Renew a Lease
Standard Renewal:
# Renew with 30-minute increment
vault lease renew -increment=30m consul/creds/web/a1b2c3d4...
# Output:
# lease_id: consul/creds/web/a1b2c3d4...
# lease_duration: 1800 (30 minutes)
# lease_renewable: true
# Note: Original 1-hour lease shortened to 30 minutes!
⚠️ Renewal Behavior:
Specifying
Specifying
-increment=30m sets the lease duration to 30 minutes from NOW, not adding 30 minutes to remaining time. This can actually shorten the lease if the increment is less than remaining duration.
Lookup Lease Properties:
# Check lease details
vault write sys/leases/lookup lease_id=consul/creds/web/a1b2c3d4...
# Output shows:
# expire_time: 2025-11-20T13:30:00Z (calculated from last renewal)
# issue_time: 2025-11-20T12:00:00Z (original creation)
# last_renewal: 2025-11-20T13:00:00Z (most recent renewal)
# renewable: true
# ttl: 1757 (29 minutes, 17 seconds remaining)
# Run again to see countdown
vault write sys/leases/lookup lease_id=consul/creds/web/a1b2c3d4...
# ttl: 1719 (28 minutes, 39 seconds remaining)
Lab 3: Exceed Max TTL
Attempt to Exceed Maximum:
# Try to renew for 2 hours
vault lease renew -increment=2h consul/creds/web/a1b2c3d4...
# Vault response:
# WARNING: Request could not be honored
# Effective max TTL less than requested increment
# Max available from creation time: 2 hours
# Requested from renewal time: 2 hours
# Result: Lease capped at maximum available (1h 57m)
# lease_id: consul/creds/web/a1b2c3d4...
# lease_duration: 7020 (1 hour, 57 minutes)
# lease_renewable: true
🎯 Max TTL Calculation:
• Original creation: 12:00 PM
• Max TTL: 2 hours (expires at 2:00 PM)
• Renewal request at: 12:03 PM
• Requested increment: 2 hours (would expire at 2:03 PM)
• Vault caps at: 1:57 minutes remaining (expires at 2:00 PM exactly)
• Original creation: 12:00 PM
• Max TTL: 2 hours (expires at 2:00 PM)
• Renewal request at: 12:03 PM
• Requested increment: 2 hours (would expire at 2:03 PM)
• Vault caps at: 1:57 minutes remaining (expires at 2:00 PM exactly)
Lab 4: List Active Leases
# Get list of active lease IDs
vault list sys/leases/lookup/consul/creds/web/
# Output (unique IDs only):
# Keys
# ----
# a1b2c3d4-e5f6-7890-abcd-ef1234567890
# b2c3d4e5-f6a7-8901-bcde-f12345678901
# c3d4e5f6-a7b8-9012-cdef-123456789012
# d4e5f6a7-b8c9-0123-def1-234567890123
# Note: Prepend "consul/creds/web/" for full lease_id
Lab 5: Revoke Single Lease
# Revoke specific lease
vault lease revoke consul/creds/web/a1b2c3d4-e5f6-7890-abcd-ef1234567890
# Output:
# Success! Revoked lease: consul/creds/web/a1b2c3d4...
# (queued for deletion in Consul)
# Verify revocation
vault list sys/leases/lookup/consul/creds/web/
# Output (first ID now missing):
# Keys
# ----
# b2c3d4e5-f6a7-8901-bcde-f12345678901
# c3d4e5f6-a7b8-9012-cdef-123456789012
# d4e5f6a7-b8c9-0123-def1-234567890123
Lab 6: Prefix Revocation
# Revoke ALL leases at path
vault lease revoke -prefix consul/creds/web/
# Output:
# Success! Revoked leases (queued for deletion):
# consul/creds/web/b2c3d4e5...
# consul/creds/web/c3d4e5f6...
# consul/creds/web/d4e5f6a7...
# Verify all leases gone
vault list sys/leases/lookup/consul/creds/web/
# Output:
# No value found at sys/leases/lookup/consul/creds/web/
🚨 Production Warning:
Prefix revocation immediately invalidates ALL credentials at the specified path. In production:
Prefix revocation immediately invalidates ALL credentials at the specified path. In production:
- Verify path before executing
- Coordinate with application teams
- Plan for credential reissuance
- Document as part of incident response
Lab 7: Verify Consul Token Revocation
# List Consul ACL tokens
consul acl token list -format json | jq -r '.[].AccessorID'
# Before revocation: Shows multiple tokens
# After revocation: Vault-generated tokens removed
# Demonstrates end-to-end lifecycle:
# 1. Vault generates Consul token
# 2. Vault manages lease
# 3. Vault revokes lease
# 4. Vault deletes token in Consul
Production Best Practices
🎯 Deployment Guidelines:
- Renewal Strategy - Implement renewal before 75% of lease duration expires
- Error Handling - Handle renewal failures gracefully, request new credentials
- TTL Configuration - Set appropriate defaults for application types:
- Short-lived: User sessions (30m-1h)
- Medium-lived: Application credentials (4h-12h)
- Long-lived: Service accounts (24h max)
- Max TTL Enforcement - Always set max TTL to enforce credential rotation
- Monitoring - Track lease expiration patterns and renewal failures
- Incident Response - Document prefix revocation procedures
- Testing - Test renewal and revocation in staging before production
- Automation - Automate lease renewal in application code
Key Takeaways
- Universal Leases - All dynamic secrets and service tokens have leases/TTLs
- Renewal Timing - Based on current time, not creation time
- Max TTL Constraint - Total lifetime from creation cannot exceed max TTL
- Revocation Process - Immediate lease invalidation, queued external deletion
- Token Cascade - Revoking a token revokes all associated dynamic secrets
- Prefix Power - Mass revocation requires sudo, use with extreme caution
- No Direct Lookup - Use
/sys/leases/lookuppath for lease properties - Lifecycle Management - Implement automated renewal and error handling
What's Next?
With lease management mastered, you now have complete control over the Vault ecosystem: authentication, authorization, secrets storage and generation, and credential lifecycle management. The next steps involve production deployment topics like high availability, disaster recovery, and enterprise features.
🎯 Practice Challenge:
Build a complete credential lifecycle system:
Build a complete credential lifecycle system:
- Configure multiple secrets engines with different TTL strategies
- Implement automated lease renewal in application code
- Create monitoring for lease expiration patterns
- Design incident response plan with prefix revocation procedures
- Test renewal failures and credential reacquisition
- Build dashboard showing active leases and expiration timeline
Congratulations! You've completed the HashiCorp Vault Associate certification learning path covering fundamentals, authentication, policies, tokens, secrets engines, and lease management. You're now equipped to implement enterprise-grade secrets management with complete lifecycle control!