Merge pull request #37202 from SergeyKanzhelev/LimitRangerClarification

Revise and update LimitRange concept

content/en/docs/concepts/policy/limit-range.md

@@ -9,21 +9,23 @@ weight: 10
 <!-- overview -->
 
 By default, containers run with unbounded [compute resources](/docs/concepts/configuration/manage-resources-containers/) on a Kubernetes cluster.
-With resource quotas, cluster administrators can restrict resource consumption and creation on a {{< glossary_tooltip text="namespace" term_id="namespace" >}} basis.
-Within a namespace, a Pod or Container can consume as much CPU and memory as defined by the namespace's resource quota. There is a concern that one Pod or Container could monopolize all available resources. A LimitRange is a policy to constrain resource allocations (to Pods or Containers) in a namespace.
+Using  Kubernetes [resource quotas](/docs/concepts/policy/resource-quotas/),
+administrators (also termed _cluster operators_) can restrict consumption and creation
+of cluster resources (such as CPU time, memory, and persistent storage) within a specified
+{{< glossary_tooltip text="namespace" term_id="namespace" >}}.
+Within a namespace, a {{< glossary_tooltip text="Pod" term_id="Pod" >}} can consume as much CPU and memory as is allowed by the ResourceQuotas that apply to that namespace. As a cluster operator, or as a namespace-level administrator, you might also be concerned about making sure that a single object cannot monopolize all available resources within a namespace.
+
+A LimitRange is a policy to constrain the resource allocations (limits and requests) that you can specify for each applicable object kind (such as Pod or {{< glossary_tooltip text="PersistentVolumeClaim" term_id="persistent-volume-claim" >}}) in a namespace.
 
 <!-- body -->
 
 A _LimitRange_ provides constraints that can:
 
 - Enforce minimum and maximum compute resources usage per Pod or Container in a namespace.
-- Enforce minimum and maximum storage request per PersistentVolumeClaim in a namespace.
+- Enforce minimum and maximum storage request per {{< glossary_tooltip text="PersistentVolumeClaim" term_id="persistent-volume-claim" >}} in a namespace.
 - Enforce a ratio between request and limit for a resource in a namespace.
 - Set default request/limit for compute resources in a namespace and automatically inject them to Containers at runtime.
 
-## Enabling LimitRange
-
-LimitRange support has been enabled by default since Kubernetes 1.10.
 
 A LimitRange is enforced in a particular namespace when there is a
 LimitRange object in that namespace.
