Rotation policies

Vault includes a rotation manager to enforce automated, schedule-based rotations for onboarded credentials. You can control how the rotation manager standardizes error-handling and tracks rotation lifecycles by providing instructions in the form of rotation policies. Rotation policies do not affect Vault access policies.

Vault currently supports policy rotation for the following workflows:

• LDAP secrets static roles
  Enterprise
• OS secrets static roles
  Enterprise

Once you create a rotation policy, you can assign that policy to new and existing roles. The rotation manager uses the policy instructions to manage retry and failure logic when automatically rotating credentials for the associated role.

Rotation policy parameters

Vault defines rotation policies in JSON and supports the following configuration parameters:

• max_retries_per_cycle (int:<required>) - The maximum number of times the rotation manager should apply backoff for rotation entries after a rotation failure.

• max_retry_cycles (int:<required>) - The maximum number of times the rotation manager should requeue rotation entries after reaching the max_retries_per_cycle limit. The rotation manager re-queues rotation entries to their next scheduled rotation.

Example rotation policy

{
  "max_retry_cycles": 3,
  "max_retries_per_cycle": 3
}

The example policy limits exponential backoff for a single rotation cycle to 3 attempts within a single retry cycle. If rotations fail after 3 attempts, the rotation manager will requeue the rotation entry with its original schedule and repeat the exponential backoff retry cycle. The example policy also limits the number of requeue attempts to a total of 3 times. If the rotation entry still fails after all 3 requeue attempts (total of 9 retry attempts), the rotation manager marks the credential rotation as orphaned and halts any further automated rotation attempts.

Default rotation policy

Vault applies a default rotation policy for supported plugins if you choose not to assign a custom rotation policy. The default policy limits retries with a backoff to 6 attempts and re-queues with the original rotation schedule to 3 attempts:

{
  "max_retry_cycles": 3,
  "max_retries_per_cycle": 6
}

Usage

You can assign rotation policies when configuring a new credential. For example, to associate the rotation policy custom-ldap-policy with a new LDAP role named alice:

$ vault write ldap/static-role/alice \
    dn="cn=alice,ou=users,dc=example,dc=com" \
    username="alice" \
    rotation_period="24h" \
    rotation_policy="custom-ldap-policy"

If you do not provide a rotation policy when creating a role, Vault uses the default policy. You can unset an assigned policy and force Vault to use the default policy by updating the role to unset the rotation_policy field:

vault write ldap/static-role/alice \
    dn="cn=alice,ou=users,dc=example,dc=com" \
    username="alice" \
    rotation_period="24h" \
    rotation_policy=""

The rotation manager fetches the latest policy updates on each requeue cycle, which means you may not see policy updates reflected immediately in Vault behavior.

Exponential backoff

When a rotation fails, the rotation manager re-queues 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 uses a minimum delay of 10 seconds.
2. Doubling interval - Subsequent delays double the previous backoff interval (e.g., 10s, 20s, 40s, 80s) and apply jitter to further stagger the retry attempt.
3. Maximum cap - Vault caps the delay for any single retry at 5 minutes (300 seconds).

Orphaned rotation attempts

To avoid becoming clogged with persistent errors, the rotation manager marks a rotation entry as orphaned if it exceeds the maximum retry limits in the associated rotation policy. Orphaning a rotation entry halts all further automated rotation attempts for the associated credential.

Restoring an orphaned rotation entry requires manual intervention:

1. Resolve any underlying errors that caused the rotation manager to orphan the credential.
2. Update the credential to reassign the rotation policy and re-register the entry with the rotation manager. You can use the same original configuration command to reregister the entry without changing the other configuration data.

For example, to reregister credentials for the alice role, you can reuse the previous command:

vault write ldap/static-role/alice \
    dn="cn=alice,ou=users,dc=example,dc=com" \
    username="alice" \
    rotation_period="24h" \
    rotation_policy="custom-ldap-policy"

You can check for orphans using the sys/rotation-orphans endpoint.