OCPBUGS-33247: Improving QoS pod based on docfooding feedback

modules/cnf-node-tuning-operator-creating-pod-with-guaranteed-qos-class.adoc

@@ -6,13 +6,51 @@
 [id="cnf-node-tuning-operator-creating-pod-with-guaranteed-qos-class_{context}"]
 = Creating a pod with a guaranteed QoS class
 
-Keep the following in mind when you create a pod that is given a QoS class of `Guaranteed`:
+You can create a pod with a quality of service (QoS) class of `Guaranteed` for high-performance workloads. Configuring a pod with a QoS class of `Guaranteed` ensures that the pod has priority access to the specified CPU and memory resources. 
 
-* Every container in the pod must have a memory limit and a memory request, and they must be the same.
-* Every container in the pod must have a CPU limit and a CPU request, and they must be the same.
+To create a pod with QoS class of `Guaranteed`, you must apply the following specifications:
 
-The following example shows the configuration file for a pod that has one container. The container has a memory limit and a memory request, both equal to 200 MiB. The container has a CPU limit and a CPU request, both equal to 1 CPU.
+* Set identical values for the memory limit and memory request fields for each container in the pod.
+* Set identical values for CPU limit and CPU request fields for each container in the pod.
 
+[NOTE]
+====
+A pod with a QoS class of `Guaranteed` cannot use resources beyond the specified limits.
+====
+
+The pod will not be evicted from a node unless one of the following criteria is met:
+
+* During resource contention on a node, there are no lower-priority pods that can be evicted.
+* The pod exceeds the CPU or memory limits.
+
+.Prerequisites
+
+* Access to the cluster as a user with the `cluster-admin` role.
+
+* The OpenShift CLI (`oc`) installed.
+
+.Procedure
+
+. Create a namespace for the pod by running the following command:
++
+[source,terminal]
+----
+$ oc create namespace qos-example <1>
+----
+<1> This example uses the `qos-example` namespace.
++
+.Example output
+[source,terminal]
+----
+namespace/qos-example created
+----
+
+. Create the `Pod` resource:
+
+.. Create a YAML file the defines the `Pod` resource:
++
+--
+.Example `qos-example.yaml` file
 [source,yaml]
 ----
 apiVersion: v1
@@ -27,45 +65,56 @@ spec:
       type: RuntimeDefault
   containers:
   - name: qos-demo-ctr
-    image: <image-pull-spec>
+    image: quay.io/openshifttest/hello-openshift:openshift <1>
     resources:
       limits:
-        memory: "200Mi"
-        cpu: "1"
+        memory: "200Mi" <2>
+        cpu: "1" <3>
       requests:
-        memory: "200Mi"
-        cpu: "1"
+        memory: "200Mi" <4>
+        cpu: "1" <5>
     securityContext:
       allowPrivilegeEscalation: false
       capabilities:
         drop: [ALL]
 ----
+<1> This example uses a public `hello-openshift` image. Replace with the image that you want to use for your workload.
+<2> This example sets the memory limit to 200MB.
+<3> This example sets the CPU limit to one CPU.
+<4> This example sets the memory request to 200MB.
+<5> This example sets the CPU request to one CPU.
++
+[NOTE]
+====
+If you specify a memory limit for a container, but do not specify a memory request, {product-title} automatically assigns a memory request that matches the limit. Similarly, if you specify a CPU limit for a container, but do not specify a CPU request, {product-title} automatically assigns a CPU request that matches the limit.
+====
+--
 
-. Create the pod:
+.. Create the `Pod` resource by running the following command:
++
+[source,terminal]
+----
+$ oc apply -f qos-example.yaml --namespace=qos-example
+----
 +
+.Example output
 [source,terminal]
 ----
-$ oc  apply -f qos-pod.yaml --namespace=qos-example
+pod/qos-demo created
 ----
 
-. View detailed information about the pod:
+.Verification
+
+* View the `qosClass` value for the pod by running the following command:
 +
 [source,terminal]
 ----
-$ oc get pod qos-demo --namespace=qos-example --output=yaml
+$ oc get pod qos-demo --namespace=qos-example --output=yaml | grep qosClass
 ----
 +
 .Example output
 [source,yaml]
 ----
-spec:
-  containers:
-    ...
-status:
-  qosClass: Guaranteed
+    qosClass: Guaranteed
 ----
-+
-[NOTE]
-====
-If you specify a memory limit for a container, but do not specify a memory request, {product-title} automatically assigns a memory request that matches the limit. Similarly, if you specify a CPU limit for a container, but do not specify a CPU request, {product-title} automatically assigns a CPU request that matches the limit.
-====
+