diff --git a/website/content/docs/api-clients/api.mdx b/website/content/docs/api-clients/api/index.mdx similarity index 53% rename from website/content/docs/api-clients/api.mdx rename to website/content/docs/api-clients/api/index.mdx index c5ef011074..c3ea4e2ad4 100644 --- a/website/content/docs/api-clients/api.mdx +++ b/website/content/docs/api-clients/api/index.mdx @@ -82,196 +82,12 @@ The following method conventions are used within Boundary's API: `DELETE` is used for deleting a specific resource, and is only used against a particular resource path. -## Rate limiting +## Manage system resources -If your controllers try to process every API request, it can lead to situations when the controllers are overwhelmed with requests. -The controllers may either run out of resources or overwhelm the database server and exhaust its resources. -API rate limiting lets you configure limits on the rate of API requests to help manage your resources and prevent them from being overwhelmed. +If your controllers try to process every API request, they may either run out of resources or overwhelm the database server. +Boundary features API rate limiting to help prevent system resources from being overwhlemed by too many simultaneous requests. +For more information, refer to [API rate limiting](/boundary/docs/api-clients/api/rate-limiting). -### Quotas - -Boundary creates quotas to track the number of requests in a given time period. -By default, Boundary tracks the number of requests by auth token, IP address, and the overall total. -Boundary reserves a portion of its memory for tracking quotas to ensure that it does not consume too much memory if there is a sudden burst of requests. - -If Boundary is unable to store a quota, it limits the request with a 503 HTTP status code. -You can configure the maximum number of quotas Boundary allows using the `api_rate_limit_max_quotas` variable. -There are also two metrics that allow you to monitor quota tracking: - -- `boundary_controller_api_ratelimiter_quota_storage_capacity` -- `boundary_controller_api_ratelimiter_quota_storage_usage` - -### Default limits - -API rate limiting is enforced on the controllers. -There are separate configurable limits for each combination of resource and action. -By default, the limits for `list` actions are: - -- 150 requests per 30 seconds per auth token -- 1,500 requests per 30 seconds per IP address -- 1,500 requests per 30 seconds in total - -The default limits for all other actions are: - -- 3,000 requests per 30 seconds per auth token -- 30,000 requests per 30 seconds per IP address -- 30,000 requests per 30 seconds in total - -You can override the default settings and configure other specific limitations using the `api_rate_limit` stanza in the controller configuration. - -### HTTP headers - -Clients that make requests to the controller API can inspect HTTP response headers to understand the configured limits and current usage. -Each response contains the following headers: - -- `RateLimit` - Provides the current limit, number of remaining requests, and the time at which the quota will reset for the limit that is closest to being exhausted for the requested resource and action. -- `RateLimit-Policy` - Describes the limits for the requested resource and action. - -If the request is limited, Boundary sends the client a 429 HTTP status code with a `Retry-After` header. -The `Retry-After` header contains the number of seconds the client should wait before it sends the request again. - -### More information - -Refer to the [controller stanza](/boundary/docs/configuration/controller#api_rate_limit) documentation for the specific `api_rate_limit` configuration options. -Some example configurations are listed below. - -### Rate limiting configuration examples - -The following example shows a simple configuration where the same limits are applied to all resources and examples: - -```hcl -controller { - # Total limit for all resources and actions - api_rate_limit { - resources = ["*"] - actions = ["*"] - per = "total" - limit = 500 - period = "1s" - } - - # Limit for all IP addresses to all resources and 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 for all authed requests to prevent one user - # from consuming all of the total limit - api_rate_limit { - resources = ["*"] - actions = ["*"] - per = "auth-token" - limit = 100 - period = "1s" - } -} -``` - -The following example shows a configuration that disables rate limiting. -You may want to disable rate limiting if you already use an external system like a reverse proxy to apply rate limiting: - -```hcl -controller { - api_rate_limit_disable = true -} -``` - -The following example uses the default settings for most endpoints, but configures a single override: - -```hcl -controller { - api_rate_limit { - resources = ["target"] - actions = ["list"] - per = "auth-token" - limit = 10 - period = "1s" - } -} -``` - -The following example is more complex. -Initially it sets some defaults to apply to all resources and actions. -Then it configures some specific endpoints with different limits. - -```hcl -controller { - # Total limit for all resources and actions - api_rate_limit { - resources = ["*"] - actions = ["*"] - per = "total" - limit = 500 - period = "1s" - } - - # Total limit for all list operations, - # sets an overall cap on the list action since it is relatively expensive - api_rate_limit { - resources = ["*"] - actions = ["list"] - per = "total" - limit = 200 - period = "1s" - } - - # Limit for IP address to all resources and actions - # to prevent a malicious host that is fabricating tokens - # or spamming unauthed endpoints - api_rate_limit { - resources = ["*"] - actions = ["*"] - per = "ip-address" - limit = 50 - period = "1s" - } - - # Limit of all authed requests, this essentially sets a default - # for all authed requests to prevent one user from consuming - # all of the total list limit set above. Any limits that follow - # can override the default for specific sets of resources and actions - api_rate_limit { - resources = ["*"] - actions = ["*"] - per = "auth-token" - limit = 100 - period = "1s" - } - - # Limit of all list operations by auth token to set a sane default - # since they are generally more expensive - api_rate_limit { - resources = ["*"] - actions = ["list"] - per = "auth-token" - limit = 50 - period = "1s" - } - - # Limit for targets and sessions list by auth token. These are resources - # that clients will want to list frequently, but might be more expensive - # if there is a large number of them for each user. Having a lower limit - # encourages the use of refresh tokens and caching. - api_rate_limit { - resources = ["target", "session"] - actions = ["list"] - per = "auth-token" - limit = 20 - period = "1s" - } - - #Limit for authorize session by auth token - api_rate_limit { - resources = ["target"] - actions = ["authorize-session"] - per = "auth-token" - limit = 150 - period = "1s" - } -} -``` \ No newline at end of file +When you search for Boundary resources using the `list` operation, you could potentially receive a very large number of results. +Boundary uses an API pagination feature to enable you to search and filter large lists of search results without overwhelming your system resources. +Refer to [API list pagination](/boundary/docs/api-clients/api/pagination) for more information about pagination and using the local cache for searches. \ No newline at end of file diff --git a/website/content/docs/api-clients/api/pagination.mdx b/website/content/docs/api-clients/api/pagination.mdx new file mode 100644 index 0000000000..1f21fd1ff7 --- /dev/null +++ b/website/content/docs/api-clients/api/pagination.mdx @@ -0,0 +1,103 @@ +--- +layout: docs +page_title: API list pagination +description: Learn how the API pagination and cache works in Boundary to prevent system resources from being overwhlemed and to help you find resources. +--- + +# API list pagination + +Boundary uses an API pagination feature to support searching and filtering large lists of results without overwhelming your system resources. + +## Introduction + +When you perform a `list` operation on a resource, the API request returns the first 1000 results, by default. +You can request the next page of results by repeating the `list` command and including a parameter with a token provided by Boundary. + +## Initial pagination + +When you run a `list` operation on a resource, the initial results are sorted in descending order by creation time and public ID (most recently created first). +Boundary returns the maximum number of responses along with the top-level fields `response_type` and `list_token`. +If the `response_type` is `delta`, it means there are more items available in the list. + +List tokens contain general metadata associated with the ongoing pagination. +To request the next page of results, run the `list` operation again and include the `list_token` that Boundary provided in the last response. +Boundary returns the next page of results with new `response_type` and `list_token` values. + +![API pagination workflow](/img/api-pagination/pagination-workflow.png) + +You can continue viewing new pages of results using the `list_token` values until the `response_type` reads `complete`. +If you compose an invalid token, you receive an invalid token error. + +## Request updated and deleted resources + +When the `response_type` reads `complete`, you have viewed all the results that were available when you ran the initial `list` operation. +You can now request any resources that were updated or deleted since you started paginating. + +To refresh the cached list results, make another `list` request using the `list_token` from the previous response. +Boundary returns a `response_type` and `list_token` as part of the response, similarly to when you ran the initial operation. +If the `response_type` is `delta`, it means there are more items available in the list. +You can use the `list_token` as a parameter to continue viewing new pages of results until the `response_type` reads `complete`. + +Boundary also includes the top-level response `removed_ids` as part of the refresh operation. +The `removed_ids` response contains the IDs of any resources that were deleted since you began paginating the results of the previous `list` operation. +Any resources that have been deleted are included on the first page of results. + +After 30 days, the `list_token` expires and you must make a new `list` request without the token to regenerate the full list of results. +If you make a `list` request using a token that has a `create_time` older than 30 days, Boundary treats it as an invalid token and returns an error. + +## Response structure + +All `list` endpoints support the following parameters: + +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not include a value, or if you include a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. + +Boundary returns the following response parameters: + +- `response_type` - Defines whether the response is a `delta` or `complete` listing. +The value is `delta` until the last page is returned, at which point it will be `complete`. +- `list_token` - An opaque token which is included in subsequent listing requests after the initial one, so that the client can continue to paginate the results. +- `sort_by` - The column name that the returned items should be sorted on. +This attribute is included in the response, so that the sort order for each endpoint is explicit. +- `sort_dir` - The direction in which the returned items are sorted. +Responses can include `desc` for descending, or `asc` for ascending. +- `items` - The list of items. +- `est_item_count` - An unsigned integer that indicates the total number of items that are available in the list of results. +This number may be an estimate, since the number of items may change during the pagination process. + +### Example response + +```json +{ + "response_type": "", + "list_token": "", + "sort_by": "created_time", + "sort_dir": "desc", + "est_item_count": 1000, + "items": [ + { + "id": "ttcp_1234567890", + "scope_id": "p_1234567890" + }, + { + "id": "ttcp_2234567890", + "scope_id": "p_1234567890" + } + ] +} +``` + +## Constraints and limitations + +In scenarios where updates are so frequent that the results may change while the refresh operation runs, those updates may not appear at all in the refreshed list. +If you make frequent updates to a resource, or if you are updating data while you run a `list` operation, HashiCorp recommends that you generate the full list of results instead of performing a refresh. + +Workers are not included in refresh operations because the updates they send to the controller are too frequent to be captured in a refresh. +To update a list of worker resources, you must regenerate the full list of results. + +When you refresh the list of results, you may notice duplicate items in the list. +This is a fundamental tradeoff when you search across multiple database transactions. \ No newline at end of file diff --git a/website/content/docs/api-clients/api/rate-limiting.mdx b/website/content/docs/api-clients/api/rate-limiting.mdx new file mode 100644 index 0000000000..fc2f25911e --- /dev/null +++ b/website/content/docs/api-clients/api/rate-limiting.mdx @@ -0,0 +1,199 @@ +--- +layout: docs +page_title: API rate limiting +description: Learn how API rate limiting lets you configure limits on the rates of API requests in Boundary to help manage resources and prevent them from being overwhelmed. +--- + +# Rate limiting + +If your controllers try to process every API request, it can lead to situations when the controllers are overwhelmed with requests. +The controllers may either run out of resources or overwhelm the database server and exhaust its resources. +API rate limiting lets you configure limits on the rate of API requests to help manage your resources and prevent them from being overwhelmed. + +## Quotas + +Boundary creates quotas to track the number of requests in a given time period. +By default, Boundary tracks the number of requests by auth token, IP address, and the overall total. +Boundary reserves a portion of its memory for tracking quotas to ensure that it does not consume too much memory if there is a sudden burst of requests. + +If Boundary is unable to store a quota, it limits the request with a 503 HTTP status code. +You can configure the maximum number of quotas Boundary allows using the `api_rate_limit_max_quotas` variable. +There are also two metrics that allow you to monitor quota tracking: + +- `boundary_controller_api_ratelimiter_quota_storage_capacity` +- `boundary_controller_api_ratelimiter_quota_storage_usage` + +## Default limits + +API rate limiting is enforced on the controllers. +There are separate configurable limits for each combination of resource and action. +By default, the limits for `list` actions are: + +- 150 requests per 30 seconds per auth token +- 1,500 requests per 30 seconds per IP address +- 1,500 requests per 30 seconds in total + +The default limits for all other actions are: + +- 3,000 requests per 30 seconds per auth token +- 30,000 requests per 30 seconds per IP address +- 30,000 requests per 30 seconds in total + +You can override the default settings and configure other specific limitations using the `api_rate_limit` stanza in the controller configuration. + +## HTTP headers + +Clients that make requests to the controller API can inspect HTTP response headers to understand the configured limits and current usage. +Each response contains the following headers: + +- `RateLimit` - Provides the current limit, number of remaining requests, and the time at which the quota will reset for the limit that is closest to being exhausted for the requested resource and action. +- `RateLimit-Policy` - Describes the limits for the requested resource and action. + +If the request is limited, Boundary sends the client a 429 HTTP status code with a `Retry-After` header. +The `Retry-After` header contains the number of seconds the client should wait before it sends the request again. + +## More information + +Refer to the [controller stanza](/boundary/docs/configuration/controller#api_rate_limit) documentation for the specific `api_rate_limit` configuration options. +Some example configurations are listed below. + +### Rate limiting configuration examples + +The following example shows a simple configuration where the same limits are applied to all resources and examples: + +```hcl +controller { + # Total limit for all resources and actions + api_rate_limit { + resources = ["*"] + actions = ["*"] + per = "total" + limit = 500 + period = "1s" + } + + # Limit for all IP addresses to all resources and 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 for all authed requests to prevent one user + # from consuming all of the total limit + api_rate_limit { + resources = ["*"] + actions = ["*"] + per = "auth-token" + limit = 100 + period = "1s" + } +} +``` + +The following example shows a configuration that disables rate limiting. +You may want to disable rate limiting if you already use an external system like a reverse proxy to apply rate limiting: + +```hcl +controller { + api_rate_limit_disable = true +} +``` + +The following example uses the default settings for most endpoints, but configures a single override: + +```hcl +controller { + api_rate_limit { + resources = ["target"] + actions = ["list"] + per = "auth-token" + limit = 10 + period = "1s" + } +} +``` + +The following example is more complex. +Initially it sets some defaults to apply to all resources and actions. +Then it configures some specific endpoints with different limits. + +```hcl +controller { + # Total limit for all resources and actions + api_rate_limit { + resources = ["*"] + actions = ["*"] + per = "total" + limit = 500 + period = "1s" + } + + # Total limit for all list operations, + # sets an overall cap on the list action since it is relatively expensive + api_rate_limit { + resources = ["*"] + actions = ["list"] + per = "total" + limit = 200 + period = "1s" + } + + # Limit for IP address to all resources and actions + # to prevent a malicious host that is fabricating tokens + # or spamming unauthed endpoints + api_rate_limit { + resources = ["*"] + actions = ["*"] + per = "ip-address" + limit = 50 + period = "1s" + } + + # Limit of all authed requests, this essentially sets a default + # for all authed requests to prevent one user from consuming + # all of the total list limit set above. Any limits that follow + # can override the default for specific sets of resources and actions + api_rate_limit { + resources = ["*"] + actions = ["*"] + per = "auth-token" + limit = 100 + period = "1s" + } + + # Limit of all list operations by auth token to set a sane default + # since they are generally more expensive + api_rate_limit { + resources = ["*"] + actions = ["list"] + per = "auth-token" + limit = 50 + period = "1s" + } + + # Limit for targets and sessions list by auth token. These are resources + # that clients will want to list frequently, but might be more expensive + # if there is a large number of them for each user. Having a lower limit + # encourages the use of refresh tokens and caching. + api_rate_limit { + resources = ["target", "session"] + actions = ["list"] + per = "auth-token" + limit = 20 + period = "1s" + } + + #Limit for authorize session by auth token + api_rate_limit { + resources = ["target"] + actions = ["authorize-session"] + per = "auth-token" + limit = 150 + period = "1s" + } +} +``` \ No newline at end of file diff --git a/website/content/docs/commands/accounts/list.mdx b/website/content/docs/commands/accounts/list.mdx index 216e1812bc..4ddfcdcc55 100644 --- a/website/content/docs/commands/accounts/list.mdx +++ b/website/content/docs/commands/accounts/list.mdx @@ -67,5 +67,11 @@ $ boundary accounts list [options] [args] - `-filter` `(string: "")` - If set, the list operation is filtered before being returned. The filter operates against each item in the list. We recommend using single quotes, because filters contain double quotes. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-methods/list.mdx b/website/content/docs/commands/auth-methods/list.mdx index 7e21efd69c..f97485914f 100644 --- a/website/content/docs/commands/auth-methods/list.mdx +++ b/website/content/docs/commands/auth-methods/list.mdx @@ -96,4 +96,10 @@ $ boundary auth-methods list [options] [args] scope is `global`. You can also specify a scope using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/auth-tokens/list.mdx b/website/content/docs/commands/auth-tokens/list.mdx index 16a84fe005..78da5a5d43 100644 --- a/website/content/docs/commands/auth-tokens/list.mdx +++ b/website/content/docs/commands/auth-tokens/list.mdx @@ -84,4 +84,11 @@ The default value is `false`. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. + @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credential-libraries/list.mdx b/website/content/docs/commands/credential-libraries/list.mdx index 7d1be8ceaf..394d00d7ef 100644 --- a/website/content/docs/commands/credential-libraries/list.mdx +++ b/website/content/docs/commands/credential-libraries/list.mdx @@ -58,5 +58,11 @@ You can also specify the credential store using the **BOUNDARY_CREDENTIAL_STORE_ The filter operates against each item in the list. We recommend that you use single quotes, because the filters contain double quotes. Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credential-stores/list.mdx b/website/content/docs/commands/credential-stores/list.mdx index 2437b63f76..b48889b82c 100644 --- a/website/content/docs/commands/credential-stores/list.mdx +++ b/website/content/docs/commands/credential-stores/list.mdx @@ -59,5 +59,11 @@ The default value is `false`. - `-scope-id ``(string: "")` - The scope in which to make the request. The default value is `global`. You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/credentials/list.mdx b/website/content/docs/commands/credentials/list.mdx index c39ba94a24..19558ac846 100644 --- a/website/content/docs/commands/credentials/list.mdx +++ b/website/content/docs/commands/credentials/list.mdx @@ -77,5 +77,11 @@ You can also specify the credential store using the **BOUNDARY_CREDENTIAL_STORE_ The filter operates against each item in the list. We recommend that you use single quotes, because the filters contain double quotes. Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/groups/list.mdx b/website/content/docs/commands/groups/list.mdx index d9bebb79b5..1993340720 100644 --- a/website/content/docs/commands/groups/list.mdx +++ b/website/content/docs/commands/groups/list.mdx @@ -89,5 +89,11 @@ The default value is `false`. - `-scope-id ``(string: "")` - The scope from which to list the groups. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-catalogs/list.mdx b/website/content/docs/commands/host-catalogs/list.mdx index effd23d489..34d7faf3c4 100644 --- a/website/content/docs/commands/host-catalogs/list.mdx +++ b/website/content/docs/commands/host-catalogs/list.mdx @@ -40,5 +40,11 @@ Refer to the [Filter resource listings documentation](/boundary/docs/concepts/fi - `-scope-id=` - The scope from which you want to list host catalogs. The default scope is `global`. You can also specify the scope using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/host-sets/list.mdx b/website/content/docs/commands/host-sets/list.mdx index 2bf1ccabd1..b93fe675bb 100644 --- a/website/content/docs/commands/host-sets/list.mdx +++ b/website/content/docs/commands/host-sets/list.mdx @@ -37,5 +37,11 @@ We recommend that you use single quotes, because the filters contain double quot Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. - `-host-catalog-id=` - The host catalog resource to use to produce the list. You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/hosts/list.mdx b/website/content/docs/commands/hosts/list.mdx index 730f5c4948..de6610a888 100644 --- a/website/content/docs/commands/hosts/list.mdx +++ b/website/content/docs/commands/hosts/list.mdx @@ -37,5 +37,11 @@ We recommend that you use single quotes, because the filters contain double quot Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. - `-host-catalog-id=` - The host catalog resource to use to produce the list. You can also specify the host catalog using the **BOUNDARY_HOST_CATALOG_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/managed-groups/list.mdx b/website/content/docs/commands/managed-groups/list.mdx index 6020d40a49..76dfe31be9 100644 --- a/website/content/docs/commands/managed-groups/list.mdx +++ b/website/content/docs/commands/managed-groups/list.mdx @@ -37,5 +37,11 @@ You can also specify the auth method using the **BOUNDARY_AUTH_METHOD_ID** envir The filter operates against each item in the list. We recommend that you use single quotes, because the filters contain double quotes. Refer to the [Filter resource listings documentation](/boundary/docs/concepts/filtering/resource-listing) for more details. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/roles/list.mdx b/website/content/docs/commands/roles/list.mdx index 3d73a1145e..c1e2174263 100644 --- a/website/content/docs/commands/roles/list.mdx +++ b/website/content/docs/commands/roles/list.mdx @@ -41,5 +41,11 @@ The default value is `false`. - `-scope-id=` - The enclosing scope from which you want to list the roles. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/scopes/list.mdx b/website/content/docs/commands/scopes/list.mdx index f0d4165ff7..18ee9799d2 100644 --- a/website/content/docs/commands/scopes/list.mdx +++ b/website/content/docs/commands/scopes/list.mdx @@ -41,5 +41,11 @@ The default value is `false`. - `-scope-id=` - The enclosing scope from which to list the scopes. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/session-recordings/list.mdx b/website/content/docs/commands/session-recordings/list.mdx index 3f286ef4a1..3772fac4cf 100644 --- a/website/content/docs/commands/session-recordings/list.mdx +++ b/website/content/docs/commands/session-recordings/list.mdx @@ -39,5 +39,11 @@ The default value is `false`. - `scope-id=` - The scope from which you want to list the session recordings. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/sessions/list.mdx b/website/content/docs/commands/sessions/list.mdx index 6b00bb2b89..b7973b69e5 100644 --- a/website/content/docs/commands/sessions/list.mdx +++ b/website/content/docs/commands/sessions/list.mdx @@ -43,5 +43,11 @@ The default value is `false`. - `scope-id=` - The scope from which to list sessions. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/storage-buckets/list.mdx b/website/content/docs/commands/storage-buckets/list.mdx index f1567fa2ab..15c8f4a190 100644 --- a/website/content/docs/commands/storage-buckets/list.mdx +++ b/website/content/docs/commands/storage-buckets/list.mdx @@ -43,5 +43,11 @@ The default value is `false`. - `scope-id=` - The scope from which to list storage buckets. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/targets/list.mdx b/website/content/docs/commands/targets/list.mdx index 42b99d0809..de6497ca48 100644 --- a/website/content/docs/commands/targets/list.mdx +++ b/website/content/docs/commands/targets/list.mdx @@ -41,5 +41,11 @@ The default value is `false`. - `scope-id=` - The scope from which to list the targets. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/content/docs/commands/users/list.mdx b/website/content/docs/commands/users/list.mdx index 0947dd63ef..0d29dae65e 100644 --- a/website/content/docs/commands/users/list.mdx +++ b/website/content/docs/commands/users/list.mdx @@ -40,5 +40,11 @@ The default value is `false`. - `-scope-id=` - The scope that contains the users you want to list. The default value is `global`. You can also specify this value using the **BOUNDARY_SCOPE_ID** environment variable. +- `list_token` (optional) - An opaque token that is returned from the previous `list` response. +If you do not supply a value, pagination starts from the beginning. +- `page_size` (optional) - An unsigned integer that indicates the number of items that should be included on the page of search results. +If you do not provide a value, or if you provide a value of `0`, Boundary uses the default page size of 1000 items. +If you configure it, the `page_size` value overrides the default page size. +Controller administrators can also configure a `max_page_size` option that constrains the maximum page size a user can request. @include 'cmd-option-note.mdx' \ No newline at end of file diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index caca7c672a..c9725a695e 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -1368,7 +1368,20 @@ }, { "title": "API", - "path": "api-clients/api" + "routes": [ + { + "title": "Overview", + "path": "api-clients/api" + }, + { + "title": "Rate limiting", + "path": "api-clients/api/rate-limiting" + }, + { + "title": "List pagination", + "path": "api-clients/api/pagination" + } + ] }, { "title": "Go SDK", diff --git a/website/public/img/api-pagination/pagination-workflow.png b/website/public/img/api-pagination/pagination-workflow.png new file mode 100644 index 0000000000..8ef4c932e8 Binary files /dev/null and b/website/public/img/api-pagination/pagination-workflow.png differ