@@ -31,17 +33,44 @@ LimitRange object in that namespace.
 The name of a LimitRange object must be a valid
 [DNS subdomain name](/docs/concepts/overview/working-with-objects/names#dns-subdomain-names).
 
-### Overview of Limit Range
+## Constraints on resource limits and requests
 
-- The administrator creates one LimitRange in one namespace.
-- Users create resources like Pods, Containers, and PersistentVolumeClaims in the namespace.
-- The `LimitRanger` admission controller enforces defaults and limits for all Pods and Containers that do not set compute resource requirements and tracks usage to ensure it does not exceed resource minimum, maximum and ratio defined in any LimitRange present in the namespace.
-- If creating or updating a resource (Pod, Container, PersistentVolumeClaim) that violates a LimitRange constraint, the request to the API server will fail with an HTTP status code `403 FORBIDDEN` and a message explaining the constraint that have been violated.
-- If a LimitRange is activated in a namespace for compute resources like `cpu` and `memory`, users must specify
+- The administrator creates a LimitRange in a namespace.
+- Users create (or try to create) objects in that namespace, such as Pods or PersistentVolumeClaims.
+- First, the `LimitRange` admission controller applies default request and limit values for all Pods (and their containers) that do not set compute resource requirements.
+- Second, the `LimitRange` tracks usage to ensure it does not exceed resource minimum, maximum and ratio defined in any `LimitRange` present in the namespace.
+- If you attempt to create or update an object (Pod or PersistentVolumeClaim) that violates a `LimitRange` constraint, your request to the API server will fail with an HTTP status code `403 Forbidden` and a message explaining the constraint that has been violated.
+- If you add a `LimitRange` in a namespace that applies to compute-related resources such as
+ `cpu` and `memory`, you must specify
   requests or limits for those values. Otherwise, the system may reject Pod creation.
-- LimitRange validations occurs only at Pod Admission stage, not on Running Pods.
+- `LimitRange` validations occur only at Pod admission stage, not on running Pods.
+  If you add or modify a LimitRange, the Pods that already exist in that namespace
+  continue unchanged.
+- If two or more `LimitRange` objects exist in the namespace, it is not deterministic which default value will be applied.
 
-Examples of policies that could be created using limit range are:
+## LimitRange and admission checks for Pods
+
+A `LimitRange` does **not** check the consistency of the default values it applies. This means that a default value for the _limit_ that is set by `LimitRange` may be less than the _request_ value specified for the container in the spec that a client submits to the API server. If that happens, the final Pod will not be scheduleable.
+
+For example, if "LimitRange` is defined as following:
+
+{{< codenew file="concepts/policy/limit-range/problematic-limit-range.yaml" >}}
+
+
+The following Pod that declares the Request of `700m`, but not the limit:
+
+{{< codenew file="concepts/policy/limit-range/example-conflict-with-limitrange-cpu.yaml" >}}
+
+
+This Pod will not be scheduled with the error `Pod "ConflictingCpuSettings" is invalid: spec.containers[0].resources.requests: Invalid value: "700m": must be less than or equal to cpu limit`
+
+If both, request and limit are set, the Pod will be scheduled successfully with the same `LimitRange` object:
+
+{{< codenew file="concepts/policy/limit-range/example-no-conflict-with-limitrange-cpu.yaml" >}}
+
+## Example resource constraints
+
+Examples of policies that could be created using `LimitRange` are:
 
 - In a 2 node cluster with a capacity of 8 GiB RAM and 16 cores, constrain Pods in a namespace to request 100m of CPU with a max limit of 500m for CPU and request 200Mi for Memory with a max limit of 600Mi for Memory.
 - Define default CPU limit and request to 150m and memory default request to 300Mi for Containers started with no cpu and memory requests in their specs.

content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md

@@ -167,6 +167,14 @@ resources:
     memory: 128Mi
 ```
 
+{{< note >}}
+
+A `LimitRange` does **not** check the consistency of the default values it applies. This means that a default value for the _limit_ that is set by `LimitRange` may be less than the _request_ value specified for the container in the spec that a client submits to the API server. If that happens, the final Pod will not be scheduleable.
+See [Constraints on resource limits and requests](/docs/concepts/policy/limit-range/#constraints-on-resource-limits-and-requests) for more details.
+
+{{< /note >}}
+
+
 ## Motivation for default memory limits and requests
 
 If your namespace has a memory {{< glossary_tooltip text="resource quota" term_id="resource-quota" >}}

content/en/examples/concepts/policy/limit-range/example-conflict-with-limitrange-cpu.yaml

@@ -0,0 +1,11 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: example-conflict-with-limitrange-cpu
+spec:
+  containers:
+  - name: demo
+    image: registry.k8s.io/pause:2.0
+    resources:
+      requests:
+        cpu: 700m

content/en/examples/concepts/policy/limit-range/example-no-conflict-with-limitrange-cpu.yaml

@@ -0,0 +1,13 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: example-no-conflict-with-limitrange-cpu
+spec:
+  containers:
+  - name: demo
+    image: registry.k8s.io/pause:2.0
+    resources:
+      requests:
+        cpu: 700m
+      limits:
+        cpu: 700m

content/en/examples/concepts/policy/limit-range/problematic-limit-range.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: LimitRange
+metadata:
+  name: cpu-resource-constraint
+spec:
+  limits:
+  - default: # this section defines default limits
+      cpu: 500m
+    defaultRequest: # this section defines default requests
+      cpu: 500m
+    max: # max and min define the limit range
+      cpu: "1"
+    min:
+      cpu: 100m