upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-06-09 08:55:13 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 11

VAULT-6615 Update docs for 1.12 quota changes (#16381)

Browse source 
* VAULT-6615 Update docs for 1.12 quota changes

* VAULT-6615 Add info about globbing

* VAULT-6615 some small updates for role param

* Update website/content/docs/enterprise/lease-count-quotas.mdx

Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>

* Update website/content/api-docs/system/lease-count-quotas.mdx

Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>

Co-authored-by: Loann Le <84412881+taoism4504@users.noreply.github.com>
This commit is contained in:
Violet Hynes 2022-08-02 15:37:56 -04:00 committed by GitHub
parent 89750ef7dd
commit 2f50f88813
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 59 additions and 28 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
website/content/api-docs/system/lease-count-quotas.mdx
View file

@ -14,7 +14,8 @@ The `/sys/quotas/lease-count` endpoint is used to create, edit and delete lease
This endpoint is used to create a lease count quota with an identifier, `name`.
A lease count quota must include a `max_leases` value with an optional `path`
that can either be a namespace or mount.
that can either be a namespace or mount, and can optionally include a path suffix following
the mount to restrict more specific API paths.
| Method | Path |
| :----- | :------------------------------ |
@ -26,12 +27,20 @@ that can either be a namespace or mount.
- `path` `(string: "")` - Path of the mount or namespace to apply the quota.
A blank path configures a global lease count quota. For example `namespace1/`
adds a quota to a full namespace, `namespace1/auth/userpass` adds a quota to
`userpass` in `namespace1`. Updating this field on an existing quota can have
"moving" effects. For example, updating `auth/userpass` to
`namespace1/auth/userpass` moves this quota from being a global mount quota to a
namespace specific mount quota. Quotas on a non-root namespace are not inherited by child
`userpass` in `namespace1`, and `namespace1/kv-v2/data/foo/bar` adds a quota to
a specific secret on a K/V v2 mount in `namespace1`. A trailing glob (`*`) can also
be added as part of the path after the mount to match paths that share the same prefix
prior to the glob. `namespace1/kv-v2/data/foo/*` would match both `namespace1/kv-v2/data/foo/bar`
and `namespace1/kv-v2/data/foo/baz`. Updating this field on an existing
quota can have "moving" effects. For example, updating `namespace1` to
`namespace1/auth/userpass` moves this quota from being a namespace quota to a
namespace-specific mount quota. Non-global quotas are not inherited by child
namespaces.
- `max_leases` `(int: 0)` - Maximum number of leases allowed by the quota rule.
- `role` `(string: "")` - If set on a quota where `path` is set to an auth mount with a
concept of roles (such as `/auth/approle/`), this will make the quota restrict login
requests to that mount that are made with the specified role. The request will fail if
the auth mount does not have a concept of roles, or `path` is not an auth mount.
### Sample Payload
@ -98,6 +107,7 @@ $ curl \
"max_leases": 1000,
"name": "global-lease-count-quota",
"path": "",
"role": "",
"type": "lease-count"
},
"warnings": null

20
website/content/api-docs/system/rate-limit-quotas.mdx
View file

@ -12,7 +12,8 @@ The `/sys/quotas/rate-limit` endpoint is used to create, edit and delete rate li
This endpoint is used to create a rate limit quota with an identifier, `name`.
A rate limit quota must include a `rate` value with an optional `path` that can
either be a namespace or mount.
either be a namespace or mount, and can optionally include a path suffix following
the mount to restrict more specific API paths.
| Method | Path |
| :----- | :----------------------------- |
@ -24,10 +25,14 @@ either be a namespace or mount.
- `path` `(string: "")` - Path of the mount or namespace to apply the quota.
A blank path configures a global rate limit quota. For example `namespace1/`
adds a quota to a full namespace, `namespace1/auth/userpass` adds a quota to
`userpass` in `namespace1`. Updating this field on an existing quota can have
"moving" effects. For example, updating `auth/userpass` to
`namespace1/auth/userpass` moves this quota from being a global mount quota to a
namespace specific mount quota. Quotas on a non-root namespace are not inherited by child
`userpass` in `namespace1`, and `namespace1/kv-v2/data/foo/bar` adds a quota to
a specific secret on a K/V v2 mount in `namespace1`. A trailing glob (`*`) can also
be added as part of the path after the mount to match paths that share the same prefix
prior to the glob. `namespace1/kv-v2/data/foo/*` would match both
`namespace1/kv-v2/data/foo/bar` and `namespace1/kv-v2/data/foo/baz`. Updating this field on
an existing quota can have "moving" effects. For example, updating `namespace1` to
`namespace1/auth/userpass` moves this quota from being a namespace quota to a
namespace specific mount quota. Non-global quotas are not inherited by child
namespaces. **Note, namespaces are supported in Enterprise only**.
- `rate` `(float: 0.0)` - The maximum number of requests in a given interval to
be allowed by the quota rule. The `rate` must be positive.
@ -35,6 +40,10 @@ either be a namespace or mount.
- `block_interval` `(string: "")` - If set, when a client reaches a rate limit
threshold, the client will be prohibited from any further requests until after
the 'block_interval' has elapsed.
- `role` `(string: "")` - If set on a quota where `path` is set to an auth mount with a
concept of roles (such as `/auth/approle/`), this will make the quota restrict login
requests to that mount that are made with the specified role. The request will fail if
the auth mount does not have a concept of roles, or `path` is not an auth mount.
### Sample Payload
@ -105,6 +114,7 @@ $ curl \
"name": "global-rate-limiter",
"path": "",
"rate": 897.3,
"role": "",
"type": "rate-limit"
},
"warnings": null

