流量控制

API 优先级和公平性控制着 Kubernetes API 服务器在过载情况下的行为。您可以在 API 优先级和公平性文档中找到更多信息。

诊断

启用优先级和公平性功能的 API 服务器的每个 HTTP 响应都有两个额外的标头：X-Kubernetes-PF-FlowSchema-UID 和 X-Kubernetes-PF-PriorityLevel-UID，分别记录匹配请求的流模式和分配给它的优先级级别。这些标头不包含 API 对象的名称（为了避免在请求用户没有查看权限的情况下泄露详细信息）。在调试时，您可以使用如下命令

kubectl get flowschemas -o custom-columns="uid:{metadata.uid},name:{metadata.name}"
kubectl get prioritylevelconfigurations -o custom-columns="uid:{metadata.uid},name:{metadata.name}"

来获取 FlowSchema 和 PriorityLevelConfiguration 的 UID 到名称的映射。

调试端点

启用 APIPriorityAndFairness 功能后，kube-apiserver 在其 HTTP(S) 端口上提供以下其他路径。

您需要确保您具有访问这些端点的权限。如果您使用管理员权限，则无需执行任何操作。如果需要，可以按照 RBAC 文档授予权限，通过指定 nonResourceURLs 来访问 /debug/api_priority_and_fairness/。

/debug/api_priority_and_fairness/dump_priority_levels - 列出所有优先级级别及其当前状态。您可以使用如下方式获取：

kubectl get --raw /debug/api_priority_and_fairness/dump_priority_levels

输出将是 CSV 格式，类似于以下内容：

PriorityLevelName, ActiveQueues, IsIdle, IsQuiescing, WaitingRequests, ExecutingRequests, DispatchedRequests, RejectedRequests, TimedoutRequests, CancelledRequests
catch-all,         0,            true,   false,       0,               0,                 1,                  0,                0,                0
exempt,            0,            true,   false,       0,               0,                 0,                  0,                0,                0
global-default,    0,            true,   false,       0,               0,                 46,                 0,                0,                0
leader-election,   0,            true,   false,       0,               0,                 4,                  0,                0,                0
node-high,         0,            true,   false,       0,               0,                 34,                 0,                0,                0
system,            0,            true,   false,       0,               0,                 48,                 0,                0,                0
workload-high,     0,            true,   false,       0,               0,                 500,                0,                0,                0
workload-low,      0,            true,   false,       0,               0,                 0,                  0,                0,                0

所选列名的说明

IsQuiescing 指示当其队列已清空时，此优先级级别将被删除。

/debug/api_priority_and_fairness/dump_queues - 列出所有队列及其当前状态。您可以使用如下方式获取：

kubectl get --raw /debug/api_priority_and_fairness/dump_queues

输出将是 CSV 格式，类似于以下内容：

PriorityLevelName, Index,  PendingRequests, ExecutingRequests, SeatsInUse, NextDispatchR,   InitialSeatsSum, MaxSeatsSum, TotalWorkSum
workload-low,      14,     27,              0,                 0,          77.64342019ss,   270,             270,         0.81000000ss
workload-low,      74,     26,              0,                 0,          76.95387841ss,   260,             260,         0.78000000ss
...
leader-election,   0,      0,               0,                 0,          5088.87053833ss, 0,               0,           0.00000000ss
leader-election,   1,      0,               0,                 0,          0.00000000ss,    0,               0,           0.00000000ss
...
workload-high,     0,      0,               0,                 0,          0.00000000ss,    0,               0,           0.00000000ss
workload-high,     1,      0,               0,                 0,          1119.44936475ss, 0,               0,           0.00000000ss

所选列名的说明

NextDispatchR：下一个请求将在哪个 R 进度计量读数（以座位秒为单位）被调度。
InitialSeatsSum：给定队列中所有请求关联的 InitialSeats 总和。
MaxSeatsSum：给定队列中所有请求关联的 MaxSeats 总和。
TotalWorkSum：给定队列中所有等待请求的总工作量（以座位秒为单位）。

