Tidy resource management task pages

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

Author: Tim Bannister

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,23 +75,23 @@ 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
 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:
 

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:
+
+* 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:
 
-* 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.
+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