Skip to content

Commit 0388631

Browse files
windsonseawindsonsea
committed
[zh] Sync /reference/debug-cluster/
1 parent b1bc2f5 commit 0388631

File tree

2 files changed

+303
-0
lines changed

2 files changed

+303
-0
lines changed

‎content/zh-cn/docs/reference/debug-cluster/_index.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: 调试集群
3+
weight: 120
4+
no_list: false
5+
---
6+
<!--
7+
title: Debug cluster
8+
weight: 120
9+
no_list: false
10+
-->

‎content/zh-cn/docs/reference/debug-cluster/flow-control.md

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
---
2+
title: 流控
3+
weight: 130
4+
---
5+
<!--
6+
title: Flow control
7+
weight: 130
8+
-->
9+
10+
<!-- overview -->
11+
12+
<!--
13+
API Priority and Fairness controls the behavior of the Kubernetes API server in
14+
an overload situation. You can find more information about it in the
15+
[API Priority and Fairness](/docs/concepts/cluster-administration/flow-control/)
16+
documentation.
17+
-->
18+
API 优先级和公平性控制着 Kubernetes API 服务器在负载过高的情况下的行为。你可以在
19+
[API 优先级和公平性](/zh-cn/docs/concepts/cluster-administration/flow-control/)文档中找到更多信息。
20+
21+
<!-- body -->
22+
23+
<!--
24+
## Diagnostics
25+
26+
Every HTTP response from an API server with the priority and fairness feature
27+
enabled has two extra headers: `X-Kubernetes-PF-FlowSchema-UID` and
28+
`X-Kubernetes-PF-PriorityLevel-UID`, noting the flow schema that matched the request
29+
and the priority level to which it was assigned, respectively. The API objects'
30+
names are not included in these headers (to avoid revealing details in case the
31+
requesting user does not have permission to view them). When debugging, you
32+
can use a command such as:
33+
-->
34+
## 问题诊断 {#diagnostics}
35+
36+
对于启用了 APF 的 API 服务器，每个 HTTP 响应都有两个额外的 HTTP 头：
37+
`X-Kubernetes-PF-FlowSchema-UID` 和 `X-Kubernetes-PF-PriorityLevel-UID`，
38+
给出与请求匹配的 FlowSchema 和已分配的优先级级别。
39+
如果请求用户没有查看这些对象的权限，则这些 HTTP 头中将不包含 API 对象的名称，
40+
因此在调试时，你可以使用类似如下的命令：
41+
42+
```shell
43+
kubectl get flowschemas -o custom-columns="uid:{metadata.uid},name:{metadata.name}"
44+
kubectl get prioritylevelconfigurations -o custom-columns="uid:{metadata.uid},name:{metadata.name}"
45+
```
46+
47+
<!--
48+
to get a mapping of UIDs to names for both FlowSchemas and
49+
PriorityLevelConfigurations.
50+
-->
51+
来获取 UID 与 FlowSchema 的名称和 PriorityLevelConfiguration 的名称之间的对应关系。
52+
53+
<!--
54+
## Debug endpoints
55+
56+
With the `APIPriorityAndFairness` feature enabled, the `kube-apiserver`
57+
serves the following additional paths at its HTTP(S) ports.
58+
-->
59+
### 调试端点 {#debug-endpoints}
60+
61+
启用 APF 特性后，`kube-apiserver` 会在其 HTTP/HTTPS 端口额外提供以下路径：
62+
63+
<!--
64+
You need to ensure you have permissions to access these endpoints.
65+
You don't have to do anything if you are using admin.
66+
Permissions can be granted if needed following the [RBAC](/docs/reference/access-authn-authz/rbac/) doc
67+
to access `/debug/api_priority_and_fairness/` by specifying `nonResourceURLs`.
68+
-->
69+
你需要确保自己具有访问这些端点的权限。如果你使用管理员身份，则无需进行任何操作。
70+
必要时可以通过设置 `nonResourceURLs` 来访问 `/debug/api_priority_and_fairness/`
71+
参照 [RBAC](/zh-cn/docs/reference/access-authn-authz/rbac/) 文档授予权限。
72+
73+
<!--
74+
- `/debug/api_priority_and_fairness/dump_priority_levels` - a listing of
75+
all the priority levels and the current state of each. You can fetch like this:
76+
-->
77+
- `/debug/api_priority_and_fairness/dump_priority_levels` ——
78+
所有优先级及其当前状态的列表。你可以这样获取：
79+
80+
```shell
81+
kubectl get --raw /debug/api_priority_and_fairness/dump_priority_levels
82+
```
83+
84+
<!--
85+
The output will be in CSV and similar to this:
86+
-->
87+
输出格式为 CSV，类似于：
88+
89+
```none
90+
PriorityLevelName, ActiveQueues, IsIdle, IsQuiescing, WaitingRequests, ExecutingRequests, DispatchedRequests, RejectedRequests, TimedoutRequests, CancelledRequests
91+
catch-all, 0, true, false, 0, 0, 1, 0, 0, 0
92+
exempt, 0, true, false, 0, 0, 0, 0, 0, 0
93+
global-default, 0, true, false, 0, 0, 46, 0, 0, 0
94+
leader-election, 0, true, false, 0, 0, 4, 0, 0, 0
95+
node-high, 0, true, false, 0, 0, 34, 0, 0, 0
96+
system, 0, true, false, 0, 0, 48, 0, 0, 0
97+
workload-high, 0, true, false, 0, 0, 500, 0, 0, 0
98+
workload-low, 0, true, false, 0, 0, 0, 0, 0, 0
99+
```
100+
101+
<!--
102+
Explanation for selected column names:
103+
- `IsQuiescing` indicates if this priority level will be removed when its queues have been drained.
104+
-->
105+
所选列名的解释：
106+
107+
- `IsQuiescing` 表示当队列已被腾空时此优先级级别是否将被移除。
108+
109+
<!--
110+
- `/debug/api_priority_and_fairness/dump_queues` - a listing of all the
111+
queues and their current state. You can fetch like this:
112+
-->
113+
- `/debug/api_priority_and_fairness/dump_queues` —— 所有队列及其当前状态的列表。
114+
你可以这样获取：
115+
116+
```shell
117+
kubectl get --raw /debug/api_priority_and_fairness/dump_queues
118+
```
119+
120+
<!--
121+
The output will be in CSV and similar to this:
122+
-->
123+
输出格式为 CSV，类似于：
124+
125+
```none
126+
PriorityLevelName, Index, PendingRequests, ExecutingRequests, SeatsInUse, NextDispatchR, InitialSeatsSum, MaxSeatsSum, TotalWorkSum
127+
workload-low, 14, 27, 0, 0, 77.64342019ss, 270, 270, 0.81000000ss
128+
workload-low, 74, 26, 0, 0, 76.95387841ss, 260, 260, 0.78000000ss
129+
...
130+
leader-election, 0, 0, 0, 0, 5088.87053833ss, 0, 0, 0.00000000ss
131+
leader-election, 1, 0, 0, 0, 0.00000000ss, 0, 0, 0.00000000ss
132+
...
133+
workload-high, 0, 0, 0, 0, 0.00000000ss, 0, 0, 0.00000000ss
134+
workload-high, 1, 0, 0, 0, 1119.44936475ss, 0, 0, 0.00000000ss
135+
```
136+
137+
<!--
138+
Explanation for selected column names:
139+
- `NextDispatchR`: The R progress meter reading, in units of seat-seconds, at
140+
which the next request will be dispatched.
141+
- `InitialSeatsSum`: The sum of InitialSeats associated with all requests in
142+
a given queue.
143+
- `MaxSeatsSum`: The sum of MaxSeats associated with all requests in a given
144+
queue.
145+
- `TotalWorkSum`: The sum of total work, in units of seat-seconds, of all
146+
waiting requests in a given queue.
147+
-->
148+
所选列名的解释：
149+
150+
- `NextDispatchR`：下一个请求将被调度时的 R 进度计读数，单位为 seat-second。
151+
- `InitialSeatsSum`：与在某个给定队列中所有请求关联的 InitialSeats 的总和。
152+
- `MaxSeatsSum`：与某个给定队列中所有请求关联的 MaxSeats 的总和。
153+
- `TotalWorkSum`：在某个给定队列中所有等待中请求的总工作量，单位为 seat-second。
154+
155+
<!--
156+
Note: `seat-second` (abbreviate as `ss`) is a measure of work, in units of
157+
seat-seconds, in the APF world.
158+
-->
159+
注意：`seat-second`（缩写为 `ss`）是 APF 领域中的工作量单位。
160+
161+
<!--
162+
- `/debug/api_priority_and_fairness/dump_requests` - a listing of all the requests
163+
including requests waiting in a queue and requests being executing.
164+
You can fetch like this:
165+
-->
166+
- `/debug/api_priority_and_fairness/dump_requests` - 所有请求的列表，
167+
包括队列中正在等待的请求和正在执行的请求。你可以运行以下类似命令获取此列表：
168+
169+
```shell
170+
kubectl get --raw /debug/api_priority_and_fairness/dump_requests
171+
```
172+
173+
<!--
174+
The output will be in CSV and similar to this:
175+
-->
176+
输出格式为 CSV，类似于：
177+
178+
```none
179+
PriorityLevelName, FlowSchemaName, QueueIndex, RequestIndexInQueue, FlowDistingsher, ArriveTime, InitialSeats, FinalSeats, AdditionalLatency, StartTime
180+
exempt, exempt, -1, -1, , 2023-07-15T04:51:25.596404345Z, 1, 0, 0s, 2023-07-15T04:51:25.596404345Z
181+
workload-low, service-accounts, 14, 0, system:serviceaccount:default:loadtest, 2023-07-18T00:12:51.386556253Z, 10, 0, 0s, 0001-01-01T00:00:00Z
182+
workload-low, service-accounts, 14, 1, system:serviceaccount:default:loadtest, 2023-07-18T00:12:51.487092539Z, 10, 0, 0s, 0001-01-01T00:00:00Z
183+
```
184+
185+
<!--
186+
You can get a more detailed listing with a command like this:
187+
-->
188+
你可以使用以下命令获得更详细的清单：
189+
190+
```shell
191+
kubectl get --raw '/debug/api_priority_and_fairness/dump_requests?includeRequestDetails=1'
192+
```
193+
194+
<!--
195+
The output will be in CSV and similar to this:
196+
-->
197+
输出格式为 CSV，类似于：
198+
199+
```none
200+
PriorityLevelName, FlowSchemaName, QueueIndex, RequestIndexInQueue, FlowDistingsher, ArriveTime, InitialSeats, FinalSeats, AdditionalLatency, StartTime, UserName, Verb, APIPath, Namespace, Name, APIVersion, Resource, SubResource
201+
exempt, exempt, -1, -1, , 2023-07-15T04:51:25.596404345Z, 1, 0, 0s, 2023-07-15T04:51:25.596404345Z, system:serviceaccount:system:admin, list, /api/v1/namespaces/kube-stress/configmaps, kube-stress, , v1, configmaps,
202+
workload-low, service-accounts, 14, 0, system:serviceaccount:default:loadtest, 2023-07-18T00:13:08.986534842Z, 10, 0, 0s, 0001-01-01T00:00:00Z, system:serviceaccount:default:loadtest, list, /api/v1/namespaces/kube-stress/configmaps, kube-stress, , v1, configmaps,
203+
workload-low, service-accounts, 14, 1, system:serviceaccount:default:loadtest, 2023-07-18T00:13:09.086476021Z, 10, 0, 0s, 0001-01-01T00:00:00Z, system:serviceaccount:default:loadtest, list, /api/v1/namespaces/kube-stress/configmaps, kube-stress, , v1, configmaps,
204+
```
205+
206+
<!--
207+
Explanation for selected column names:
208+
- `QueueIndex`: The index of the queue. It will be -1 for priority levels
209+
without queues.
210+
- `RequestIndexInQueue`: The index in the queue for a given request. It will
211+
be -1 for executing requests.
212+
- `InitialSeats`: The number of seats will be occupied during the initial
213+
(normal) stage of execution of the request.
214+
- `FinalSeats`: The number of seats will be occupied during the final stage
215+
of request execution, accounting for the associated WATCH notifications.
216+
- `AdditionalLatency`: The extra time taken during the final stage of request
217+
execution. FinalSeats will be occupied during this time period. It does not
218+
mean any latency that a user will observe.
219+
- `StartTime`: The time a request starts to execute. It will be
220+
0001-01-01T00:00:00Z for queued requests.
221+
-->
222+
所选列名的解释：
223+
- `QueueIndex`：队列的索引。对于没有队列的优先级级别，该值将为 -1。
224+
- `RequestIndexInQueue`：某个给定请求在队列中的索引。对于正在执行的请求，该值将为 -1。
225+
- `InitialSeats`：在请求的初始（正常）执行阶段占用的席位数。
226+
- `FinalSeats`：在请求执行的最终阶段占用的席位数，包括与之关联的 WATCH 通知。
227+
- `AdditionalLatency`：在请求执行的最终阶段所耗用的额外时间。
228+
FinalSeats 将在此时间段内被占用。这并不意味着用户会感知到任何延迟。
229+
- `StartTime`：请求开始执行的时间。对于排队的请求，该值将为 0001-01-01T00:00:00Z。
230+
231+
<!--
232+
## Debug logging
233+
234+
At `-v=3` or more verbosity, the API server outputs an httplog line for every
235+
request in the API server log, and it includes the following attributes.
236+
-->
237+
### 调试日志生成行为 {#debug-logging}
238+
239+
在 `-v=3` 或更详细的情况下，API 服务器会为在 API 服务日志中为每个请求输出一行 httplog，
240+
其中包括以下属性：
241+
242+
<!--
243+
- `apf_fs`: the name of the flow schema to which the request was classified.
244+
- `apf_pl`: the name of the priority level for that flow schema.
245+
- `apf_iseats`: the number of seats determined for the initial
246+
(normal) stage of execution of the request.
247+
- `apf_fseats`: the number of seats determined for the final stage of
248+
execution (accounting for the associated `watch` notifications) of the
249+
request.
250+
- `apf_additionalLatency`: the duration of the final stage of
251+
execution of the request.
252+
-->
253+
- `apf_fs`：请求被分类到的 FlowSchema 的名称。
254+
- `apf_pl`：该 FlowSchema 的优先级名称。
255+
- `apf_iseats`：为请求执行的初始（正常）阶段确定的席位数量。
256+
- `apf_fseats`：为请求的最后执行阶段（考虑关联的 `watch` 通知）确定的席位数量。
257+
- `apf_additionalLatency`：请求执行最后阶段的持续时间。
258+
259+
<!--
260+
At higher levels of verbosity there will be log lines exposing details
261+
of how APF handled the request, primarily for debugging purposes.
262+
-->
263+
在更高级别的精细度下，将有日志行揭示 APF 如何处理请求的详细信息，主要用于调试目的。
264+
265+
<!--
266+
## Response headers
267+
268+
APF adds the following two headers to each HTTP response message.
269+
They won't appear in the audit log. They can be viewed from the client side.
270+
For client using `klog`, use verbosity `-v=8` or higher to view these headers.
271+
272+
- `X-Kubernetes-PF-FlowSchema-UID` holds the UID of the FlowSchema
273+
object to which the corresponding request was classified.
274+
- `X-Kubernetes-PF-PriorityLevel-UID` holds the UID of the
275+
PriorityLevelConfiguration object associated with that FlowSchema.
276+
-->
277+
### 响应头 {#response-headers}
278+
279+
APF 将以下两个头添加到每个 HTTP 响应消息中。
280+
这些信息不会出现在审计日志中，但可以从客户端查看。
281+
对于使用 `klog` 的客户端，使用 `-v=8` 或更高的详细级别可以查看这些头。
282+
283+
- `X-Kubernetes-PF-FlowSchema-UID` 保存相应请求被分类到的 FlowSchema 对象的 UID。
284+
- `X-Kubernetes-PF-PriorityLevel-UID` 保存与该 FlowSchema 关联的 PriorityLevelConfiguration 对象的 UID。
285+
286+
## {{% heading "whatsnext" %}}
287+
288+
<!--
289+
For background information on design details for API priority and fairness, see
290+
the [enhancement proposal](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1040-priority-and-fairness).
291+
-->
292+
有关 API 优先级和公平性的设计细节的背景信息，
293+
请参阅[增强提案](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1040-priority-and-fairness)。

0 commit comments

Comments
 (0)