速率限制配额服务 (RLQS) (proto)

警告

此 API 功能目前正在开发中。标记为正在开发中的 API 功能不被视为稳定，不受威胁模型涵盖，不受安全团队支持，并且可能会发生重大变更。在了解上述所有事项之前，请勿使用此功能。

速率限制配额服务 (RLQS) 是一种 Envoy 全局速率限制服务，允许将速率限制决策委派给远程服务。该服务将聚合来自多个数据平面实例的用量报告，并根据其业务逻辑将速率限制分配分配给每个实例。该逻辑超出了协议 API 的范围。

该协议被设计为一个流优先 API。它利用类似观察的订阅模型。数据平面根据过滤器配置将请求分组到配额桶中，并定期将它们连同桶标识符 BucketId 一起报告给 RLQS 服务器。一旦 RLQS 服务器收集到足够的报告以做出决定，它将发送包含速率限制指令的分配。

数据平面发送的第一个报告被 RLQS 服务器解释为“观察”请求，表明数据平面实例有兴趣接收 BucketId 的进一步更新。从那时起，RLQS 服务器可以随意将分配推送到此实例，即使该实例未发送用量报告。RLQS 服务器有责任确定数据平面实例何时没有发送 BucketId 报告过长时间，并使用 AbandonAction 响应，表明服务器现在已停止发送 BucketId 桶的配额分配，数据平面实例应该放弃它。

如果由于任何原因，RLQS 客户端没有收到已报告桶的初始分配，为了防止内存耗尽，数据平面将限制保留该桶的时间。等待初始分配的确切时间由过滤器选择，并且可能会根据实现而有所不同。一旦持续时间结束，数据平面将停止报告桶用量，拒绝任何排队的请求，并将桶从内存中清除。随后匹配到该桶的请求将重新初始化该桶处于“无分配”状态，重新启动报告。

有关更多详细信息，请参阅速率限制配额配置概述。

service.rate_limit_quota.v3.RateLimitQuotaUsageReports

[service.rate_limit_quota.v3.RateLimitQuotaUsageReports proto]

{
  "domain": ...,
  "bucket_quota_usages": []
}

域名

(string, 必需) 所有配额请求都必须指定域名。这使得能够在不同的应用程序之间共享配额服务器，而不必担心重叠。例如，“envoy”。

仅应在第一个报告中提供，同一个流上的所有后续消息都被认为是在同一个域名中。如果需要更改域名，请关闭流，并使用不同的域名重新打开一个新的流。

bucket_quota_usages: (重复 service.rate_limit_quota.v3.RateLimitQuotaUsageReports.BucketQuotaUsage, 必需) 配额用量报告列表。RLQS 服务器按客户端提供的相同顺序处理该列表。

service.rate_limit_quota.v3.RateLimitQuotaUsageReports.BucketQuotaUsage

[service.rate_limit_quota.v3.RateLimitQuotaUsageReports.BucketQuotaUsage proto]

桶的用量报告。

注意

请注意，发送给 BucketId 的第一个报告表示 RLQS 客户端正在订阅该 BucketId 的未来分配。

{
  "bucket_id": {...},
  "time_elapsed": {...},
  "num_requests_allowed": ...,
  "num_requests_denied": ...
}

bucket_id: (service.rate_limit_quota.v3.BucketId, 必需) 报告请求配额用量的 BucketId。

time_elapsed: (Duration, 必需) 自上次报告以来的经过时间。

num_requests_allowed: (uint64) 数据平面允许通过的请求。

num_requests_denied: (uint64) 被限制的请求。

service.rate_limit_quota.v3.RateLimitQuotaResponse

[service.rate_limit_quota.v3.RateLimitQuotaResponse proto]

{
  "bucket_action": []
}

bucket_action: (重复 service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction, 必需) 要应用于桶的已排序操作列表。这些操作按给定的顺序应用，从上到下。

service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction

[service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction proto]

命令数据平面对具有 bucket_id 的桶执行其中一项操作。

{
  "bucket_id": {...},
  "quota_assignment_action": {...},
  "abandon_action": {...}
}

