速率限制配額服務 (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": []
}

domain

(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 伺服器表示 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 欄位中設定的策略來限制與儲存區匹配的請求速率。分配將成為儲存區的作用中分配。

使分配過期

在 assignment_time_to_live 欄位中定義的任務持續時間。當持續時間結束時，任務會 過期，並且不再是 啟用 狀態。資料平面應停止對 bucket 套用速率限制策略，並將 bucket 轉換為「任務過期」狀態。這會啟動在 expired_assignment_behavior 欄位中設定的行為。

替換任務

如果速率限制策略與 bucket 的 啟用 任務不同，或目前 bucket 任務為 過期 狀態，則資料平面必須立即結束目前任務，回報 bucket 使用情況，並套用新的任務。新的任務會變成 bucket 的 啟用 任務。
如果速率限制策略與 bucket 的 啟用 (非 過期) 任務相同，則資料平面應將 啟用 任務的持續時間延長為 assignment_time_to_live 欄位中提供的新任務的持續時間。啟用 任務被視為未變更。

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

assignment_time_to_live

(Duration) 任務被視為 過期 的持續時間。關於過期的流程請參閱上方的說明。

如果未設定，則任務沒有到期日。
如果設定為 0，則任務會立即過期，強制用戶端進入「任務過期」狀態。在伺服器重新啟動之前，RLQS 伺服器可以在需要用戶端主動回退到預先設定的 ExpiredAssignmentBehavior 時使用此功能。

注意

請注意，使任務過期與放棄任務並不相同。雖然使任務過期只會將 bucket 轉換為「任務過期」狀態，但放棄任務會完全從資料平面記憶體中清除 bucket，並停止使用情況回報。

rate_limit_strategy: (type.v3.RateLimitStrategy) 設定與 bucket 匹配的請求的本機速率限制器。如果未設定，則允許所有請求。

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

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

bucket 的放棄動作。表示 RLQS 伺服器將不再傳送給定 bucket_id 的更新。

如果在一段時間後沒有回報 bucket 的請求，則伺服器會將 bucket 視為非活動狀態。伺服器會停止追蹤 bucket，並透過此訊息指示資料平面放棄 bucket。

放棄任務

資料平面會從記憶體中刪除 bucket（包括其使用情況資料）。它應停止追蹤 bucket，並停止回報其使用情況。這實際上會將資料平面重設為將第一個請求匹配到 bucket 之前的狀態。

重新啟動訂閱

如果將新請求匹配到先前放棄的 bucket，則資料平面必須表現得像是從未追蹤過該 bucket，並且是第一個與其匹配的請求

訂閱和回報的流程會從頭開始。
bucket 會轉換為「無任務」狀態。
一旦收到新的任務，就會根據 QuotaAssignmentAction 的「將第一個任務套用至 bucket」部分套用該任務。

service.rate_limit_quota.v3.BucketId

[service.rate_limit_quota.v3.BucketId proto]

bucket 的識別碼。用於在控制平面 (RLQS 伺服器) 和資料平面 (RLQS 用戶端) 之間匹配 bucket，例如：

資料平面會將符合 BucketId bucket 的請求的使用情況回報給控制平面
控制平面會將具有 BucketId 的 bucket 的任務傳送到資料平面 Bucket ID。

範例

bucket:
  name: my_bucket
  env: staging

注意

BucketId 鍵的順序無關緊要。bucket { a: 'A', b: 'B' } 和 { b: 'B', a: 'A' } 是相同的。

{
  "bucket": {...}
}

bucket: (repeated map<string, string>)