[zh] resync page flow-control

Author: zhenghao.zhu

content/zh-cn/docs/concepts/cluster-administration/flow-control.md

@@ -81,8 +81,8 @@ APF 适用于 **watch** 请求。当 APF 被禁用时，**watch** 请求不受 `
 
 <!--
 The API Priority and Fairness feature is controlled by a feature gate
-and is enabled by default.  See 
-[Feature Gates](/docs/reference/command-line-tools-reference/feature-gates/)
+and is enabled by default.  See [Feature
+Gates](/docs/reference/command-line-tools-reference/feature-gates/)
 for a general explanation of feature gates and how to enable and
 disable them.  The name of the feature gate for APF is
 "APIPriorityAndFairness".  This feature also involves an {{<
@@ -187,30 +187,29 @@ objects mentioned below.
 ### Seats Occupied by a Request
 
 The above description of concurrency management is the baseline story.
-In it, requests have different durations but are counted equally at
-any given moment when comparing against a priority level's concurrency
-limit. In the baseline story, each request occupies one unit of
-concurrency. The word "seat" is used to mean one unit of concurrency,
-inspired by the way each passenger on a train or aircraft takes up one
-of the fixed supply of seats.
+Requests have different durations but are counted equally at any given
+moment when comparing against a priority level's concurrency limit. In
+the baseline story, each request occupies one unit of concurrency. The
+word "seat" is used to mean one unit of concurrency, inspired by the
+way each passenger on a train or aircraft takes up one of the fixed
+supply of seats.
 
 But some requests take up more than one seat.  Some of these are **list**
 requests that the server estimates will return a large number of
 objects.  These have been found to put an exceptionally heavy burden
-on the server, among requests that take a similar amount of time to
-run.  For this reason, the server estimates the number of objects that
-will be returned and considers the request to take a number of seats
+on the server.  For this reason, the server estimates the number of objects
+that will be returned and considers the request to take a number of seats
 that is proportional to that estimated number.
 -->
 ### 请求占用的席位  {#seats-occupied-by-a-request}
 
-上述并发管理的描述是基线情况。其中，各个请求具有不同的持续时间，
+上述并发管理的描述是基线情况。各个请求具有不同的持续时间，
 但在与一个优先级的并发限制进行比较时，这些请求在任何给定时刻都以同等方式进行计数。
 在这个基线场景中，每个请求占用一个并发单位。
 我们用 “席位（Seat）” 一词来表示一个并发单位，其灵感来自火车或飞机上每位乘客占用一个固定座位的供应方式。
 
 但有些请求所占用的席位不止一个。有些请求是服务器预估将返回大量对象的 **list** 请求。
-和所需运行时间相近的其他请求相比，我们发现这类请求会给服务器带来异常沉重的负担。
+我们发现这类请求会给服务器带来异常沉重的负担。
 出于这个原因，服务器估算将返回的对象数量，并认为请求所占用的席位数与估算得到的数量成正比。
 
 <!--
@@ -506,16 +505,15 @@ https://play.golang.org/p/Gi0PLgVHiUg , which computes this table.
 ### FlowSchema
 
 A FlowSchema matches some inbound requests and assigns them to a
-priority level. Every inbound request is tested against every
-FlowSchema in turn, starting with those with numerically lowest ---
-which we take to be the logically highest --- `matchingPrecedence` and
-working onward.  The first match wins.
+priority level. Every inbound request is tested against FlowSchemas,
+starting with those with the numerically lowest `matchingPrecedence` and
+working upward. The first match wins.
 -->
 ### FlowSchema
 
 FlowSchema 匹配一些入站请求，并将它们分配给优先级。
-每个入站请求都会对所有 FlowSchema 测试是否匹配，
-首先从 `matchingPrecedence` 数值最低的匹配开始（我们认为这是逻辑上的最高优先级），
+每个入站请求都会对 FlowSchema 测试是否匹配，
+首先从 `matchingPrecedence` 数值最低的匹配开始，
 然后依次进行，直到首个匹配出现。
 
 {{< caution >}}
@@ -537,7 +535,7 @@ ensure that no two FlowSchemas have the same `matchingPrecedence`.
 A FlowSchema matches a given request if at least one of its `rules`
 matches. A rule matches if at least one of its `subjects` *and* at least
 one of its `resourceRules` or `nonResourceRules` (depending on whether the
-incoming request is for a resource or non-resource URL) matches the request.
+incoming request is for a resource or non-resource URL) match the request.
 -->
 当给定的请求与某个 FlowSchema 的 `rules` 的其中一条匹配，那么就认为该请求与该 FlowSchema 匹配。
 判断规则与该请求是否匹配，**不仅**要求该条规则的 `subjects` 字段至少存在一个与该请求相匹配，
@@ -556,19 +554,18 @@ effectively removing it from consideration.
 
 <!--
 A FlowSchema's `distinguisherMethod.type` determines how requests matching that
-schema will be separated into flows. It may be
-either `ByUser`, in which case one requesting user will not be able to starve
-other users of capacity, or `ByNamespace`, in which case requests for resources
-in one namespace will not be able to starve requests for resources in other
-namespaces of capacity, or it may be blank (or `distinguisherMethod` may be
-omitted entirely), in which case all requests matched by this FlowSchema will be
+schema will be separated into flows. It may be `ByUser`, in which one requesting
+user will not be able to starve other users of capacity; `ByNamespace`, in which
+requests for resources in one namespace will not be able to starve requests for
+resources in other namespaces of capacity; or blank (or `distinguisherMethod` may be
+omitted entirely), in which all requests matched by this FlowSchema will be
 considered part of a single flow. The correct choice for a given FlowSchema
 depends on the resource and your particular environment.
 -->
 FlowSchema 的 `distinguisherMethod.type` 字段决定了如何把与该模式匹配的请求分散到各个流中。
 可能是 `ByUser`，在这种情况下，一个请求用户将无法饿死其他容量的用户；
 或者是 `ByNamespace`，在这种情况下，一个名字空间中的资源请求将无法饿死其它名字空间的资源请求；
-或者它可以为空（或者可以完全省略 `distinguisherMethod`），
+或者为空（或者可以完全省略 `distinguisherMethod`），
 在这种情况下，与此 FlowSchema 匹配的请求将被视为单个流的一部分。
 资源和你的特定环境决定了如何选择正确一个 FlowSchema。
 
@@ -763,7 +760,7 @@ for an annotation with key `apf.kubernetes.io/autoupdate-spec`.  If
 there is such an annotation and its value is `true` then the
 kube-apiservers control the object.  If there is such an annotation
 and its value is `false` then the users control the object.  If
-neither of those condtions holds then the `metadata.generation` of the
+neither of those conditions holds then the `metadata.generation` of the
 object is consulted.  If that is 1 then the kube-apiservers control
 the object.  Otherwise the users control the object.  These rules were
 introduced in release 1.22 and their consideration of
@@ -902,26 +899,26 @@ poorly-behaved workloads that may be harming system health.
   broken down by the labels `flow_schema` (indicating the one that
   matched the request), `priority_level` (indicating the one to which
   the request was assigned), and `reason`.  The `reason` label will be
-  have one of the following values:
+  one of the following values:
 -->
 * `apiserver_flowcontrol_rejected_requests_total` 是一个计数器向量，
   记录被拒绝的请求数量（自服务器启动以来累计值），
   由标签 `flow_chema`（表示与请求匹配的 FlowSchema）、`priority_level`
   （表示分配给请该求的优先级）和 `reason` 来区分。
-  `reason` 标签将具有以下值之一：
+  `reason` 标签将是以下值之一：
 
   <!--
   * `queue-full`, indicating that too many requests were already
-    queued,
+    queued.
   * `concurrency-limit`, indicating that the
     PriorityLevelConfiguration is configured to reject rather than
-    queue excess requests, or
+    queue excess requests.
   * `time-out`, indicating that the request was still in the queue
     when its queuing time limit expired.
   * `cancelled`, indicating that the request is not purge locked
-     and has been ejected from the queue.
+    and has been ejected from the queue.
   -->
-  * `queue-full`，表明已经有太多请求排队，
+  * `queue-full`，表明已经有太多请求排队
   * `concurrency-limit`，表示将 PriorityLevelConfiguration 配置为
     `Reject` 而不是 `Queue`，或者
   * `time-out`，表示在其排队时间超期的请求仍在队列中。
@@ -930,14 +927,12 @@ poorly-behaved workloads that may be harming system health.
 <!--
 * `apiserver_flowcontrol_dispatched_requests_total` is a counter
   vector (cumulative since server start) of requests that began
-  executing, broken down by the labels `flow_schema` (indicating the
-  one that matched the request) and `priority_level` (indicating the
-  one to which the request was assigned).
+  executing, broken down by `flow_schema` and `priority_level`.
 -->
 * `apiserver_flowcontrol_dispatched_requests_total` 是一个计数器向量，
   记录开始执行的请求数量（自服务器启动以来的累积值），
-  由标签 `flow_schema`（表示与请求匹配的 FlowSchema）和
-  `priority_level`（表示分配给该请求的优先级）来区分。
+  由 `flow_schema` 和 `priority_level` 来区分。
+
 
 <!--
 * `apiserver_current_inqueue_requests` is a gauge vector of recent
@@ -962,10 +957,10 @@ poorly-behaved workloads that may be harming system health.
   nanosecond, of the number of requests broken down by the labels
   `phase` (which takes on the values `waiting` and `executing`) and
   `request_kind` (which takes on the values `mutating` and
-  `readOnly`).  Each observed value is a ratio, between 0 and 1, of a
-  number of requests divided by the corresponding limit on the number
-  of requests (queue volume limit for waiting and concurrency limit
-  for executing).
+  `readOnly`).  Each observed value is a ratio, between 0 and 1, of
+  the number of requests divided by the corresponding limit on the
+  number of requests (queue volume limit for waiting and concurrency
+  limit for executing).
 -->
 * `apiserver_flowcontrol_read_vs_write_current_requests` 是一个直方图向量，
   在每个纳秒结束时记录请求数量的观察值，由标签 `phase`（取值为 `waiting` 及 `executing`）
@@ -976,29 +971,28 @@ poorly-behaved workloads that may be harming system health.
 <!--
 * `apiserver_flowcontrol_current_inqueue_requests` is a gauge vector
   holding the instantaneous number of queued (not executing) requests,
-  broken down by the labels `priority_level` and `flow_schema`.
+  broken down by `priority_level` and `flow_schema`.
 -->
 * `apiserver_flowcontrol_current_inqueue_requests` 是一个表向量，
   记录包含排队中的（未执行）请求的瞬时数量，
-  由标签 `priority_level` 和 `flow_schema` 区分。
+  由 `priority_level` 和 `flow_schema` 区分。
 
 <!--
 * `apiserver_flowcontrol_current_executing_requests` is a gauge vector
   holding the instantaneous number of executing (not waiting in a
-  queue) requests, broken down by the labels `priority_level` and
-  `flow_schema`.
+  queue) requests, broken down by `priority_level` and `flow_schema`.
 -->
 * `apiserver_flowcontrol_current_executing_requests` 是一个表向量，
   记录包含执行中（不在队列中等待）请求的瞬时数量，
-  由标签 `priority_level` 和 `flow_schema` 进一步区分。
+  由 `priority_level` 和 `flow_schema` 进一步区分。
 
 <!-- 
 * `apiserver_flowcontrol_request_concurrency_in_use` is a gauge vector
   holding the instantaneous number of occupied seats, broken down by
-  the labels `priority_level` and `flow_schema`.
+  `priority_level` and `flow_schema`.
 -->
 * `apiserver_flowcontrol_request_concurrency_in_use` 是一个规范向量，
-  包含占用座位的瞬时数量，由标签 `priority_level` 和 `flow_schema` 进一步区分。
+  包含占用座位的瞬时数量，由 `priority_level` 和 `flow_schema` 进一步区分。
 
 <!--
 * `apiserver_flowcontrol_priority_level_request_utilization` is a
@@ -1040,14 +1034,13 @@ poorly-behaved workloads that may be harming system health.
 <!--
 * `apiserver_flowcontrol_request_queue_length_after_enqueue` is a
   histogram vector of queue lengths for the queues, broken down by
-  the labels `priority_level` and `flow_schema`, as sampled by the
-  enqueued requests.  Each request that gets queued contributes one
-  sample to its histogram, reporting the length of the queue immediately
-  after the request was added.  Note that this produces different
-  statistics than an unbiased survey would.
+  `priority_level` and `flow_schema`, as sampled by the enqueued requests.
+  Each request that gets queued contributes one sample to its histogram,
+  reporting the length of the queue immediately after the request was added.
+  Note that this produces different statistics than an unbiased survey would.
 -->
 * `apiserver_flowcontrol_request_queue_length_after_enqueue` 是一个直方图向量，
-  记录请求队列的长度，由标签 `priority_level` 和 `flow_schema` 进一步区分。
+  记录请求队列的长度，由 `priority_level` 和 `flow_schema` 进一步区分。
   每个排队中的请求都会为其直方图贡献一个样本，并在添加请求后立即上报队列的长度。
   请注意，这样产生的统计数据与无偏调查不同。
 
@@ -1137,6 +1130,14 @@ poorly-behaved workloads that may be harming system health.
 * `apiserver_flowcontrol_demand_seats_stdev` 是一个表向量，
   为每个优先级包含了上一个并发度借用调整期间所观察到的席位需求的时间加权总标准偏差。
 
+<!--
+* `apiserver_flowcontrol_demand_seats_smoothed` is a gauge vector
+  holding, for each priority level, the smoothed enveloped seat demand
+  determined at the last concurrency adjustment.
+-->
+* `apiserver_flowcontrol_demand_seats_smoothed` 是一个表向量，
+  为每个优先级包含了上一个并发度调整期间确定的平滑包络席位需求。
+
 <!--
 * `apiserver_flowcontrol_target_seats` is a gauge vector holding, for
   each priority level, the concurrency target going into the borrowing
@@ -1163,16 +1164,13 @@ poorly-behaved workloads that may be harming system health.
 <!--
 * `apiserver_flowcontrol_request_wait_duration_seconds` is a histogram
   vector of how long requests spent queued, broken down by the labels
-  `flow_schema` (indicating which one matched the request),
-  `priority_level` (indicating the one to which the request was
-  assigned), and `execute` (indicating whether the request started
-  executing).
+  `flow_schema`, `priority_level`, and `execute`. The `execute` label
+  indicates whether the request has started executing.
 -->
 * `apiserver_flowcontrol_request_wait_duration_seconds` 是一个直方图向量，
   记录请求排队的时间，
-  由标签 `flow_schema`（表示与请求匹配的 FlowSchema），
-  `priority_level`（表示分配该请求的优先级）
-  和 `execute`（表示请求是否开始执行）进一步区分。
+  由标签 `flow_schema`、`priority_level` 和 `execute` 进一步区分。
+  标签 `execute` 表示请求是否开始执行。
 
   {{< note >}}
   <!--
@@ -1188,14 +1186,11 @@ poorly-behaved workloads that may be harming system health.
 <!--
 * `apiserver_flowcontrol_request_execution_seconds` is a histogram
   vector of how long requests took to actually execute, broken down by
-  the labels `flow_schema` (indicating which one matched the request)
-  and `priority_level` (indicating the one to which the request was
-  assigned).
+  `flow_schema` and `priority_level`.
 -->
 * `apiserver_flowcontrol_request_execution_seconds` 是一个直方图向量，
   记录请求实际执行需要花费的时间，
-  由标签 `flow_schema`（表示与请求匹配的 FlowSchema）和
-  `priority_level`（表示分配给该请求的优先级）进一步区分。
+  由标签 `flow_schema` 和 `priority_level` 进一步区分。
 
 <!--
 * `apiserver_flowcontrol_watch_count_samples` is a histogram vector of
@@ -1218,23 +1213,20 @@ poorly-behaved workloads that may be harming system health.
 
 <!--
 * `apiserver_flowcontrol_request_dispatch_no_accommodation_total` is a
-  counter vec of the number of events that in principle could have led
+  counter vector of the number of events that in principle could have led
   to a request being dispatched but did not, due to lack of available
-  concurrency, broken down by `flow_schema` and `priority_level`.  The
-  relevant sorts of events are arrival of a request and completion of
-  a request.
+  concurrency, broken down by `flow_schema` and `priority_level`.
 -->
 * `apiserver_flowcontrol_request_dispatch_no_accommodation_total`
   是一个事件数量的计数器，这些事件在原则上可能导致请求被分派，
   但由于并发度不足而没有被分派，
   由标签 `flow_schema` 和 `priority_level` 进一步区分。
-  相关的事件类型是请求的到达和请求的完成。
 
 <!--
 ### Debug endpoints
 
 When you enable the API Priority and Fairness feature, the `kube-apiserver`
-serves the following additional paths at its HTTP[S] ports.
+serves the following additional paths at its HTTP(S) ports.
 -->
 ### 调试端点    {#debug-endpoints}
 
@@ -1371,7 +1363,7 @@ request, and it includes the following attributes.
 
 <!--
 At higher levels of verbosity there will be log lines exposing details
-of how APF handled the request, primarily for debug purposes.
+of how APF handled the request, primarily for debugging purposes.
 -->
 在更高级别的精细度下，将有日志行揭示 APF 如何处理请求的详细信息，主要用于调试目的。
 
@@ -1404,4 +1396,3 @@ or the feature's [slack channel](https://kubernetes.slack.com/messages/api-prior
 请参阅[增强提案](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1040-priority-and-fairness)。
 你可以通过 [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery/)
 或特性的 [Slack 频道](https://kubernetes.slack.com/messages/api-priority-and-fairness/)提出建议和特性请求。
-