bucket_id: (service.rate_limit_quota.v3.BucketId, 必需) 应用操作的 BucketId。

quota_assignment_action

(service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction) 将配额分配应用于桶。

命令数据平面对桶应用速率限制策略。在 QuotaAssignmentAction 消息中详细描述了应用和到期速率限制策略的过程。

必须设置 quota_assignment_action、abandon_action 之一。

abandon_action

(service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction) 放弃桶。

命令数据平面放弃桶。在 AbandonAction 消息中描述了放弃桶的过程。

必须设置 quota_assignment_action、abandon_action 之一。

service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction

[service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.QuotaAssignmentAction proto]

桶的配额分配。配置给定 bucket_id 的速率限制策略和持续时间。

将第一个分配应用于桶

一旦数据平面收到 QuotaAssignmentAction，它必须发送桶的当前用量报告，并开始使用 rate_limit_strategy 字段中配置的策略限制匹配到桶的请求。分配成为桶的 active 分配。

分配到期

分配的持续时间定义在 assignment_time_to_live 字段中。当持续时间运行完毕时，分配被视为 expired，并且不再处于 active 状态。数据平面应停止对桶应用速率限制策略，并将桶转换为“已过期分配”状态。这将激活在 expired_assignment_behavior 字段中配置的行为。

替换分配

如果速率限制策略与桶的 active 分配不同，或者当前桶分配为 expired，数据平面必须立即结束当前分配，报告桶用量，并应用新分配。新分配成为桶的 active 分配。
如果速率限制策略与桶的 active（不是 expired）分配相同，数据平面应将 active 分配的持续时间延长到 assignment_time_to_live 字段中提供的新的分配持续时间。active 分配被视为未更改。

{
  "assignment_time_to_live": {...},
  "rate_limit_strategy": {...}
}

assignment_time_to_live

(Duration) 分配被视为 expired 后的持续时间。到期的过程在上面描述过。

如果未设置，则分配没有过期日期。
如果设置为 0，则分配立即过期，强制客户端进入 “过期分配” 状态。RLQS 服务器在需要客户端主动回退到预配置的 ExpiredAssignmentBehavior 时可以使用此方法，例如服务器即将重启之前。

注意

请注意，过期分配与放弃分配不同。过期分配只是将桶过渡到“过期分配”状态；而放弃分配会完全从数据平面内存中删除桶，并停止使用报告。

rate_limit_strategy: (type.v3.RateLimitStrategy) 配置与桶匹配的请求的本地速率限制器。如果未设置，则允许所有请求。

service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction

[service.rate_limit_quota.v3.RateLimitQuotaResponse.BucketAction.AbandonAction proto]

桶的放弃操作。表示 RLQS 服务器将不再发送给定 bucket_id 的更新。

如果一段时间内未报告任何桶的请求，则服务器会认为该桶处于非活动状态。服务器停止跟踪桶，并通过此消息指示数据平面放弃该桶。

放弃分配

数据平面应从内存中删除桶（包括其使用数据）。它应该停止跟踪桶，并停止报告其使用情况。这实际上将数据平面重置到匹配第一个请求到桶之前的状态。

重新启动订阅

如果新的请求与之前被放弃的桶匹配，则数据平面必须表现得好像它从未跟踪过该桶，并且这是第一个与该桶匹配的请求。

订阅和报告过程从头开始。
桶过渡到 “无分配” 状态。
收到新分配后，将根据 QuotaAssignmentAction 的“将第一个分配应用于桶”部分应用新分配。

service.rate_limit_quota.v3.BucketId

[service.rate_limit_quota.v3.BucketId proto]

桶的标识符。用于在控制平面（RLQS 服务器）和数据平面（RLQS 客户端）之间匹配桶，例如

数据平面发送与使用 BucketId 匹配的请求的使用情况报告到控制平面
控制平面向数据平面发送具有 BucketId 的桶分配。桶 ID。

示例

bucket:
  name: my_bucket
  env: staging

注意

BucketId 键的顺序无关紧要。桶 { a: 'A', b: 'B' } 和 { b: 'B', a: 'A' } 是相同的。

{
  "bucket": {...}
}

bucket: (repeated map<string, string>)