Merge pull request #46769 from MikeSpreitzer/discuss-apf-recursion

Add section to APF page about recursive scenarios

Author: k8s-ci-robot

content/en/docs/concepts/cluster-administration/flow-control.md

@@ -67,6 +67,37 @@ kube-apiserver \
 The command-line flag `--enable-priority-and-fairness=false` will disable the
 API Priority and Fairness feature.
 
+## Recursive server scenarios
+
+API Priority and Fairness must be used carefully in recursive server
+scenarios. These are sccenarios in which some server A, while serving
+a request, issues a subsidiary request to some server B. Perhaps
+server B might even make a further subsidiary call back to server
+A. In situations where Priority and Fairness control is applied to
+both the original request and some subsidiary ones(s), no matter how
+deep in the recursion, there is a danger of priority inversions and/or
+deadlocks.
+
+One example of recursion is when the `kube-apiserver` issues an
+admission webhook call to server B, and while serving that call,
+server B makes a further subsidiary request back to the
+`kube-apiserver`. Another example of recursion is when an `APIService`
+object directs the `kube-apiserver` to delegate requests about a
+certain API group to a custom external server B (this is one of the
+things called "aggregation").
+
+When the original request is known to belong to a certain priority
+level, and the subsidiary controlled requests are classified to higher
+priority levels, this is one possible solution. When the original
+requests can belong to any priority level, the subsidiary controlled
+requests have to be exempt from Priority and Fairness limitation. One
+way to do that is with the objects that configure classification and
+handling, discussed below. Another way is to disable Priority and
+Fairness on server B entirely, using the techniques discussed above. A
+third way, which is the simplest to use when server B is not
+`kube-apisever`, is to build server B with Priority and Fairness
+disabled in the code.
+
 ## Concepts
 
 There are several distinct features involved in the API Priority and Fairness