流量控制 (Flow control)
API 优先级和公平性控制 Kubernetes API 服务器在过载情况下的行为。您可以在API 优先级和公平性文档中找到更多相关信息。
诊断 (Diagnostics)
启用了优先级和公平性功能的 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}"
来获取 UID 到 FlowSchemas 和 PriorityLevelConfigurations 名称的映射。
调试端点 (Debug endpoints)
启用 `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`：给定队列中所有等待请求的总工作量之和，单位为座位秒。
注意：`座位秒`（缩写为 `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`：请求执行最后阶段花费的额外时间。FinalSeats 将在此期间被占用。它并不意味着用户将观察到的任何延迟。
- `StartTime`：请求开始执行的时间。对于排队的请求，它将为 0001-01-01T00:00:00Z。
调试日志记录 (Debug logging)
在 `-v=3` 或更高详细程度下，API 服务器会在 API 服务器日志中为每个请求输出一行 httplog，其中包括以下属性。
- `apf_fs`：请求被分类到的流模式的名称。
- `apf_pl`：该流模式的优先级名称。
- `apf_iseats`：为请求执行的初始（正常）阶段确定的座位数。
- `apf_fseats`：为请求执行的最后阶段（考虑关联的 `watch` 通知）确定的座位数。
- `apf_additionalLatency`：请求执行最后阶段的持续时间。
在更高的详细程度下，将会有日志行公开 APF 如何处理请求的详细信息，主要用于调试目的。
响应标头 (Response headers)
APF 将以下两个标头添加到每个 HTTP 响应消息中。它们不会出现在审计日志中。可以从客户端查看它们。对于使用 `klog` 的客户端，使用详细程度 `-v=8` 或更高来查看这些标头。
- `X-Kubernetes-PF-FlowSchema-UID` 包含相应请求被分类到的 FlowSchema 对象的 UID。
- `X-Kubernetes-PF-PriorityLevel-UID` 包含与该 FlowSchema 关联的 PriorityLevelConfiguration 对象的 UID。
后续步骤 (What's next)
有关 API 优先级和公平性设计细节的背景信息，请参阅增强提案。