From 5ab064ceea06ab56c85cfc19a395fd679643a659 Mon Sep 17 00:00:00 2001
From: Tim Bannister <tim@scalefactory.com>
Date: Tue, 12 Oct 2021 23:21:17 +0100
Subject: [PATCH 1/2] Tidy resource management task pages
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Revise tasks within “Manage Memory, CPU, and API Resources”:

- reword to avoid implying that API clients can create a container
  (you can, but its done by creating a Pod)
- call a manifest a manifest
- use tooltips where relevant
- link to new API reference not the old one
- other improvements
---
 .../cpu-constraint-namespace.md               | 64 +++++++-------
 .../manage-resources/cpu-default-namespace.md | 83 ++++++++++++-------
 .../memory-constraint-namespace.md            | 80 +++++++++---------
 .../memory-default-namespace.md               | 73 ++++++++++------
 .../quota-memory-cpu-namespace.md             | 53 +++++++-----
 .../manage-resources/quota-pod-namespace.md   | 27 +++---
 6 files changed, 225 insertions(+), 155 deletions(-)

diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md
index e3758e05c9..d640195efc 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md
@@ -7,9 +7,10 @@ weight: 40
 
 <!-- overview -->
 
-This page shows how to set minimum and maximum values for the CPU resources used by Containers
-and Pods in a namespace. You specify minimum and maximum CPU values in a
-[LimitRange](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#limitrange-v1-core)
+This page shows how to set minimum and maximum values for the CPU resources used by containers
+and Pods in a {{< glossary_tooltip text="namespace" term_id="namespace" >}}. You specify minimum
+and maximum CPU values in a
+[LimitRange](/docs/reference/kubernetes-api/policy-resources/limit-range-v1/)
 object. If a Pod does not meet the constraints imposed by the LimitRange, it cannot be created
 in the namespace.
 
@@ -19,11 +20,13 @@ in the namespace.
 ## {{% heading "prerequisites" %}}
 
 
-{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
-
-Your cluster must have at least 1 CPU available for use to run the task examples.
+{{< include "task-tutorial-prereqs.md" >}}
 
+You must have access to create namespaces in your cluster.
 
+Your cluster must have at least 1.0 CPU available for use to run the task examples.
+See [meaning of CPU](/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu)
+to learn what Kubernetes means by “1 CPU”.
 
 
 <!-- steps -->
@@ -39,7 +42,7 @@ kubectl create namespace constraints-cpu-example
 
 ## Create a LimitRange and a Pod
 
-Here's the configuration file for a LimitRange:
+Here's an example manifest for a LimitRange:
 
 {{< codenew file="admin/resource/cpu-constraints.yaml" >}}
 
@@ -72,15 +75,15 @@ limits:
   type: Container
 ```
 
-Now whenever a Container is created in the constraints-cpu-example namespace, Kubernetes
-performs these steps:
+Now whenever you create a Pod in the constraints-cpu-example namespace (or some other client
+of the Kubernetes API creates an equivalent Pod), Kubernetes performs these steps:
 
-* If the Container does not specify its own CPU request and limit, assign the default
-CPU request and limit to the Container.
+* If any container in that Pod does not specify its own CPU request and limit, the control plane
+  assigns the default CPU request and limit to that container.
 
-* Verify that the Container specifies a CPU request that is greater than or equal to 200 millicpu.
+* Verify that every container in that Pod specifies a CPU request that is greater than or equal to 200 millicpu.
 
-* Verify that the Container specifies a CPU limit that is less than or equal to 800 millicpu.
+* Verify that every container in that Pod specifies a CPU limit that is less than or equal to 800 millicpu.
 
 {{< note >}}
 When creating a `LimitRange` object, you can specify limits on huge-pages
@@ -88,7 +91,7 @@ or GPUs as well. However, when both `default` and `defaultRequest` are specified
 on these resources, the two values must be the same.
 {{< /note >}}
 
-Here's the configuration file for a Pod that has one Container. The Container manifest
+Here's a manifest for a Pod that has one container. The container manifest
 specifies a CPU request of 500 millicpu and a CPU limit of 800 millicpu. These satisfy the
 minimum and maximum CPU constraints imposed by the LimitRange.
 
@@ -100,7 +103,7 @@ Create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints-pod.yaml --namespace=constraints-cpu-example
 ```
 
-Verify that the Pod's Container is running:
+Verify that the Pod is running and that its container is healthy:
 
 ```shell
 kubectl get pod constraints-cpu-demo --namespace=constraints-cpu-example
@@ -112,7 +115,7 @@ View detailed information about the Pod:
 kubectl get pod constraints-cpu-demo --output=yaml --namespace=constraints-cpu-example
 ```
 
-The output shows that the Container has a CPU request of 500 millicpu and CPU limit
+The output shows that the Pod's only container has a CPU request of 500 millicpu and CPU limit
 of 800 millicpu. These satisfy the constraints imposed by the LimitRange.
 
 ```yaml
@@ -131,7 +134,7 @@ kubectl delete pod constraints-cpu-demo --namespace=constraints-cpu-example
 
 ## Attempt to create a Pod that exceeds the maximum CPU constraint
 
-Here's the configuration file for a Pod that has one Container. The Container specifies a
+Here's a manifest for a Pod that has one container. The container specifies a
 CPU request of 500 millicpu and a cpu limit of 1.5 cpu.
 
 {{< codenew file="admin/resource/cpu-constraints-pod-2.yaml" >}}
@@ -142,8 +145,8 @@ Attempt to create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints-pod-2.yaml --namespace=constraints-cpu-example
 ```
 
-The output shows that the Pod does not get created, because the Container specifies a CPU limit that is
-too large:
+The output shows that the Pod does not get created, because it defines an unacceptable container.
+That container is not acceptable because it specifies a CPU limit that is too large:
 
 ```
 Error from server (Forbidden): error when creating "examples/admin/resource/cpu-constraints-pod-2.yaml":
@@ -152,7 +155,7 @@ pods "constraints-cpu-demo-2" is forbidden: maximum cpu usage per Container is 8
 
 ## Attempt to create a Pod that does not meet the minimum CPU request
 
-Here's the configuration file for a Pod that has one Container. The Container specifies a
+Here's a manifest for a Pod that has one container. The container specifies a
 CPU request of 100 millicpu and a CPU limit of 800 millicpu.
 
 {{< codenew file="admin/resource/cpu-constraints-pod-3.yaml" >}}
@@ -163,8 +166,9 @@ Attempt to create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/cpu-constraints-pod-3.yaml --namespace=constraints-cpu-example
 ```
 
-The output shows that the Pod does not get created, because the Container specifies a CPU
-request that is too small:
+The output shows that the Pod does not get created, because it defines an unacceptable container.
+That container is not acceptable because it specifies a CPU limit that is lower than the
+enforced minimum:
 
 ```
 Error from server (Forbidden): error when creating "examples/admin/resource/cpu-constraints-pod-3.yaml":
@@ -173,8 +177,8 @@ pods "constraints-cpu-demo-3" is forbidden: minimum cpu usage per Container is 2
 
 ## Create a Pod that does not specify any CPU request or limit
 
-Here's the configuration file for a Pod that has one Container. The Container does not
-specify a CPU request, and it does not specify a CPU limit.
+Here's a manifest for a Pod that has one container. The container does not
+specify a CPU request, nor does it specify a CPU limit.
 
 {{< codenew file="admin/resource/cpu-constraints-pod-4.yaml" >}}
 
@@ -190,8 +194,9 @@ View detailed information about the Pod:
 kubectl get pod constraints-cpu-demo-4 --namespace=constraints-cpu-example --output=yaml
 ```
 
-The output shows that the Pod's Container has a CPU request of 800 millicpu and a CPU limit of 800 millicpu.
-How did the Container get those values?
+The output shows that the Pod's single container has a CPU request of 800 millicpu and a
+CPU limit of 800 millicpu.
+How did that container get those values?
 
 ```yaml
 resources:
@@ -201,11 +206,12 @@ resources:
     cpu: 800m
 ```
 
-Because your Container did not specify its own CPU request and limit, it was given the
+Because that container did not specify its own CPU request and limit, the control plane
+applied the
 [default CPU request and limit](/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace/)
-from the LimitRange.
+from the LimitRange for this namespace.
 
-At this point, your Container might be running or it might not be running. Recall that a prerequisite for this task is that your cluster must have at least 1 CPU available for use. If each of your Nodes has only 1 CPU, then there might not be enough allocatable CPU on any Node to accommodate a request of 800 millicpu. If you happen to be using Nodes with 2 CPU, then you probably have enough CPU to accommodate the 800 millicpu request.
+At this point, your Pod might be running or it might not be running. Recall that a prerequisite for this task is that your cluster must have at least 1 CPU available for use. If each of your Nodes has only 1 CPU, then there might not be enough allocatable CPU on any Node to accommodate a request of 800 millicpu. If you happen to be using Nodes with 2 CPU, then you probably have enough CPU to accommodate the 800 millicpu request.
 
 Delete your Pod:
 
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace.md
index 0156d67e4d..d58baca108 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace.md
@@ -6,19 +6,29 @@ weight: 20
 
 <!-- overview -->
 
-This page shows how to configure default CPU requests and limits for a namespace.
-A Kubernetes cluster can be divided into namespaces. If a Container is created in a namespace
-that has a default CPU limit, and the Container does not specify its own CPU limit, then
-the Container is assigned the default CPU limit. Kubernetes assigns a default CPU request
-under certain conditions that are explained later in this topic.
+This page shows how to configure default CPU requests and limits for a
+{{< glossary_tooltip text="namespace" term_id="namespace" >}}.
 
+A Kubernetes cluster can be divided into namespaces. If you create a Pod within a
+namespace that has a default CPU
+[limit](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits), and any container in that Pod does not specify
+its own CPU limit, then the
+{{< glossary_tooltip text="control plane" term_id="control-plane" >}} assigns the default
+CPU limit to that container.
 
+Kubernetes assigns a default CPU
+[request](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits),
+but only under certain conditions that are explained later in this page.
 
 ## {{% heading "prerequisites" %}}
 
 
-{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
+{{< include "task-tutorial-prereqs.md" >}}
 
+You must have access to create namespaces in your cluster.
+
+If you're not already familiar with what Kubernetes means by 1.0 CPU,
+read [meaning of CPU](/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu).
 
 <!-- steps -->
 
@@ -33,8 +43,8 @@ kubectl create namespace default-cpu-example
 
 ## Create a LimitRange and a Pod
 
-Here's the configuration file for a LimitRange object. The configuration specifies
-a default CPU request and a default CPU limit.
+Here's a manifest for an example {{< glossary_tooltip text="LimitRange" term_id="limitrange" >}}.
+The manifest specifies a default CPU request and a default CPU limit.
 
 {{< codenew file="admin/resource/cpu-defaults.yaml" >}}
 
@@ -44,12 +54,12 @@ Create the LimitRange in the default-cpu-example namespace:
 kubectl apply -f https://k8s.io/examples/admin/resource/cpu-defaults.yaml --namespace=default-cpu-example
 ```
 
-Now if a Container is created in the default-cpu-example namespace, and the
-Container does not specify its own values for CPU request and CPU limit,
-the Container is given a default CPU request of 0.5 and a default
+Now if you create a Pod in the default-cpu-example namespace, and any container
+in that Pod does not specify its own values for CPU request and CPU limit,
+then the control plane applies default values: a CPU request of 0.5 and a default
 CPU limit of 1.
 
-Here's the configuration file for a Pod that has one Container. The Container
+Here's a manifest for a Pod that has one container. The container
 does not specify a CPU request and limit.
 
 {{< codenew file="admin/resource/cpu-defaults-pod.yaml" >}}
@@ -66,8 +76,9 @@ View the Pod's specification:
 kubectl get pod default-cpu-demo --output=yaml --namespace=default-cpu-example
 ```
 
-The output shows that the Pod's Container has a CPU request of 500 millicpus and
-a CPU limit of 1 cpu. These are the default values specified by the LimitRange.
+The output shows that the Pod's only container has a CPU request of 500m `cpu`
+(which you can read as “500 millicpu”), and a CPU limit of 1 `cpu`.
+These are the default values specified by the LimitRange.
 
 ```shell
 containers:
@@ -81,9 +92,9 @@ containers:
       cpu: 500m
 ```
 
-## What if you specify a Container's limit, but not its request?
+## What if you specify a container's limit, but not its request?
 
-Here's the configuration file for a Pod that has one Container. The Container
+Here's a manifest for a Pod that has one container. The container
 specifies a CPU limit, but not a request:
 
 {{< codenew file="admin/resource/cpu-defaults-pod-2.yaml" >}}
@@ -95,14 +106,15 @@ Create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/cpu-defaults-pod-2.yaml --namespace=default-cpu-example
 ```
 
-View the Pod specification:
+View the [specification](/docs/concepts/overview/working-with-objects/kubernetes-objects/#object-spec-and-status)
+of the Pod that you created:
 
 ```
 kubectl get pod default-cpu-demo-2 --output=yaml --namespace=default-cpu-example
 ```
 
-The output shows that the Container's CPU request is set to match its CPU limit.
-Notice that the Container was not assigned the default CPU request value of 0.5 cpu.
+The output shows that the container's CPU request is set to match its CPU limit.
+Notice that the container was not assigned the default CPU request value of 0.5 `cpu`:
 
 ```
 resources:
@@ -112,9 +124,9 @@ resources:
     cpu: "1"
 ```
 
-## What if you specify a Container's request, but not its limit?
+## What if you specify a container's request, but not its limit?
 
-Here's the configuration file for a Pod that has one Container. The Container
+Here's an example manifest for a Pod that has one container. The container
 specifies a CPU request, but not a limit:
 
 {{< codenew file="admin/resource/cpu-defaults-pod-3.yaml" >}}
@@ -125,15 +137,16 @@ Create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/cpu-defaults-pod-3.yaml --namespace=default-cpu-example
 ```
 
-View the Pod specification:
+View the specification of the Pod that you created:
 
 ```
 kubectl get pod default-cpu-demo-3 --output=yaml --namespace=default-cpu-example
 ```
 
-The output shows that the Container's CPU request is set to the value specified in the
-Container's configuration file. The Container's CPU limit is set to 1 cpu, which is the
-default CPU limit for the namespace.
+The output shows that the container's CPU request is set to the value you specified at
+the time you created the Pod (in other words: it matches the manifest).
+However, the same container's CPU limit is set to 1 `cpu`, which is the default CPU limit
+for that namespace.
 
 ```
 resources:
@@ -145,16 +158,22 @@ resources:
 
 ## Motivation for default CPU limits and requests
 
-If your namespace has a
-[resource quota](/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace/),
+If your namespace has a CPU {{< glossary_tooltip text="resource quota" term_id="resource-quota" >}}
+configured,
 it is helpful to have a default value in place for CPU limit.
-Here are two of the restrictions that a resource quota imposes on a namespace:
+Here are two of the restrictions that a CPU resource quota imposes on a namespace:
 
-* Every Container that runs in the namespace must have its own CPU limit.
-* The total amount of CPU used by all Containers in the namespace must not exceed a specified limit.
+* For every Pod that runs in the namespace, each of its containers must have a CPU limit.
+* CPU limits apply a resource reservation on the node where the Pod in question is scheduled.
+  The total amount of CPU that is reserved for use by all Pods in the namespace must not
+  exceed a specified limit.
+
+When you add a LimitRange:
+
+If any Pod in that namespace that includes a container does not specify its own CPU limit,
+the control plane applies the default CPU limit to that container, and the Pod can be
+allowed to run in a namespace that is restricted by a CPU ResourceQuota.
 
-If a Container does not specify its own CPU limit, it is given the default limit, and then
-it can be allowed to run in a namespace that is restricted by a quota.
 
 ## Clean up
 
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md
index de80b80ce3..8db50fb4d1 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md
@@ -7,7 +7,7 @@ weight: 30
 
 <!-- overview -->
 
-This page shows how to set minimum and maximum values for memory used by Containers
+This page shows how to set minimum and maximum values for memory used by containers
 running in a namespace. You specify minimum and maximum memory values in a
 [LimitRange](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#limitrange-v1-core)
 object. If a Pod does not meet the constraints imposed by the LimitRange,
@@ -15,16 +15,14 @@ it cannot be created in the namespace.
 
 
 
-
 ## {{% heading "prerequisites" %}}
 
 
-{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
-
-Each node in your cluster must have at least 1 GiB of memory.
-
+{{< include "task-tutorial-prereqs.md" >}}
 
+You must have access to create namespaces in your cluster.
 
+Each node in your cluster must have at least 1 GiB of memory available for Pods.
 
 <!-- steps -->
 
@@ -39,7 +37,7 @@ kubectl create namespace constraints-mem-example
 
 ## Create a LimitRange and a Pod
 
-Here's the configuration file for a LimitRange:
+Here's an example manifest for a LimitRange:
 
 {{< codenew file="admin/resource/memory-constraints.yaml" >}}
 
@@ -72,18 +70,19 @@ file for the LimitRange, they were created automatically.
     type: Container
 ```
 
-Now whenever a Container is created in the constraints-mem-example namespace, Kubernetes
+Now whenever you define a Pod within the constraints-mem-example namespace, Kubernetes
 performs these steps:
 
-* If the Container does not specify its own memory request and limit, assign the default
-memory request and limit to the Container.
+* If any container in that Pod does not specify its own memory request and limit, assign
+the default memory request and limit to that container.
 
-* Verify that the Container has a memory request that is greater than or equal to 500 MiB.
+* Verify that every container in that Pod requests at least 500 MiB of memory.
 
-* Verify that the Container has a memory limit that is less than or equal to 1 GiB.
+* Verify that every container in that Pod requests no more than 1024 MiB (1 GiB)
+  of memory.
 
-Here's the configuration file for a Pod that has one Container. The Container manifest
-specifies a memory request of 600 MiB and a memory limit of 800 MiB. These satisfy the
+Here's a manifest for a Pod that has one container. Within the Pod spec, the sole
+container specifies a memory request of 600 MiB and a memory limit of 800 MiB. These satisfy the
 minimum and maximum memory constraints imposed by the LimitRange.
 
 {{< codenew file="admin/resource/memory-constraints-pod.yaml" >}}
@@ -94,7 +93,7 @@ Create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints-pod.yaml --namespace=constraints-mem-example
 ```
 
-Verify that the Pod's Container is running:
+Verify that the Pod is running and that its container is healthy:
 
 ```shell
 kubectl get pod constraints-mem-demo --namespace=constraints-mem-example
@@ -106,8 +105,9 @@ View detailed information about the Pod:
 kubectl get pod constraints-mem-demo --output=yaml --namespace=constraints-mem-example
 ```
 
-The output shows that the Container has a memory request of 600 MiB and a memory limit
-of 800 MiB. These satisfy the constraints imposed by the LimitRange.
+The output shows that the container within that Pod has a memory request of 600 MiB and
+a memory limit of 800 MiB. These satisfy the constraints imposed by the LimitRange for
+this namespace:
 
 ```yaml
 resources:
@@ -125,7 +125,7 @@ kubectl delete pod constraints-mem-demo --namespace=constraints-mem-example
 
 ## Attempt to create a Pod that exceeds the maximum memory constraint
 
-Here's the configuration file for a Pod that has one Container. The Container specifies a
+Here's a manifest for a Pod that has one container. The container specifies a
 memory request of 800 MiB and a memory limit of 1.5 GiB.
 
 {{< codenew file="admin/resource/memory-constraints-pod-2.yaml" >}}
@@ -136,8 +136,8 @@ Attempt to create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints-pod-2.yaml --namespace=constraints-mem-example
 ```
 
-The output shows that the Pod does not get created, because the Container specifies a memory limit that is
-too large:
+The output shows that the Pod does not get created, because it defines a container that
+requests more memory than is allowed:
 
 ```
 Error from server (Forbidden): error when creating "examples/admin/resource/memory-constraints-pod-2.yaml":
@@ -146,7 +146,7 @@ pods "constraints-mem-demo-2" is forbidden: maximum memory usage per Container i
 
 ## Attempt to create a Pod that does not meet the minimum memory request
 
-Here's the configuration file for a Pod that has one Container. The Container specifies a
+Here's a manifest for a Pod that has one container. That container specifies a
 memory request of 100 MiB and a memory limit of 800 MiB.
 
 {{< codenew file="admin/resource/memory-constraints-pod-3.yaml" >}}
@@ -157,8 +157,8 @@ Attempt to create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints-pod-3.yaml --namespace=constraints-mem-example
 ```
 
-The output shows that the Pod does not get created, because the Container specifies a memory
-request that is too small:
+The output shows that the Pod does not get created, because it defines a container
+that requests less memory than the enforced minimum:
 
 ```
 Error from server (Forbidden): error when creating "examples/admin/resource/memory-constraints-pod-3.yaml":
@@ -167,9 +167,7 @@ pods "constraints-mem-demo-3" is forbidden: minimum memory usage per Container i
 
 ## Create a Pod that does not specify any memory request or limit
 
-
-
-Here's the configuration file for a Pod that has one Container. The Container does not
+Here's a manifest for a Pod that has one container. The container does not
 specify a memory request, and it does not specify a memory limit.
 
 {{< codenew file="admin/resource/memory-constraints-pod-4.yaml" >}}
@@ -182,12 +180,12 @@ kubectl apply -f https://k8s.io/examples/admin/resource/memory-constraints-pod-4
 
 View detailed information about the Pod:
 
-```
+```shell
 kubectl get pod constraints-mem-demo-4 --namespace=constraints-mem-example --output=yaml
 ```
 
-The output shows that the Pod's Container has a memory request of 1 GiB and a memory limit of 1 GiB.
-How did the Container get those values?
+The output shows that the Pod's only container has a memory request of 1 GiB and a memory limit of 1 GiB.
+How did that container get those values?
 
 ```
 resources:
@@ -197,11 +195,20 @@ resources:
     memory: 1Gi
 ```
 
-Because your Container did not specify its own memory request and limit, it was given the
+Because your Pod did not define any memory request and limit for that container, the cluster
+applied a
 [default memory request and limit](/docs/tasks/administer-cluster/manage-resources/memory-default-namespace/)
 from the LimitRange.
 
-At this point, your Container might be running or it might not be running. Recall that a prerequisite
+This means that the definition of that Pod shows those values. You can check it using
+`kubectl describe`:
+
+```shell
+# Look for the "Requests:" section of the output
+kubectl describe pod constraints-mem-demo-4 --namespace=constraints-mem-example
+```
+
+At this point, your Pod might be running or it might not be running. Recall that a prerequisite
 for this task is that your Nodes have at least 1 GiB of memory. If each of your Nodes has only
 1 GiB of memory, then there is not enough allocatable memory on any Node to accommodate a memory
 request of 1 GiB. If you happen to be using Nodes with 2 GiB of memory, then you probably have
@@ -209,7 +216,7 @@ enough space to accommodate the 1 GiB request.
 
 Delete your Pod:
 
-```
+```shell
 kubectl delete pod constraints-mem-demo-4 --namespace=constraints-mem-example
 ```
 
@@ -224,12 +231,12 @@ Pods that were created previously.
 As a cluster administrator, you might want to impose restrictions on the amount of memory that Pods can use.
 For example:
 
-* Each Node in a cluster has 2 GB of memory. You do not want to accept any Pod that requests
-more than 2 GB of memory, because no Node in the cluster can support the request.
+* Each Node in a cluster has 2 GiB of memory. You do not want to accept any Pod that requests
+more than 2 GiB of memory, because no Node in the cluster can support the request.
 
 * A cluster is shared by your production and development departments.
-You want to allow production workloads to consume up to 8 GB of memory, but
-you want development workloads to be limited to 512 MB. You create separate namespaces
+You want to allow production workloads to consume up to 8 GiB of memory, but
+you want development workloads to be limited to 512 MiB. You create separate namespaces
 for production and development, and you apply memory constraints to each namespace.
 
 ## Clean up
@@ -241,7 +248,6 @@ kubectl delete namespace constraints-mem-example
 ```
 
 
-
 ## {{% heading "whatsnext" %}}
 
 
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md
index d2f4790abc..1d0fb3eb05 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md
@@ -6,17 +6,28 @@ weight: 10
 
 <!-- overview -->
 
-This page shows how to configure default memory requests and limits for a namespace.
-If a Container is created in a namespace that has a default memory limit, and the Container
-does not specify its own memory limit, then the Container is assigned the default memory limit.
+This page shows how to configure default memory requests and limits for a
+{{< glossary_tooltip text="namespace" term_id="namespace" >}}.
+
+A Kubernetes cluster can be divided into namespaces. Once you have a namespace that
+that has a default memory
+[limit](/docs/concepts/configuration/manage-resources-containers/#requests-and-limits),
+and you then try to create a Pod with a container that does not specify its own memory
+limit its own memory limit, then the
+{{< glossary_tooltip text="control plane" term_id="control-plane" >}} assigns the default
+memory limit to that container.
+
 Kubernetes assigns a default memory request under certain conditions that are explained later in this topic.
 
 
 
+
 ## {{% heading "prerequisites" %}}
 
 
-{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
+{{< include "task-tutorial-prereqs.md" >}}
+
+You must have access to create namespaces in your cluster.
 
 Each node in your cluster must have at least 2 GiB of memory.
 
@@ -35,8 +46,9 @@ kubectl create namespace default-mem-example
 
 ## Create a LimitRange and a Pod
 
-Here's the configuration file for a LimitRange object. The configuration specifies
-a default memory request and a default memory limit.
+Here's a manifest for an example {{< glossary_tooltip text="LimitRange" term_id="limitrange" >}}.
+The manifest specifies a default memory
+request and a default memory limit.
 
 {{< codenew file="admin/resource/memory-defaults.yaml" >}}
 
@@ -46,12 +58,13 @@ Create the LimitRange in the default-mem-example namespace:
 kubectl apply -f https://k8s.io/examples/admin/resource/memory-defaults.yaml --namespace=default-mem-example
 ```
 
-Now if a Container is created in the default-mem-example namespace, and the
-Container does not specify its own values for memory request and memory limit,
-the Container is given a default memory request of 256 MiB and a default
-memory limit of 512 MiB.
+Now if you create a Pod in the default-mem-example namespace, and any container
+within that Pod does not specify its own values for memory request and memory limit,
+then the {{< glossary_tooltip text="control plane" term_id="control-plane" >}}
+applies default values: a memory request of 256MiB and a memory limit of 512MiB.
 
-Here's the configuration file for a Pod that has one Container. The Container
+
+Here's an example manifest for a Pod that has one container. The container
 does not specify a memory request and limit.
 
 {{< codenew file="admin/resource/memory-defaults-pod.yaml" >}}
@@ -68,7 +81,7 @@ View detailed information about the Pod:
 kubectl get pod default-mem-demo --output=yaml --namespace=default-mem-example
 ```
 
-The output shows that the Pod's Container has a memory request of 256 MiB and
+The output shows that the Pod's container has a memory request of 256 MiB and
 a memory limit of 512 MiB. These are the default values specified by the LimitRange.
 
 ```shell
@@ -89,9 +102,9 @@ Delete your Pod:
 kubectl delete pod default-mem-demo --namespace=default-mem-example
 ```
 
-## What if you specify a Container's limit, but not its request?
+## What if you specify a container's limit, but not its request?
 
-Here's the configuration file for a Pod that has one Container. The Container
+Here's a manifest for a Pod that has one container. The container
 specifies a memory limit, but not a request:
 
 {{< codenew file="admin/resource/memory-defaults-pod-2.yaml" >}}
@@ -109,8 +122,8 @@ View detailed information about the Pod:
 kubectl get pod default-mem-demo-2 --output=yaml --namespace=default-mem-example
 ```
 
-The output shows that the Container's memory request is set to match its memory limit.
-Notice that the Container was not assigned the default memory request value of 256Mi.
+The output shows that the container's memory request is set to match its memory limit.
+Notice that the container was not assigned the default memory request value of 256Mi.
 
 ```
 resources:
@@ -120,9 +133,9 @@ resources:
     memory: 1Gi
 ```
 
-## What if you specify a Container's request, but not its limit?
+## What if you specify a container's request, but not its limit?
 
-Here's the configuration file for a Pod that has one Container. The Container
+Here's a manifest for a Pod that has one container. The container
 specifies a memory request, but not a limit:
 
 {{< codenew file="admin/resource/memory-defaults-pod-3.yaml" >}}
@@ -139,9 +152,9 @@ View the Pod's specification:
 kubectl get pod default-mem-demo-3 --output=yaml --namespace=default-mem-example
 ```
 
-The output shows that the Container's memory request is set to the value specified in the
-Container's configuration file. The Container's memory limit is set to 512Mi, which is the
-default memory limit for the namespace.
+The output shows that the container's memory request is set to the value specified in the
+container's manifest. The container is limited to use no more than 512MiB of
+memory, which matches the default memory limit for the namespace.
 
 ```
 resources:
@@ -153,15 +166,23 @@ resources:
 
 ## Motivation for default memory limits and requests
 
-If your namespace has a resource quota,
+If your namespace has a memory {{< glossary_tooltip text="resource quota" term_id="resource-quota" >}}
+configured,
 it is helpful to have a default value in place for memory limit.
 Here are two of the restrictions that a resource quota imposes on a namespace:
 
-* Every Container that runs in the namespace must have its own memory limit.
-* The total amount of memory used by all Containers in the namespace must not exceed a specified limit.
+* For every Pod that runs in the namespace, the Pod and each of its containers must have a memory limit.
+  (If you specify a memory limit for every container in a Pod, Kubernetes can infer the Pod-level memory
+  limit by adding up the limits for its containers).
+* CPU limits apply a resource reservation on the node where the Pod in question is scheduled.
+  The total amount of memory reserved for all Pods in the namespace must not exceed a specified limit.
+* The total amount of memory actually used by all Pods in the namespace must also not exceed a specified limit.
 
-If a Container does not specify its own memory limit, it is given the default limit, and then
-it can be allowed to run in a namespace that is restricted by a quota.
+When you add a LimitRange:
+
+If any Pod in that namespace that includes a container does not specify its own memory limit,
+the control plane applies the default memory limit to that container, and the Pod can be
+allowed to run in a namespace that is restricted by a memory ResourceQuota.
 
 ## Clean up
 
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace.md
index 4869c35e06..290cac909f 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace.md
@@ -8,8 +8,9 @@ weight: 50
 <!-- overview -->
 
 This page shows how to set quotas for the total amount memory and CPU that
-can be used by all Containers running in a namespace. You specify quotas in a
-[ResourceQuota](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcequota-v1-core)
+can be used by all Pods running in a {{< glossary_tooltip text="namespace" term_id="namespace" >}}.
+You specify quotas in a
+[ResourceQuota](/docs/reference/kubernetes-api/policy-resources/resource-quota-v1/)
 object.
 
 
@@ -17,14 +18,13 @@ object.
 
 ## {{% heading "prerequisites" %}}
 
+{{< include "task-tutorial-prereqs.md" >}}
 
-{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
+You must have access to create namespaces in your cluster.
 
 Each node in your cluster must have at least 1 GiB of memory.
 
 
-
-
 <!-- steps -->
 
 ## Create a namespace
@@ -38,7 +38,7 @@ kubectl create namespace quota-mem-cpu-example
 
 ## Create a ResourceQuota
 
-Here is the configuration file for a ResourceQuota object:
+Here is a manifest for an example ResourceQuota:
 
 {{< codenew file="admin/resource/quota-mem-cpu.yaml" >}}
 
@@ -56,15 +56,18 @@ kubectl get resourcequota mem-cpu-demo --namespace=quota-mem-cpu-example --outpu
 
 The ResourceQuota places these requirements on the quota-mem-cpu-example namespace:
 
-* Every Container must have a memory request, memory limit, cpu request, and cpu limit.
-* The memory request total for all Containers must not exceed 1 GiB.
-* The memory limit total for all Containers must not exceed 2 GiB.
-* The CPU request total for all Containers must not exceed 1 cpu.
-* The CPU limit total for all Containers must not exceed 2 cpu.
+* For every Pod in the namespace, each container must have a memory request, memory limit, cpu request, and cpu limit.
+* The memory request total for all Pods in that namespace must not exceed 1 GiB.
+* The memory limit total for all Pods in that namespace must not exceed 2 GiB.
+* The CPU request total for all Pods in that namespace must not exceed 1 cpu.
+* The CPU limit total for all Pods in that namespace must not exceed 2 cpu.
+
+See [meaning of CPU](/docs/concepts/configuration/manage-resources-containers/#meaning-of-cpu)
+to learn what Kubernetes means by “1 CPU”.
 
 ## Create a Pod
 
-Here is the configuration file for a Pod:
+Here is a manifest for an example Pod:
 
 {{< codenew file="admin/resource/quota-mem-cpu-pod.yaml" >}}
 
@@ -75,15 +78,15 @@ Create the Pod:
 kubectl apply -f https://k8s.io/examples/admin/resource/quota-mem-cpu-pod.yaml --namespace=quota-mem-cpu-example
 ```
 
-Verify that the Pod's Container is running:
+Verify that the Pod is running and that its (only) container is healthy:
 
-```
+```shell
 kubectl get pod quota-mem-cpu-demo --namespace=quota-mem-cpu-example
 ```
 
 Once again, view detailed information about the ResourceQuota:
 
-```
+```shell
 kubectl get resourcequota mem-cpu-demo --namespace=quota-mem-cpu-example --output=yaml
 ```
 
@@ -105,15 +108,22 @@ status:
     requests.memory: 600Mi
 ```
 
+If you have the `jq` tool, you can also query (using [JSONPath](/docs/reference/kubectl/jsonpath/))
+for just the `used` values, **and** pretty-print that that of the output. For example:
+
+```shell
+kubectl get resourcequota mem-cpu-demo --namespace=quota-mem-cpu-example -o jsonpath='{ .status.used }' | jq .
+```
+
 ## Attempt to create a second Pod
 
-Here is the configuration file for a second Pod:
+Here is a manifest for a second Pod:
 
 {{< codenew file="admin/resource/quota-mem-cpu-pod-2.yaml" >}}
 
-In the configuration file, you can see that the Pod has a memory request of 700 MiB.
+In the manifest, you can see that the Pod has a memory request of 700 MiB.
 Notice that the sum of the used memory request and this new memory
-request exceeds the memory request quota. 600 MiB + 700 MiB > 1 GiB.
+request exceeds the memory request quota: 600 MiB + 700 MiB > 1 GiB.
 
 Attempt to create the Pod:
 
@@ -133,11 +143,12 @@ requested: requests.memory=700Mi,used: requests.memory=600Mi, limited: requests.
 ## Discussion
 
 As you have seen in this exercise, you can use a ResourceQuota to restrict
-the memory request total for all Containers running in a namespace.
+the memory request total for all Pods running in a namespace.
 You can also restrict the totals for memory limit, cpu request, and cpu limit.
 
-If you want to restrict individual Containers, instead of totals for all Containers, use a
-[LimitRange](/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace/).
+Instead of managing total resource use within a namespace, you might want to restrict
+individual Pods, or the containers in those Pods. To achieve that kind of limiting, use a
+[LimitRange](/docs/concepts/policy/limit-range/).
 
 ## Clean up
 
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/quota-pod-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/quota-pod-namespace.md
index b0485f2b45..5db78858d5 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/quota-pod-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/quota-pod-namespace.md
@@ -8,8 +8,8 @@ weight: 60
 <!-- overview -->
 
 This page shows how to set a quota for the total number of Pods that can run
-in a namespace. You specify quotas in a
-[ResourceQuota](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#resourcequota-v1-core)
+in a {{< glossary_tooltip text="Namespace" term_id="namespace" >}}. You specify quotas in a
+[ResourceQuota](/docs/reference/kubernetes-api/policy-resources/resource-quota-v1/)
 object.
 
 
@@ -18,10 +18,9 @@ object.
 ## {{% heading "prerequisites" %}}
 
 
-{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
-
-
+{{< include "task-tutorial-prereqs.md" >}}
 
+You must have access to create namespaces in your cluster.
 
 <!-- steps -->
 
@@ -36,7 +35,7 @@ kubectl create namespace quota-pod-example
 
 ## Create a ResourceQuota
 
-Here is the configuration file for a ResourceQuota object:
+Here is an example manifest for a ResourceQuota:
 
 {{< codenew file="admin/resource/quota-pod.yaml" >}}
 
@@ -66,11 +65,12 @@ status:
     pods: "0"
 ```
 
-Here is the configuration file for a Deployment:
+Here is an example manifest for a {{< glossary_tooltip term_id="deployment" >}}:
 
 {{< codenew file="admin/resource/quota-pod-deployment.yaml" >}}
 
-In the configuration file, `replicas: 3` tells Kubernetes to attempt to create three Pods, all running the same application.
+In that manifest, `replicas: 3` tells Kubernetes to attempt to create three new Pods, all
+running the same application.
 
 Create the Deployment:
 
@@ -85,7 +85,7 @@ kubectl get deployment pod-quota-demo --namespace=quota-pod-example --output=yam
 ```
 
 The output shows that even though the Deployment specifies three replicas, only two
-Pods were created because of the quota.
+Pods were created because of the quota you defined earlier:
 
 ```yaml
 spec:
@@ -95,11 +95,18 @@ spec:
 status:
   availableReplicas: 2
 ...
-lastUpdateTime: 2017-07-07T20:57:05Z
+lastUpdateTime: 2021-04-02T20:57:05Z
     message: 'unable to create pods: pods "pod-quota-demo-1650323038-" is forbidden:
       exceeded quota: pod-demo, requested: pods=1, used: pods=2, limited: pods=2'
 ```
 
+### Choice of resource
+
+In this task you have defined a ResourceQuota that limited the total number of Pods, but
+you could also limit the total number of other kinds of object. For example, you
+might decide to limit how many {{< glossary_tooltip text="CronJobs" term_id="cronjob" >}}
+that can live in a single namespace.
+
 ## Clean up
 
 Delete your namespace:

From 3dd1eb11213f7224d3ee1db68e3e0fb6e244169f Mon Sep 17 00:00:00 2001
From: Tim Bannister <tim@scalefactory.com>
Date: Tue, 12 Oct 2021 23:35:07 +0100
Subject: [PATCH 2/2] Add descriptions to tasks

---
 .../manage-resources/cpu-constraint-namespace.md               | 3 +++
 .../manage-resources/cpu-default-namespace.md                  | 3 +++
 .../manage-resources/memory-constraint-namespace.md            | 3 +++
 .../manage-resources/memory-default-namespace.md               | 3 +++
 .../manage-resources/quota-memory-cpu-namespace.md             | 2 ++
 .../administer-cluster/manage-resources/quota-pod-namespace.md | 2 ++
 6 files changed, 16 insertions(+)

diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md
index d640195efc..bb472ed647 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/cpu-constraint-namespace.md
@@ -2,6 +2,9 @@
 title: Configure Minimum and Maximum CPU Constraints for a Namespace
 content_type: task
 weight: 40
+description: >-
+  Define a range of valid CPU resource limits for a namespace, so that every new Pod
+  in that namespace falls within the range you configure.
 ---
 
 
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace.md
index d58baca108..14d50aa4d7 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/cpu-default-namespace.md
@@ -2,6 +2,9 @@
 title: Configure Default CPU Requests and Limits for a Namespace
 content_type: task
 weight: 20
+description: >-
+  Define a default CPU resource limits for a namespace, so that every new Pod
+  in that namespace has a CPU resource limit configured.
 ---
 
 <!-- overview -->
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md
index 8db50fb4d1..3efd899075 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md
@@ -2,6 +2,9 @@
 title: Configure Minimum and Maximum Memory Constraints for a Namespace
 content_type: task
 weight: 30
+description: >-
+  Define a range of valid memory resource limits for a namespace, so that every new Pod
+  in that namespace falls within the range you configure.
 ---
 
 
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md
index 1d0fb3eb05..ff2a4082c2 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/memory-default-namespace.md
@@ -2,6 +2,9 @@
 title: Configure Default Memory Requests and Limits for a Namespace
 content_type: task
 weight: 10
+description: >-
+  Define a default memory resource limit for a namespace, so that every new Pod
+  in that namespace has a memory resource limit configured.
 ---
 
 <!-- overview -->
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace.md
index 290cac909f..161c3a12a9 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/quota-memory-cpu-namespace.md
@@ -2,6 +2,8 @@
 title: Configure Memory and CPU Quotas for a Namespace
 content_type: task
 weight: 50
+description: >-
+  Define overall memory and CPU resource limits for a namespace.
 ---
 
 
diff --git a/content/en/docs/tasks/administer-cluster/manage-resources/quota-pod-namespace.md b/content/en/docs/tasks/administer-cluster/manage-resources/quota-pod-namespace.md
index 5db78858d5..3cdb1a9f24 100644
--- a/content/en/docs/tasks/administer-cluster/manage-resources/quota-pod-namespace.md
+++ b/content/en/docs/tasks/administer-cluster/manage-resources/quota-pod-namespace.md
@@ -2,6 +2,8 @@
 title: Configure a Pod Quota for a Namespace
 content_type: task
 weight: 60
+description: >-
+  Restrict how many Pods you can create within a namespace.
 ---