abf65c8a0b
* VAULT-5095 Update docs to reflect current behaviour * Update website/content/api-docs/system/lease-count-quotas.mdx Co-authored-by: Nick Cabatoff <ncabatoff@hashicorp.com> * Update website/content/api-docs/system/rate-limit-quotas.mdx Co-authored-by: Nick Cabatoff <ncabatoff@hashicorp.com> Co-authored-by: Nick Cabatoff <ncabatoff@hashicorp.com>
147 lines
3.8 KiB
Plaintext
147 lines
3.8 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: /sys/quotas/rate-limit - HTTP API
|
|
description: The `/sys/quotas/rate-limit` endpoint is used to create, edit and delete rate limit quotas.
|
|
---
|
|
|
|
# `/sys/quotas/rate-limit`
|
|
|
|
The `/sys/quotas/rate-limit` endpoint is used to create, edit and delete rate limit quotas.
|
|
|
|
## Create or Update a Rate Limit Quota
|
|
|
|
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.
|
|
|
|
| Method | Path |
|
|
| :----- | :----------------------------- |
|
|
| `POST` | `/sys/quotas/rate-limit/:name` |
|
|
|
|
### Parameters
|
|
|
|
- `name` `(string: "")` - The name of the quota.
|
|
- `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
|
|
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.
|
|
- `interval` `(string: "")` - The duration to enforce rate limiting for (default `"1s"`).
|
|
- `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.
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"path": "",
|
|
"rate": 897.3,
|
|
"interval": "2m",
|
|
"block_interval": "5m"
|
|
}
|
|
```
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request POST \
|
|
--header "X-Vault-Token: ..." \
|
|
--data @payload.json \
|
|
http://127.0.0.1:8200/v1/sys/quotas/rate-limit/global-rate-limiter
|
|
```
|
|
|
|
## Delete a Rate Limit Quota
|
|
|
|
A rate limit quota can be deleted by `name`.
|
|
|
|
| Method | Path |
|
|
| :------- | :----------------------------- |
|
|
| `DELETE` | `/sys/quotas/rate-limit/:name` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request DELETE \
|
|
--header "X-Vault-Token: ..." \
|
|
http://127.0.0.1:8200/v1/sys/quotas/rate-limit/global-rate-limiter
|
|
```
|
|
|
|
## Get a Rate Limit Quota
|
|
|
|
A rate limit quota can be retrieved by `name`.
|
|
|
|
| Method | Path |
|
|
| :----- | :----------------------------- |
|
|
| `GET` | `/sys/quotas/rate-limit/:name` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request GET \
|
|
--header "X-Vault-Token: ..." \
|
|
http://127.0.0.1:8200/v1/sys/quotas/rate-limit/global-rate-limiter
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"request_id": "d0870811-455d-3dfd-459f-aee016e6fb68",
|
|
"lease_id": "",
|
|
"lease_duration": 0,
|
|
"renewable": false,
|
|
"data": {
|
|
"block_interval": 300,
|
|
"interval": 2,
|
|
"name": "global-rate-limiter",
|
|
"path": "",
|
|
"rate": 897.3,
|
|
"type": "rate-limit"
|
|
},
|
|
"warnings": null
|
|
}
|
|
```
|
|
|
|
## List Rate Limit Quotas
|
|
|
|
This endpoint returns a list of all the rate limit quotas.
|
|
|
|
| Method | Path |
|
|
| :----- | :----------------------- |
|
|
| `LIST` | `/sys/quotas/rate-limit` |
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
--request LIST \
|
|
--header "X-Vault-Token: ..." \
|
|
http://127.0.0.1:8200/v1/sys/quotas/rate-limit
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"auth": null,
|
|
"data": {
|
|
"keys": ["global-rate-limiter", "kv-rate-limiter"]
|
|
},
|
|
"lease_duration": 0,
|
|
"lease_id": "",
|
|
"renewable": false,
|
|
"request_id": "ab633ee1-a692-ba03-083b-f1bd91c51c28",
|
|
"warnings": null,
|
|
"wrap_info": null
|
|
}
|
|
```
|