Lease count quotas

Vault features an extension to resource quotas that allows operators to enforce limits on how many leases are created. For a given lease count quota, if the number of leases in the cluster hits the configured limit, max_leases, additional lease creations will be forbidden for all clients until the an operator modifies the configured limit, or a lease has been revoked or expired.

Lease count quotas guard against lease explosions.

Root tokens

It is important to note that lease count quotas do not apply to the root tokens. If the number of leases in the cluster hits the configured limit, max_leases, an operator can still create a root token and access the cluster to try to recover.

Batch tokens

Batch token creation is blocked when the lease count quota is exceeded, but batch tokens do not count toward the quota.

All the nodes in the Vault cluster share the lease quota rules, meaning that the lease counters are shared, regardless of which node in the Vault cluster receives lease generation requests. Lease quotas can be imposed across Vault's API, or scoped down to API pertaining to specific namespaces or specific mounts.

Lease count quota inheritance

A quota that is defined in the root namespace with no specified path is inherited by all namespaces. This type of quota is referred to as a global quota. Global quotas applie to the entire Vault API unless a more specific quota (higher precedence) quota has been defined.

Lease count quota precedence

Lease count quota precedence is dictated by highest to lowest level of specificity. The rules are as follows:

1. Global lease count quotas are applied to all mounts and namespaces only if no other, more specific namespace is defined.
2. Lease count quotas defined on a namespace take precedence over the global quotas.
3. Lease count quotas defined for a mount will take precedence over global and namespace quotas.
4. Lease count quotas defined for a specific path will take precedence over global, namespace, and mount quotas.
5. Lease count quotas defined with a login role for a specific auth mount will take precedence over every other quota when applying to login requests using that auth method and the specified role.

The limits on quotas can either be increased or decreased. If a lower precedence quota is very restrictive and if it is desired to relax the limits in one namespace, or on a specific mount, it can be done using this precedence model. On the other hand, if a lower precedence quota is very liberal and if it is desired to further restrict usages in a specific namespace or mount, that can be done using the precedence model too.

Default lease count quota

As of Vault 1.16.0, new installations of Vault Enterprise will include a default global quota with a max_leases value of 300000. This value is an intentionally low limit, intended to prevent runaway leases in the event that no other lease count quota is specified.

This limit will affect all new clusters with no pre-existing configuration. As with any other quota, the default can be directly increased, decreased, or removed using the lease-count-quotas endpoints.

The default may also be overridden by higher precedence quotas (specified for a namespace, mount, path, or role) as described in the Lease count quota precedence section above.

Quota inspection

Vault also allows the inspection of the state of lease count quotas in a Vault cluster through various metrics and through enabling optional audit logging.

Lease count quota exceeded

Vault returns a 429 - Too Many Requests response if a new lease request violates the quota limit. For more information on this error, refer to the error document.

Tutorial

Refer to Protecting Vault with Resource Quotas for a step-by-step tutorial.

API

Lease count quotas can be managed over the HTTP API. Please see Lease Count Quotas API for more details.