From 2f50f88813c13e8d0fa43d40a7fd9219f1e00536 Mon Sep 17 00:00:00 2001 From: Violet Hynes Date: Tue, 2 Aug 2022 15:37:56 -0400 Subject: [PATCH] VAULT-6615 Update docs for 1.12 quota changes (#16381) * 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> --- .../api-docs/system/lease-count-quotas.mdx | 20 ++++++++++---- .../api-docs/system/rate-limit-quotas.mdx | 20 ++++++++++---- .../content/docs/concepts/resource-quotas.mdx | 21 +++++++++------ .../docs/enterprise/lease-count-quotas.mdx | 26 ++++++++++++------- 4 files changed, 59 insertions(+), 28 deletions(-) diff --git a/website/content/api-docs/system/lease-count-quotas.mdx b/website/content/api-docs/system/lease-count-quotas.mdx index 0c0030988a..0f28cc9368 100644 --- a/website/content/api-docs/system/lease-count-quotas.mdx +++ b/website/content/api-docs/system/lease-count-quotas.mdx @@ -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 diff --git a/website/content/api-docs/system/rate-limit-quotas.mdx b/website/content/api-docs/system/rate-limit-quotas.mdx index f845e85ece..5de9139228 100644 --- a/website/content/api-docs/system/rate-limit-quotas.mdx +++ b/website/content/api-docs/system/rate-limit-quotas.mdx @@ -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 diff --git a/website/content/docs/concepts/resource-quotas.mdx b/website/content/docs/concepts/resource-quotas.mdx index 2e33fb1ff3..0408612a94 100644 --- a/website/content/docs/concepts/resource-quotas.mdx +++ b/website/content/docs/concepts/resource-quotas.mdx @@ -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 diff --git a/website/content/docs/enterprise/lease-count-quotas.mdx b/website/content/docs/enterprise/lease-count-quotas.mdx index be55000b05..62149bc453 100644 --- a/website/content/docs/enterprise/lease-count-quotas.mdx +++ b/website/content/docs/enterprise/lease-count-quotas.mdx @@ -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)