Vault: lease, dynamic role and static role

A Vault dynamic secret does not exist without its lease: it is the object you read, renew and revoke to control the life of a credential. This lesson shows that lease in practice (lease_id, duration, renewal, mass revocation by prefix), then the difference between a dynamic role, which creates an account on demand, and a static role, which renews the password of an existing account.

The principle, the three models of credentials, the choice of engine and the limits of dynamic secrets are covered in Static vs dynamic secrets: a comparison, in particular its section "How does a dynamic secret work?". This page does not repeat them: it takes the Vault side, the commands that handle the lease.

What you will learn

• Read the output of a dynamic secret and extract its lease_id.
• Renew a lease within the max_ttl of the role.
• Revoke a lease, or all the leases of a prefix.
• Choose between a dynamic role and a static role.

What is a Vault lease?

A lease is the record by which Vault ties an issued credential to its expiry date: each time a dynamic path is read, Vault creates the credential, references it by a lease_id and schedules its deletion. Without a lease, Vault could neither renew nor revoke what it has issued. The duration of a lease is its TTL (time to live); the role also sets a ceiling, the max TTL, beyond which the lease can no longer be extended.

vault read database/creds/readonly

Key                Value
---                -----
lease_id           database/creds/readonly/abcd1234
lease_duration     1h
username           v-token-readonly-xyz123
password           A1B2c3D4e5F6g7H8

The output first contains the credential (username, password), then the lease_id, which is the identifier to keep: every following operation takes it as an argument. The lease_duration says how long the account stays valid. For a database, tracking the lease also serves to delete the user at expiry. The lease_id always starts with the path that issued it (database/creds/readonly/...), which makes the prefix revocation seen below possible.

For each lease, Vault remembers the issued secret, the token that asked for it, the expiry, and how to revoke it.

Which duration should you choose for a lease?

The duration comes from the role (default_ttl, max_ttl) and depends on the use: the more exposed the credential, the shorter its lifetime must be. The table gives orders of magnitude, not rules.

TTL	Use case
1h	DB access for a batch job
24h	Development session
4h	CI/CD job credentials
30 days	TLS certificates for services

Swipe to see more

How do you renew a lease?

Before expiry, the client extends the lease with the vault lease renew command followed by the lease_id. The renewal is capped by the max_ttl configured on the role: beyond it, you must ask for a new credential. The duration you request is a wish, not a guarantee (the Vault API documentation says the backend "may grant a different amount"): asking for more than the ceiling raises no error, Vault silently grants the ceiling. Always read the lease_duration in the response.

vault lease renew database/creds/readonly/abcd1234

Who renews?

In production, the real subject is not the vault lease renew command but the architecture: who renews (the app, a sidecar, Vault Agent), when, and what happens if the renewal fails? Plan this strategy before deployment. A sidecar is a helper process that runs next to the application; Vault Agent is the Vault client that can authenticate and renew leases on the application's behalf.

How does revocation work?

Revocation ends a lease before its expiry: Vault does not just forget the entry, it runs the cleanup on the target system. For a database, it deletes the user it created; for AWS, it deletes the IAM user of an iam_user role but cannot recall an STS session already issued, as the Vault AWS lesson explains. Two levels exist: a single lease, or all the leases under a path with the -prefix option.

# Revoke one specific lease
vault lease revoke database/creds/readonly/abcd1234

# Revoke all the leases of a prefix
vault lease revoke -prefix database/creds/readonly

Revocation by prefix is the emergency gesture: if you suspect that a credential issued by the readonly role has leaked, without knowing which one among dozens of open leases, a single command cuts every access of that role. The applications will have to ask for credentials again, which is precisely the intended behaviour.

For the revocation of a full incident (renewal, investigation, communication), see the lesson Responding to a compromised secret.

What is the difference between a dynamic role and a static role?

A dynamic role creates a new account at each read; a static role renews the password of an account that already exists. An engine such as Database offers two types of roles, which differ by what Vault does with the account: create it, or only renew its password. The pair does not exist identically in every engine; it is mostly a useful model for Database and for some AWS uses.

What is a dynamic role?

A dynamic role creates a new credential at each read, carried by its own lease. Two successive reads give two different accounts.

vault read database/creds/app-role
# → username: v-token-app-xyz123

vault read database/creds/app-role
# → username: v-token-app-abc456  (different!)

Each workload therefore has its own account, revocable individually. The price: the application must handle the renewal (or ask again), and the target system accumulates ephemeral accounts.

What is a static role?

A static role takes charge of an account that already exists and periodically renews its password. The user name does not change, only the value does.

vault read database/static-creds/legacy-app
# → username: legacy_app_user (fixed)
# → password: RotatedPass123 (changed periodically)

It is the compromise for legacy applications that require a stable user: automatic renewal of the password without changing the architecture. The downside: if several applications share the same static role, they share the account, and traceability per workload disappears.

Static role is not a static secret

A static role is not a KV secret. Vault manages the credential and renews its password automatically. The key is fixed, the value changes. For what a KV secret is, see Vault KV.

Dynamic role or static role?

The table sets the two side by side. The deciding row is the account on the target system: if the application can accept an account that appears and disappears, choose the dynamic role; if it requires a fixed user, the static role is the fallback.

	Dynamic role	Static role
Account on the target system	Created at each read	Already exists, Vault does not create it
Read path (Database)	database/creds/<role>	database/static-creds/<role>
What changes	The whole account	The password only
Traceability per workload	One account per lease	Shared if the account is shared

Swipe to see more

The choice of engine and the decision tree between KV, dynamic and federated identity are in Static vs dynamic secrets: a comparison. To configure a role end to end on PostgreSQL, see Vault Database.

What do dynamic secrets not solve?

A lease reduces the exposure time; it replaces neither the authentication of the workload to Vault, nor the policies that decide who reads which database/creds/<role> path, nor the monitoring of the audit logs. Vault also becomes a critical component: its high availability and the handling of a renewal that fails remain to be designed. The detail of these limits is in the section "What are the limits of dynamic secrets?" of Static vs dynamic secrets: a comparison.

Key points

1. Lease: the identifier (lease_id) of the dynamic secret, needed to renew and revoke it.
2. Renewal: capped by the role's max_ttl; decide who renews before deploying.
3. Revocation: on a database, vault lease revoke also deletes the account (AWS STS sessions stay valid until their TTL); -prefix cuts all the leases of a path.
4. Dynamic role: a new credential at each request.
5. Static role: an existing account whose password Vault renews (legacy).
6. Limits: authentication, policies, audit and high availability remain your responsibility.

Knowledge check

Check that the essentials of this lesson are in place. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

3 questions

3 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →