move to reference doc and address comments

mengqiy · mengqiy · commit ae7ae36b7c8e · 2023-09-14T00:18:42.000Z
diff --git a/content/en/docs/concepts/cluster-administration/flow-control.md b/content/en/docs/concepts/cluster-administration/flow-control.md
@@ -661,110 +661,6 @@ poorly-behaved workloads that may be harming system health.
   to a request being dispatched but did not, due to lack of available
   concurrency, broken down by `flow_schema` and `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.
-
-- `/debug/api_priority_and_fairness/dump_priority_levels` - a listing of
-  all the priority levels and the current state of each.  You can fetch like this:
-
-  ```shell
-  kubectl get --raw /debug/api_priority_and_fairness/dump_priority_levels
-  ```
-
-  The output is similar to this:
-
-  ```none
-  PriorityLevelName, ActiveQueues, IsIdle, IsQuiescing, WaitingRequests, ExecutingRequests, DispatchedRequests, RejectedRequests, TimedoutRequests, CancelledRequests
-  catch-all,         0,            true,   false,       0,               0,                 1,                  0,                0,                0
-  exempt,            <none>,       <none>, <none>,      <none>,          <none>,            <none>,             <none>,           <none>,           <none>
-  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
-  ```
-
-- `/debug/api_priority_and_fairness/dump_queues` - a listing of all the
-  queues and their current state.  You can fetch like this:
-
-  ```shell
-  kubectl get --raw /debug/api_priority_and_fairness/dump_queues
-  ```
-
-  The output is similar to this:
-
-  ```none
-  PriorityLevelName, Index,  PendingRequests, ExecutingRequests, VirtualStart,
-  workload-high,     0,      0,               0,                 0.0000,
-  workload-high,     1,      0,               0,                 0.0000,
-  workload-high,     2,      0,               0,                 0.0000,
-  ...
-  leader-election,   14,     0,               0,                 0.0000,
-  leader-election,   15,     0,               0,                 0.0000,
-  ```
-
-- `/debug/api_priority_and_fairness/dump_requests` - a listing of all the requests
-  that are currently waiting in a queue.  You can fetch like this:
-
-  ```shell
-  kubectl get --raw /debug/api_priority_and_fairness/dump_requests
-  ```
-
-  The output is similar to this:
-
-  ```none
-  PriorityLevelName, FlowSchemaName, QueueIndex, RequestIndexInQueue, FlowDistingsher,       ArriveTime,
-  exempt,            <none>,         <none>,     <none>,              <none>,                <none>,
-  system,            system-nodes,   12,         0,                   system:node:127.0.0.1, 2020-07-23T15:26:57.179170694Z,
-  ```
-  
-  In addition to the queued requests, the output includes one phantom line
-  for each priority level that is exempt from limitation.
-
-  You can get a more detailed listing with a command like this:
-
-  ```shell
-  kubectl get --raw '/debug/api_priority_and_fairness/dump_requests?includeRequestDetails=1'
-  ```
-
-  The output is similar to this:
-
-  ```none
-  PriorityLevelName, FlowSchemaName, QueueIndex, RequestIndexInQueue, FlowDistingsher,       ArriveTime,                     UserName,              Verb,   APIPath,                                                     Namespace, Name,   APIVersion, Resource, SubResource,
-  system,            system-nodes,   12,         0,                   system:node:127.0.0.1, 2020-07-23T15:31:03.583823404Z, system:node:127.0.0.1, create, /api/v1/namespaces/scaletest/configmaps,
-  system,            system-nodes,   12,         1,                   system:node:127.0.0.1, 2020-07-23T15:31:03.594555947Z, system:node:127.0.0.1, create, /api/v1/namespaces/scaletest/configmaps,
-  ```
-
-### Debug logging
-
-At `-v=3` or more verbose the server outputs an httplog line for every
-request, and it includes the following attributes.
-
-- `apf_fs`: the name of the flow schema to which the request was classified.
-- `apf_pl`: the name of the priority level for that flow schema.
-- `apf_iseats`: the number of seats determined for the initial
-  (normal) stage of execution of the request.
-- `apf_fseats`: the number of seats determined for the final stage of
-  execution (accounting for the associated WATCH notifications) of the
-  request.
-- `apf_additionalLatency`: the duration of the final stage of
-  execution of the request.
-
-At higher levels of verbosity there will be log lines exposing details
-of how APF handled the request, primarily for debugging purposes.
-
-### Response headers
-
-APF adds the following two headers to each HTTP response message.
-
-- `X-Kubernetes-PF-FlowSchema-UID` holds the UID of the FlowSchema
-  object to which the corresponding request was classified.
-- `X-Kubernetes-PF-PriorityLevel-UID` holds the UID of the
-  PriorityLevelConfiguration object associated with that FlowSchema.
-
 ## Good practices for using API Priority and Fairness
 
 When a given priority level exceeds its permitted concurrency, requests can
@@ -881,7 +777,7 @@ Example FlowSchema object to isolate list event requests:
 
 ## {{% heading "whatsnext" %}}
 
-You can visit flow control [troubleshooting page](/docs/tasks/debug/flow-control.md) to learn how to debug.
+You can visit flow control [reference doc](/docs/reference/flow-control/) to learn more about troubleshooting.
 For background information on design details for API priority and fairness, see
 the [enhancement proposal](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1040-priority-and-fairness).
 You can make suggestions and feature requests via [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery)
diff --git a/content/en/docs/reference/flow-control/_index.md b/content/en/docs/reference/flow-control/_index.md
@@ -1,29 +1,27 @@
 ---
-title: Troubleshooting APIServer flow control issues
-content_type: task
+title: Flow control
+weight: 120
+no_list: true
 ---
 
 <!-- overview -->
 
 API Priority and Fairness controls the behavior of the Kubernetes API server in
 an overload situation. You can find more information about it in the
-[concept doc](/docs/concepts/cluster-administration/flow-control.md)
+[API Priority and Fairness](/docs/concepts/cluster-administration/flow-control/)
+documentation.
 
-## {{% heading "prerequisites" %}}
-
-* Kubernetes cluster is installed
-* `kubectl` is configured to communicate with the cluster
-
-<!-- steps -->
+<!-- body -->
 
 ## Diagnostics
 
 Every HTTP response from an API server with the priority and fairness feature
 enabled has two extra headers: `X-Kubernetes-PF-FlowSchema-UID` and
 `X-Kubernetes-PF-PriorityLevel-UID`, noting the flow schema that matched the request
 and the priority level to which it was assigned, respectively. The API objects'
-names are not included in these headers in case the requesting user does not
-have permission to view them, so when debugging you can use a command like
+names are not included in these headers (to avoid revealing details in case the
+requesting user does not have permission to view them). When debugging, you
+can use a command such as:
 
 ```shell
 kubectl get flowschemas -o custom-columns="uid:{metadata.uid},name:{metadata.name}"
