Overview

Vault Enterprise features a centralized system to automate schedule-based or period-based credential rotation. Vault periodically evaluates pending rotations, and dispatches requests to the appropriate plugins.

Failure Handling

If a rotation attempt exceeds the maximum retry limits defined within a rotation policy, Vault marks the entry as orphaned. This state serves as a safety mechanism:

• Halts Automation: Further automated rotation attempts are paused to prevent loops or service degradation.
• Requires Intervention: Manual troubleshooting is necessary to resolve the root error and restore the credential to a healthy state.

For detailed recovery steps, please refer to the rotation orphaning documentation.

High availability

Automated rotations execute exclusively on the active node of a cluster. In the event of a leadership change, the new active node automatically restores the rotation state from storage and resumes processing rotations where the previous node left off.

For replicated clusters:

• Shared mounts: Rotations occur on the active node of the primary cluster.
• Local mounts: Rotations occur independently on the active node of each cluster.

Exponential backoff

When a rotation fails, Vault Enterprise requeues the rotation entry using an exponential backoff schedule to prevent continuous high-frequency retries from stressing the system. The backoff schedule also includes a randomized factor (jitter) to help ensure a more even load distribution. The backoff schedule has 3 elements:

1. Initial delay - The first retry attempt is scheduled after a brief minimum wait period.
2. Doubling interval - Subsequent delays increase exponentially based on the previous interval, with jitter applied to further stagger the retry attempts.
3. Maximum cap - Vault enforces an upper limit on the delay for any single retry. Once this cap is reached, subsequent attempts continue at that fixed interval until the rotation succeeds or the entry is orphaned.

Policy-driven

Vault Enterprise supports rotation policies to be set that define the retry behavior for a given scheduled rotation. Read the rotation policy documentation for more information on how to configure rotation policies and their effect on Vault's retry behavior. The API documentation also includes details regarding management of rotation policies.

Checking a rotation status

Read the role or credential in the plugin to check the rotation status. The response includes three primary fields for finding out this status and the next scheduled rotation.

1. The last_vault_rotation field is the timestamp of the last successful rotation performed by Vault. It is updated when an automated rotation succeeds and also when a manual rotation occurs between scheduled rotations.
2. The next_vault_rotation field is the timestamp of the next scheduled automatic rotation. This field is not updated when a manual rotation succeeds because the next scheduled rotation will still occur at the originally-scheduled time.
3. The ttl field is the number of seconds remaining until the next scheduled rotation begins. This field is not updated for the same reason as the next_vault_rotation field.

For example, reading an LDAP static role credential may include the following information:

$ vault read ldap/static-cred/my-role

Key                            Value
---                            -----
last_vault_rotation    2026-04-02T23:30:00Z
next_vault_rotation    2026-04-03T11:30:00Z
ttl                    84600
...

Troubleshooting

Vault Enterprise logs rotation activity to the Vault server logs such as successful rotations, rotation failures, retry attempts, and orphaning. Vault includes metadata in the log statements to identify the credential being rotated and error information in the case of a failure. For example:

[INFO]  rotation-job-manager: successfully rotated job: rotationID=database/config/my-database
[ERROR] rotation-job-manager: rotation failed, attempting to re-queue: rotationID=database/config/my-database error="connection refused"
[ERROR] rotation-job-manager: orphaning item, please re-register after resolving the error: rotationID=database/config/my-database

Migration from legacy rotation system in plugins

We recommend monitoring the full migration process through the static-migration endpoint of the given plugin. For example, the LDAP secrets engine static role migration uses the /static-migration endpoint.

The migration process runs in the background and does not prevent ordinary operation of the plugin. Vault pauses individual static role rotations until the role migrates. Once the role migrates, the normal rotation schedule resumes.

Supported plugins have a dedicated monitoring endpoint. Refer to the individual plugin API documentation for more details on managing the migration process.