diff --git a/content/en/docs/concepts/cluster-administration/flow-control.md b/content/en/docs/concepts/cluster-administration/flow-control.md index e7532707d7..523e511d5c 100644 --- a/content/en/docs/concepts/cluster-administration/flow-control.md +++ b/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