docs: Document API rate limiting (#4111)

* docs: Document API rate limiting

* docs: Fix default setting

* addss rate limiting examples to complete configuration example

* use # for comments for consistency

* Update website/content/docs/api-clients/api.mdx

Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>

* Apply batch suggestions from code review

Co-authored-by: Michael Li <michael.li@hashicorp.com>

* docs: Updates from review feedback

* docs: Updates from review feedback

* docs: Add new defaults and sub-headings

* Update website/content/docs/api-clients/go-sdk.mdx

Co-authored-by: Timothy Messier <tim.messier@gmail.com>

* docs: Remove remaining comments from code blocks

* docs: Update code blocks

* fixes tabs

* Update website/content/docs/api-clients/api.mdx

Co-authored-by: Michael Li <michael.li@hashicorp.com>

---------

Co-authored-by: stellarsquall <stellarsquall@protonmail.ch>
Co-authored-by: Robin Beck <stellarsquall@users.noreply.github.com>
Co-authored-by: Michael Li <michael.li@hashicorp.com>
Co-authored-by: Timothy Messier <tim.messier@gmail.com>
This commit is contained in:
authored and GitHub committed 2023-12-11 09:52:36 -05:00
1 parent d4f2f02072
commit 3cfc20e6f6
4 files changed
+271 -1

No files matched your search

@@ -108,6 +108,37 @@ description will be read.
are anything specified by Go's [ParseDuration()](https://golang.org/pkg/time/#ParseDuration) method. Only
used when an `ops` listener is set and the Controller is present. Default is 0 seconds.
- `api_rate_limit` - Sets limits on the rate of requests for controller API endpoints.
This setting can help prevent resources from being overwhelmed with too many requests at a time.
The `api_rate_limit` configuration stanza contains the following fields:
- `resources` - Specifies the Boundary resource you want to limit rates for.
The resource can be `target` or `credential-library`, for example.
You can include all resources by using the wildcard `"*"`.
- `actions` - Specifies the actions you want to limit on the resource.
The actions could be `create`, `list`, or `authorize-session`, for example.
You can include all actions by using the wildcard `"*"`.
- `per` - Specifies how the limit is allocated.
You can choose from the following values:
- `total` - Counts all requests, regardless of auth token or IP address.
- `ip-address` - Counts requests per IP address.
This value lets you limit requests per IP address.
- `auth-token` - Counts requests per the user's auth token.
This value lets you limit requests per auth token.
You can also use the wildcard `"*"` to include all values, but only when `unlimited` is also configured.
- `limit` - Specifies the number of requests that are allowed within the `period`.
- `period` - Specifies the time window for the `limit`.
The limit resets after this period of time has passed.
- `unlimited` - Indicates that the corresponding resources and actions should not be rate limited.
If you set this value to `true`, you should not specify values for the `limit` and `period` or you will receive an error.
For more information about how API rate limiting works, refer to the [API rate limiting](/boundary/docs/api-clients/api#rate-limiting) documentation.
- `api_rate_limit_disable` - Disables API rate limiting, if set to `true`.
If `api_rate_limit_disable` is set to `true`, and you have provided any `api_rate_limit` stanzas, you will receive an error.
- `api_rate_limit_max_quotas` - Specifies the maximum number of API rate limiting quotas that Boundary allows.
## Signals
The `SIGHUP` signal causes a controller to reload its configuration file to pick up any updates to the `database url` value. Any other updated values are ignored.
@@ -189,6 +220,35 @@ controller {
database {
url = "postgresql://boundary:boundarydemo@postgres.yourdomain.com:5432/boundary"
}
# Rate limiting examples to conserve controller resources
# total limit for all resources and actions
api_rate_limit {
resources = ["*"]
actions = ["*"]
per = "total"
limit = 500
period = "1s"
}
# Limit for ip addresses to all resources+actions to prevent a malicious
# host that is fabricating tokens, or spamming unauthed endpoints
api_rate_limit {
resources = ["*"]
actions = ["*"]
per = "ip-address"
limit = 100
period = "1s"
}
# Limit of all authed requests, to prevent one user consuming all of the total limit
api_rate_limit {
resources = ["*"]
actions = ["*"]
per = "auth-token"
limit = 100
period = "1s"
}
}
# API listener configuration block