注意：seat-second（缩写为 ss）是 APF 世界中工作的一种度量单位，以座位秒为单位。

/debug/api_priority_and_fairness/dump_requests - 列出所有请求，包括等待在队列中的请求和正在执行的请求。您可以使用如下方式获取：

kubectl get --raw /debug/api_priority_and_fairness/dump_requests

输出将是 CSV 格式，类似于以下内容：

PriorityLevelName, FlowSchemaName,   QueueIndex, RequestIndexInQueue, FlowDistingsher,                        ArriveTime,                     InitialSeats, FinalSeats, AdditionalLatency, StartTime
exempt,            exempt,           -1,         -1,                  ,                                       2023-07-15T04:51:25.596404345Z, 1,            0,          0s,                2023-07-15T04:51:25.596404345Z
workload-low,      service-accounts, 14,         0,                   system:serviceaccount:default:loadtest, 2023-07-18T00:12:51.386556253Z, 10,           0,          0s,                0001-01-01T00:00:00Z
workload-low,      service-accounts, 14,         1,                   system:serviceaccount:default:loadtest, 2023-07-18T00:12:51.487092539Z, 10,           0,          0s,                0001-01-01T00:00:00Z

您可以使用如下命令获取更详细的列表：

kubectl get --raw '/debug/api_priority_and_fairness/dump_requests?includeRequestDetails=1'

输出将是 CSV 格式，类似于以下内容：

PriorityLevelName, FlowSchemaName,   QueueIndex, RequestIndexInQueue, FlowDistingsher,                        ArriveTime,                     InitialSeats, FinalSeats, AdditionalLatency, StartTime,                      UserName,                               Verb,   APIPath,                                   Namespace,   Name,   APIVersion, Resource,   SubResource
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,
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,
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,

所选列名的说明

QueueIndex：队列的索引。对于没有队列的优先级级别，它将为 -1。
RequestIndexInQueue：给定请求在队列中的索引。对于正在执行的请求，它将为 -1。
InitialSeats：请求执行的初始（正常）阶段将占用多少座位。
FinalSeats：请求执行的最终阶段将占用多少座位，包括关联的 WATCH 通知。
AdditionalLatency：请求执行的最终阶段所花费的额外时间。最终座位将在该时间段内占用。这并不意味着用户会观察到的任何延迟。
StartTime：请求开始执行的时间。对于排队的请求，它将为 0001-01-01T00:00:00Z。

调试日志

在 -v=3 或更高的详细程度下，API 服务器会在 API 服务器日志中为每个 API 服务器请求输出一个 httplog 行，其中包含以下属性。

apf_fs：请求被分类到的流模式的名称。
apf_pl：该流模式的优先级级别名称。
apf_iseats：请求执行的初始（正常）阶段确定的座位数。
apf_fseats：请求执行的最终阶段确定的座位数（包括关联的 watch 通知）。
apf_additionalLatency：请求执行的最终阶段的持续时间。

在更高的详细程度下，会有日志行显示 APF 处理请求的详细信息，主要用于调试目的。

响应标头

APF 将以下两个标头添加到每个 HTTP 响应消息。它们不会出现在审计日志中。可以从客户端查看。对于使用 klog 的客户端，请使用详细程度 -v=8 或更高版本来查看这些标头。

X-Kubernetes-PF-FlowSchema-UID 包含相应请求被分类到的 FlowSchema 对象的 UID。
X-Kubernetes-PF-PriorityLevel-UID 包含与该 FlowSchema 关联的 PriorityLevelConfiguration 对象的 UID。

接下来

有关 API 优先级和公平性的设计细节的背景信息，请参阅增强提案。

上次修改时间为 2023 年 9 月 14 日下午 6:34 PST：解决评论 (0469dc9b32)

流量控制

诊断

调试端点

调试日志

响应标头

接下来

反馈