review: fixes wording and rename objects

keps/sig-api-machinery/20190228-priority-and-fairness.md

@@ -710,11 +710,13 @@ queue’s virtual start time is decremented by G - S.
 ### Example Configuration
 
 
-For kube-apiserver self-maintaining, solving priority-inversion, including requests from: 
+For kube-apiserver self-maintaining, solving priority-inversion, including requests 
+from: 
 
-1. kubectl requests from admin
-2. apiserver loopback requests
-3. delegated auth/admission requests
+1. requests from system-privileged group, including kubectl requests from admin and 
+apiserver loopback requests.
+2. delegated authentication/authorization API groups, including delegated delegated 
+authentication/authorization requests.
 
 ```yaml
 kind: RequestPriority
@@ -786,20 +788,20 @@ Some flow schemata.
 ```yaml
 kind: FlowSchema
 meta:
-  name: system-top
+  name: exempt
 spec:
   matchingPrecedence: 1500
   priorityLevelConfiguration:
     name: exempt
   rules:
-  - rule:
+  - rule: # All resource requests from system-privileged group
       verbs: ['*']
       apiGroups: ['*']
       resources: ['*']
     subjects:
     - kind: Group
       name: "system:masters"
-  - rule:
+  - rule: # Delegated auth[n/z] requests
       verbs: ['*']
       apiGroups: ['authentication.k8s.io', 'authorization.k8s.io']
       resources: ['*']
@@ -813,28 +815,41 @@ spec:
 ```yaml
 kind: FlowSchema
 meta:
-  name: system-high
+  name: nodes
 spec:
   matchingPrecedence: 2500
   priorityLevelConfiguration:
     name: system-high
   distinguisherMethod:
     type: ByUser
   rules:  
-  - rule:
+  - rule: # All resource requests from node group
       verbs: ['*']
       apiGroups: ['*']
       resources: ['*']
     subjects:
     - kind: Group
       name: "system:nodes"
-  - rule:
+  - rule: # All non-resource requests from node group
       verbs: ['*']
       nonResourceURLs: ['*']
     subjects:
     - kind: Group
       name: "system:nodes"    
-  - rule:
+```
+
+```yaml
+kind: FlowSchema
+meta:
+  name: leader-election
+spec:
+  matchingPrecedence: 2500
+  priorityLevelConfiguration:
+    name: system-high
+  distinguisherMethod:
+    type: ByUser
+  rules:  
+  - rule: # Leader-election requests from kube-controller-manager/kube-scheduler
       verbs: ['*']
       apiGroups: ['coordination.k8s.io']
       resources: ['leases']
@@ -848,15 +863,15 @@ spec:
 ```yaml
 kind: FlowSchema
 meta:
-  name: system-low
+  name: kube-manager-controller
 spec:
   matchingPrecedence: 3500
   priorityLevelConfiguration:
     name: system-low
   distinguisherMethod:
     type: ByUser
   rules:  
-  - rule:
+  - rule: # All resource requests from kube-controller-manager
       verbs: ['*']
       apiGroups: ['*']
       resources: ['*']
@@ -865,7 +880,7 @@ spec:
       name: "system:kube-controller-manager"    
     - kind: User
       name: "system:kube-scheduler"    
-  - rule:
+  - rule: # All non-resource requests from kube-controller-manager
       verbs: ['*']
       nonResourceURLs: ['*']
     subjects:
@@ -878,22 +893,48 @@ spec:
 ```yaml
 kind: FlowSchema
 meta:
-  name: workload
+  name: kube-scheduler
+spec:
+  matchingPrecedence: 3500
+  priorityLevelConfiguration:
+    name: system-low
+  distinguisherMethod:
+    type: ByUser
+  rules:  
+  - rule: # All resource requests from kube-scheduler
+      verbs: ['*']
+      apiGroups: ['*']
+      resources: ['*']
+    subjects:
+    - kind: User
+      name: "system:kube-scheduler"    
+  - rule: # All non-resource requests from kube-scheduler
+      verbs: ['*']
+      nonResourceURLs: ['*']
+    subjects:
+    - kind: User
+      name: "system:kube-scheduler"         
+```
+
+```yaml
+kind: FlowSchema
+meta:
+  name: serviceaccounts
 spec:
   matchingPrecedence: 7500
   priorityLevelConfiguration:
     name: workload
   distinguisherMethod:
     type: ByNamespace
   rules:  
-  - rule:
+  - rule: # All in-cluster resource requests from service-account tokens
       verbs: ['*']
       apiGroups: ['*']
       resources: ['*']
     subjects:
     - kind: Group
       name: "system:serviceaccounts"
-  - rule:
+  - rule: # All in-cluster non-requests from service-account tokens
       verbs: ['*']
       nonResourceURLs: ['*']
     subjects:
@@ -904,15 +945,15 @@ spec:
 ```yaml
 kind: FlowSchema
 meta:
-  name: catch-all
+  name: default
 spec:
   matchingPrecedence: 10000
   priorityLevelConfiguration:
     name: default
   distinguisherMethod:
-    type: ByUser
+    type: ByNamespace
   rules:  
-  - rule:
+  - rule: # All resource requests
       verbs: ['*']
       apiGroups: ['*']
       resources: ['*']
@@ -921,7 +962,7 @@ spec:
       name: "system:authenticated"
     - kind: Group
       name: "system:unauthenticated"
-  - rule:
+  - rule: # All non-resource requests
       verbs: ['*']
       nonResourceURLs: ['*']
     subjects:
@@ -1018,7 +1059,7 @@ kind: FlowSchema
 meta:
   name: matches-nothing
 spec:
-  matchingPrecedence: 5000
+  matchingPrecedence: 20000 # either logically lower than "default" flow-schema which catches all requests
   priorityLevelConfiguration:
     name: default
   rules:  
@@ -1028,7 +1069,7 @@ spec:
       resources: ['*']
     subjects:
     - kind: User
-      name: "" # unreachable username
+      name: "null" # or assign it any unreachable username
 ```
 
 ### Prometheus Metrics