From a706ae9bcde803610aab686f663d789f97c4d23f Mon Sep 17 00:00:00 2001
From: "Bobby (Babak) Salamat" <bsalamat@google.com>
Date: Wed, 4 Jul 2018 01:15:25 -0700
Subject: [PATCH] Add note about existing PriorityClasses (#9279)

* Add note about existing PriorityClasses

* Addressed the reviewer's comments
---
 .../configuration/pod-priority-preemption.md  | 21 ++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/content/en/docs/concepts/configuration/pod-priority-preemption.md b/content/en/docs/concepts/configuration/pod-priority-preemption.md
index 193880eb43..0a211c5478 100644
--- a/content/en/docs/concepts/configuration/pod-priority-preemption.md
+++ b/content/en/docs/concepts/configuration/pod-priority-preemption.md
@@ -111,12 +111,27 @@ object for each such mapping that they want.
 PriorityClass also has two optional fields: `globalDefault` and `description`.
 The `globalDefault` field indicates that the value of this PriorityClass should
 be used for Pods without a `priorityClassName`. Only one PriorityClass with
-`globalDefault`  set to true can exist in the system. If there is no PriorityClass
+`globalDefault` set to true should exist in the system. If there is more than one
+PriorityClass with `globalDefault` set to true, the value of the smallest
+of those PriorityClasses is used as the default priority. If there is no PriorityClass
 with `globalDefault` set, the priority of Pods with no `priorityClassName` is zero.
 
 The `description` field is an arbitrary string. It is meant to tell users of
 the cluster when they should use this PriorityClass.
 
+Kubernetes comes with two predefined PriorityClasses: `system-node-critical`, and
+`system-cluster-critical`. The former has the highest priority and is used for critical
+system Pods that must run on all or most of the nodes and should never
+be preempted. The latter is used for system critical Pods that must always
+run in a cluster, but they can be terminated on one node and started on a
+different node.
+
+{{< note >}}
+**Note**: You should never use these PriorityClasses that are dedicated to
+system components for non-system Pods. Otherwise, Pods with such high priorities
+might preempt system critical components, causing disruption of cluster services.  
+{{< /note >}}
+
 ### Notes about PodPriority and existing clusters
 - If you upgrade your existing cluster and enable this feature, the priority
 of your existing Pods is effectively zero.
@@ -138,7 +153,7 @@ metadata:
   name: high-priority
 value: 1000000
 globalDefault: false
-description: "This priority class should be used for XYZ service pods only."
+description: "This priority class should be used for XYZ service Pods only."
 ```
 
 ## Pod priority
@@ -242,7 +257,7 @@ preceding question must be yes. If the answer is no, the Node is not considered
 for preemption.
 {{< /note >}}
 
-If a pending Pod has inter-pod affinity to one or more of the lower-priority Pods
+If a pending Pod has inter-Pod affinity to one or more of the lower-priority Pods
 on the Node, the inter-Pod affinity rule cannot be satisfied in the absence of those
 lower-priority Pods. In this case, the scheduler does not preempt any Pods on the
 Node. Instead, it looks for another Node. The scheduler might find a suitable Node