21
website/content/docs/concepts/resource-quotas.mdx
View file

@ -20,24 +20,29 @@ developers.
Vault provides a feature, resource quotas, that allows Vault operators to specify
limits on resources used in Vault. Specifically, Vault allows operators to create
and configure API rate limits.
and configure API rate limits. Users of Vault Enterprise have a second option, alongside
rate limits, [lease-count quotas](/docs/enterprise/lease-count-quotas), which can
limit the number of leases that can be in use at one time.
## Rate Limit Quotas
Vault allows operators to create rate limit quotas which enforce API rate
limiting using a [token bucket](https://en.wikipedia.org/wiki/Token_bucket) algorithm.
A rate limit quota can be created at the root level or defined on a namespace or
mount by specifying a `path` when creating the quota. The rate limiter is applied
to each unique client IP address on a per-node basis (i.e. rate limit quotas
are not replicated). A client may invoke `rate` requests at any given second,
A rate limit quota can be created at the root level or defined on a namespace,
mount, or full API path by specifying a `path` when creating the quota. The rate
limiter is applied to each unique client IP address on a per-node basis (i.e. rate limit
quotas are not replicated). A client may invoke `rate` requests at any given second,
after which they may invoke additional requests at `rate` per-second.
A rate limit quota defined at the root level (i.e. empty `path`) is inherited by
all namespaces and mounts. It acts as a single rate limiter for the entire Vault
API. A rate limit quota defined on a namespace takes precedence over the global
rate limit quota, and a rate limit quota defined for a mount takes precedence over
the global and namespace rate limit quotas. In other words, the most specific
quota rule will be applied.
rate limit quota, a rate limit quota defined for a mount takes precedence over
the global and namespace rate limit quotas, and a rate limit quota defined for
a specific path will take precedence over global, namespace, and mount quotas.
Additionally, quotas defined with a `role` to limit login requests made using
that role on the specified auth mount will take precedence over all other quotas.
In other words, the most specific quota rule will be applied.
A rate limit can be created with an optional `block_interval`, such that when set
to a non-zero value, any client that hits a rate limit threshold will be blocked

26
website/content/docs/enterprise/lease-count-quotas.mdx
View file

@ -25,17 +25,23 @@ the lease counters will be 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.
A quota that is defined in the `root` namespace is inherited by all namespaces
and mounts, essentially to the entire Vault API.
A quota that is defined in the `root` namespace with no specified path is inherited by all namespaces.
Essentially, it applies to the entire Vault API unless a more specific quota has been defined
for a specific API path.
Lease count quotas defined on a namespace will take precedence over the inherited
quotas. Lease count quotas defined for a mount will take precedence over inherited
and namespace quotas. The limits on the namespace and mount quotas can either be
increased or decreased. If the inherited 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 the inherited 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.
Lease count quotas defined on a namespace take precedence over the global
quotas. Lease count quotas defined for a mount will take precedence over global
and namespace quotas. Lease count quotas defined for a specific path will take precedence
over global, namespace, and mount quotas. 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.
Vault also allows the inspection into the state of lease count quotas in a Vault
cluster through various [metrics](/docs/internals/telemetry#Resource-Quota-Metrics)