@@ -38,14 +36,19 @@ PriorityLevelConfigurations.
 When you enable the API Priority and Fairness feature, the `kube-apiserver`
 serves the following additional paths at its HTTP(S) ports.
 
+You need to ensure you have permissions to access these endpoints.
+You don't have to do anything if you are using admin.
+Permissions can be granted if needed following [this doc](https://kubernetes.io/docs/reference/access-authn-authz/rbac/)
+to access `/debug/api_priority_and_fairness/` by specifying `nonResourceURLs`.
+
 - `/debug/api_priority_and_fairness/dump_priority_levels` - a listing of
   all the priority levels and the current state of each.  You can fetch like this:
 
   ```shell
   kubectl get --raw /debug/api_priority_and_fairness/dump_priority_levels
   ```
 
-  The output is similar to this:
+  The output will be in CSV and similar to this:
 
   ```none
   PriorityLevelName, ActiveQueues, IsIdle, IsQuiescing, WaitingRequests, ExecutingRequests, DispatchedRequests, RejectedRequests, TimedoutRequests, CancelledRequests
@@ -69,7 +72,7 @@ serves the following additional paths at its HTTP(S) ports.
   kubectl get --raw /debug/api_priority_and_fairness/dump_queues
   ```
 
-  The output is similar to this:
+  The output will be in CSV and similar to this:
 
   ```none
   PriorityLevelName, Index,  PendingRequests, ExecutingRequests, SeatsInUse, NextDispatchR,   InitialSeatsSum, MaxSeatsSum, TotalWorkSum
@@ -104,7 +107,7 @@ serves the following additional paths at its HTTP(S) ports.
   kubectl get --raw /debug/api_priority_and_fairness/dump_requests
   ```
 
-  The output is similar to this:
+  The output will be in CSV and similar to this:
 
   ```none
   PriorityLevelName, FlowSchemaName,   QueueIndex, RequestIndexInQueue, FlowDistingsher,                        ArriveTime,                     InitialSeats, FinalSeats, AdditionalLatency, StartTime
@@ -119,7 +122,7 @@ serves the following additional paths at its HTTP(S) ports.
   kubectl get --raw '/debug/api_priority_and_fairness/dump_requests?includeRequestDetails=1'
   ```
 
-  The output is similar to this:
+  The output will be in CSV and similar to this:
 
   ```none
   PriorityLevelName, FlowSchemaName,   QueueIndex, RequestIndexInQueue, FlowDistingsher,                        ArriveTime,                     InitialSeats, FinalSeats, AdditionalLatency, StartTime,                      UserName,                               Verb,   APIPath,                                   Namespace,   Name,   APIVersion, Resource,   SubResource
@@ -145,8 +148,8 @@ serves the following additional paths at its HTTP(S) ports.
 
 ## Debug logging
 
-At `-v=3` or more verbose the server outputs an httplog line for every
-request, and it includes the following attributes.
+At `-v=3` or more verbosity, the API server outputs an httplog line for every
+request in the APIServer log, and it includes the following attributes.
 
 - `apf_fs`: the name of the flow schema to which the request was classified.
 - `apf_pl`: the name of the priority level for that flow schema.
@@ -164,6 +167,8 @@ of how APF handled the request, primarily for debugging purposes.
 ## Response headers
 
 APF adds the following two headers to each HTTP response message.
+They won't appear in the audit log. They can be viewed from the client side.
+For client using klog, use verbosity `-v=8` or higher to view these headers.
 
 - `X-Kubernetes-PF-FlowSchema-UID` holds the UID of the FlowSchema
   object to which the corresponding request was classified.
@@ -174,5 +179,3 @@ APF adds the following two headers to each HTTP response message.
 
 For background information on design details for API priority and fairness, see
 the [enhancement proposal](https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/1040-priority-and-fairness).
-You can make suggestions and feature requests via [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery) 
-or the feature's [slack channel](https://kubernetes.slack.com/messages/api-priority-and-fairness).
