Nodes Clusters docs fixes during ROSA review

Michael Burke · Michael Burke · commit 766a2cd0490c · 2023-08-11T09:25:41.000-04:00
diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml
@@ -2393,6 +2393,9 @@ Topics:
   - Name: Analyzing cluster resource levels
     File: nodes-cluster-resource-levels
     Distros: openshift-enterprise,openshift-origin
+  - Name: Configuring a cluster for pods
+    File: nodes-cluster-pods-configuring
+    Distros: openshift-enterprise,openshift-origin
   - Name: Setting limit ranges
     File: nodes-cluster-limit-ranges
   - Name: Configuring cluster memory to meet container memory and risk requirements
diff --git a/modules/node-tuning-operator-supported-tuned-daemon-plug-ins.adoc b/modules/node-tuning-operator-supported-tuned-daemon-plug-ins.adoc
@@ -2,6 +2,7 @@
 //
 // * scalability_and_performance/using-node-tuning-operator.adoc
 // * post_installation_configuration/node-tasks.adoc
+// * nodes/nodes/nodes-node-tuning-operator
 
 [id="supported-tuned-daemon-plug-ins_{context}"]
 = Supported TuneD daemon plugins
@@ -38,8 +39,8 @@ that is not supported. The following TuneD plugins are currently not supported:
 The TuneD bootloader plugin is currently supported on {op-system-first} 8.x worker nodes. For {op-system-base-full} 7.x worker nodes, the TuneD bootloader plugin is currently not supported.
 ====
 
-See
-link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/customizing-tuned-profiles_monitoring-and-managing-system-status-and-performance#available-tuned-plug-ins_customizing-tuned-profiles[Available
-TuneD Plugins] and
-link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/getting-started-with-tuned_monitoring-and-managing-system-status-and-performance[Getting
-Started with TuneD] for more information.
+.Additional references
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/customizing-tuned-profiles_monitoring-and-managing-system-status-and-performance#available-tuned-plug-ins_customizing-tuned-profiles[Available TuneD Plugins]
+
+* link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/monitoring_and_managing_system_status_and_performance/getting-started-with-tuned_monitoring-and-managing-system-status-and-performance[Getting Started with TuneD]
diff --git a/modules/nodes-cluster-limit-ranges-creating.adoc b/modules/nodes-cluster-limit-ranges-creating.adoc
@@ -64,6 +64,7 @@ spec:
 
 . Create the object:
 +
+[source,terminal]
 ----
 $ oc create -f <limit_range_file> -n <project> <1>
 ----
diff --git a/modules/nodes-cluster-limit-ranges-deleting.adoc b/modules/nodes-cluster-limit-ranges-deleting.adoc
@@ -8,8 +8,9 @@
 
 To remove any active `LimitRange` object to no longer enforce the limits in a project:
 
-. Run the following command:
+* Run the following command:
 +
+[source,terminal]
 ----
 $ oc delete limits <limit_name>
 ----
diff --git a/modules/nodes-cluster-limit-ranges-viewing.adoc b/modules/nodes-cluster-limit-ranges-viewing.adoc
@@ -13,10 +13,12 @@ You can also use the CLI to view limit range details:
 . Get the list of `LimitRange` object defined in the project. For example, for a
 project called *demoproject*:
 +
+[source,terminal]
 ----
 $ oc get limits -n demoproject
 ----
 +
+[source,terminal]
 ----
 NAME              CREATED AT
 resource-limits   2020-07-15T17:14:23Z
@@ -25,10 +27,14 @@ resource-limits   2020-07-15T17:14:23Z
 . Describe the `LimitRange` object you are interested in, for example the
 `resource-limits` limit range:
 +
+
+[source,terminal]
 ----
 $ oc describe limits resource-limits -n demoproject
 ----
 +
+
+[source,terminal]
 ----
 Name:                           resource-limits
 Namespace:                      demoproject
diff --git a/modules/nodes-cluster-overcommit-node-enforcing.adoc b/modules/nodes-cluster-overcommit-node-enforcing.adoc
@@ -18,7 +18,7 @@ If you disable CPU limit enforcement, it is important to understand the impact o
 
 .Prerequisites
 
-. Obtain the label associated with the static `MachineConfigPool` CRD for the type of node you want to configure by entering the following command:
+* Obtain the label associated with the static `MachineConfigPool` CRD for the type of node you want to configure by entering the following command:
 +
 [source,terminal]
 ----
@@ -50,6 +50,7 @@ metadata:
 ====
 If the label is not present, add a key/value pair such as:
 
+[source,terminal]
 ----
 $ oc label machineconfigpool worker custom-kubelet=small-pods
 ----
diff --git a/modules/nodes-cluster-overcommit-project-disable.adoc b/modules/nodes-cluster-overcommit-project-disable.adoc
@@ -7,25 +7,21 @@
 [id="nodes-cluster-overcommit-project-disable_{context}"]
 = Disabling overcommitment for a project
 
-When enabled, overcommitment can be disabled per-project.
-For example, you can allow infrastructure components to be configured independently of overcommitment.
+When enabled, overcommitment can be disabled per-project. For example, you can allow infrastructure components to be configured independently of overcommitment.
 
 .Procedure
 
 To disable overcommitment in a project:
 
-. Edit the project object file
-
-. Add the following annotation:
+. Edit the namespace object to add the following annotation:
 +
 [source,yaml]
 ----
-quota.openshift.io/cluster-resource-override-enabled: "false"
-----
-
-. Create the project object:
-+
-[source,terminal]
-----
-$ oc create -f <file-name>.yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  annotations:
+    quota.openshift.io/cluster-resource-override-enabled: "false" <1>
+# ...
 ----
+<1> Setting this annotation to `false` disables overcommit for this namespace.
diff --git a/modules/nodes-cluster-resource-configure-jdk.adoc b/modules/nodes-cluster-resource-configure-jdk.adoc
@@ -36,7 +36,7 @@ override this behavior, especially if a container memory limit is also set.
 
 There are at least two ways the above can be achieved:
 
-. If the container memory limit is set and the experimental options are
+* If the container memory limit is set and the experimental options are
    supported by the JVM, set `-XX:+UnlockExperimentalVMOptions
    -XX:+UseCGroupMemoryLimitForHeap`.
 +
@@ -48,7 +48,7 @@ The `UseCGroupMemoryLimitForHeap` option has been removed in JDK 11. Use `-XX:+U
 This sets `-XX:MaxRAM` to the container memory limit, and the maximum heap size
 (`-XX:MaxHeapSize` / `-Xmx`) to 1/`-XX:MaxRAMFraction` (1/4 by default).
 
-. Directly override one of `-XX:MaxRAM`, `-XX:MaxHeapSize` or `-Xmx`.
+* Directly override one of `-XX:MaxRAM`, `-XX:MaxHeapSize` or `-Xmx`.
 +
 This option involves hard-coding a value, but has the advantage of allowing a
 safety margin to be calculated.
diff --git a/modules/nodes-cluster-resource-configure-oom.adoc b/modules/nodes-cluster-resource-configure-oom.adoc
@@ -32,6 +32,11 @@ follows:
 [source,terminal]
 ----
 $ grep '^oom_kill ' /sys/fs/cgroup/memory/memory.oom_control
+----
++
+.Example output
+[source,terminal]
+----
 oom_kill 0
 ----
 
@@ -68,6 +73,11 @@ The `137` code indicates the container process exited with code 137, indicating
 [source,terminal]
 ----
 $ grep '^oom_kill ' /sys/fs/cgroup/memory/memory.oom_control
+----
++
+.Example output
+[source,terminal]
+----
 oom_kill 1
 ----
 +
diff --git a/modules/nodes-cluster-resource-configure-request-limit.adoc b/modules/nodes-cluster-resource-configure-request-limit.adoc
@@ -12,6 +12,8 @@ within a pod should use the Downward API.
 .Procedure
 
 . Configure the pod to add the `MEMORY_REQUEST` and `MEMORY_LIMIT` stanzas:
+
+.. Create a YAML file similar to the following:
 +
 [source,yaml]
 ----
@@ -46,13 +48,15 @@ spec:
 <1> Add this stanza to discover the application memory request value.
 <2> Add this stanza to discover the application memory limit value.
 
-. Create the pod:
+.. Create the pod by running the following command:
 +
 [source,terminal]
 ----
 $ oc create -f <file-name>.yaml
 ----
 
+.Verification
+
 . Access the pod using a remote shell:
 +
 [source,terminal]
diff --git a/modules/nodes-cluster-resource-configure.adoc b/modules/nodes-cluster-resource-configure.adoc
@@ -34,6 +34,7 @@ spec:
       memoryRequestToLimitPercent: 50 <1>
       cpuRequestToLimitPercent: 25 <2>
       limitCPUToMemoryPercent: 200 <3>
+# ...
 ----
 <1> Optional. Specify the percentage to override the container memory limit, if used, between 1-100. The default is 50.
 <2> Optional. Specify the percentage to override the container CPU limit, if used, between 1-100. The default is 25.
@@ -47,11 +48,11 @@ apiVersion: v1
 kind: Namespace
 metadata:
 
- ...
+# ...
 
   labels:
     clusterresourceoverrides.admission.autoscaling.openshift.io/enabled: "true" <1>
 
- ...
+# ...
 ----
 <1> Add this label to each project.
diff --git a/modules/nodes-cluster-resource-levels-about.adoc b/modules/nodes-cluster-resource-levels-about.adoc
@@ -4,9 +4,9 @@
 
 :_content-type: CONCEPT
 [id="nodes-cluster-resource-levels-about_{context}"]
-= Understanding the {product-title} cluster capacity tool 
+= Understanding the OpenShift Cluster Capacity Tool
 
-The cluster capacity tool simulates a sequence of scheduling decisions to
+The OpenShift Cluster Capacity Tool simulates a sequence of scheduling decisions to
 determine how many instances of an input pod can be scheduled on the cluster
 before it is exhausted of resources to provide a more accurate estimation.
 
@@ -23,6 +23,6 @@ on its selection and affinity criteria. As a result, the estimation of which
 remaining pods a cluster can schedule can be difficult.
 ====
 
-You can run the cluster capacity analysis tool as a stand-alone utility from 
+You can run the OpenShift Cluster Capacity Tool as a stand-alone utility from 
 the command line, or as a job in a pod inside an {product-title} cluster. 
-Running it as job inside of a pod enables you to run it multiple times without intervention.
+Running the tool as job inside of a pod enables you to run it multiple times without intervention.
diff --git a/modules/nodes-cluster-resource-levels-command.adoc b/modules/nodes-cluster-resource-levels-command.adoc
@@ -4,20 +4,22 @@
 
 :_content-type: PROCEDURE
 [id="nodes-cluster-resource-levels-command_{context}"]
-= Running the cluster capacity tool on the command line
+= Running the OpenShift Cluster Capacity Tool on the command line
 
-You can run the {product-title} cluster capacity tool from the command line
+You can run the OpenShift Cluster Capacity Tool from the command line
 to estimate the number of pods that can be scheduled onto your cluster.
 
+You create a sample pod spec file, which the tool uses for estimating resource usage. The pod spec specifies its resource
+requirements as `limits` or `requests`. The cluster capacity tool takes the
+pod's resource requirements into account for its estimation analysis.
+
 .Prerequisites
 
-* Run the link:https://catalog.redhat.com/software/containers/openshift4/ose-cluster-capacity/5cca0324d70cc57c44ae8eb6?container-tabs=overview[OpenShift Cluster Capacity Tool], which is available as a container image from the Red Hat Ecosystem Catalog.
+. Run the link:https://catalog.redhat.com/software/containers/openshift4/ose-cluster-capacity/5cca0324d70cc57c44ae8eb6?container-tabs=overview[OpenShift Cluster Capacity Tool], which is available as a container image from the Red Hat Ecosystem Catalog.
 
-* Create a sample `Pod` spec file, which the tool uses for estimating resource usage. The `podspec` specifies its resource
-requirements as `limits` or `requests`. The cluster capacity tool takes the
-pod's resource requirements into account for its estimation analysis.
-+
-An example of the `Pod` spec input is:
+. Create a sample pod spec file:
+
+.. Create a YAML file similar to the following:
 +
 [source,yaml]
 ----
@@ -42,6 +44,18 @@ spec:
         memory: 100Mi
 ----
 
+.. Create the cluster role:
++
+[source,terminal]
+----
+$ oc create -f <file_name>.yaml
+----
+For example:
++
+[source,terminal]
+----
+$ oc create -f pod-spec.yaml
+----
 
 .Procedure
 
@@ -66,10 +80,17 @@ $ podman pull registry.redhat.io/openshift4/ose-cluster-capacity
 [source,terminal]
 ----
 $ podman run -v $HOME/.kube:/kube:Z -v $(pwd):/cc:Z  ose-cluster-capacity \
-/bin/cluster-capacity --kubeconfig /kube/config --podspec /cc/pod-spec.yaml \
---verbose <1>
+/bin/cluster-capacity --kubeconfig /kube/config --<pod_spec>.yaml /cc/<pod_spec>.yaml \
+--verbose
 ----
-<1> You can also add the `--verbose` option to output a detailed description of how many pods can be scheduled on each node in the cluster.
++
+--
+where:
+
+<pod_spec>.yaml:: Specifies the pod spec to use.
+
+verbose:: Outputs a detailed description of how many pods can be scheduled on each node in the cluster.
+--
 +
 .Example output
 [source,terminal]
diff --git a/modules/nodes-cluster-resource-levels-job.adoc b/modules/nodes-cluster-resource-levels-job.adoc
diff --git a/modules/nodes-cluster-resource-override-deploy-cli.adoc b/modules/nodes-cluster-resource-override-deploy-cli.adoc
diff --git a/modules/nodes-cluster-resource-override-deploy-console.adoc b/modules/nodes-cluster-resource-override-deploy-console.adoc
diff --git a/modules/nodes-cluster-resource-override.adoc b/modules/nodes-cluster-resource-override.adoc
diff --git a/nodes/clusters/nodes-cluster-resource-levels.adoc b/nodes/clusters/nodes-cluster-resource-levels.adoc
diff --git a/nodes/nodes/nodes-nodes-machine-config-daemon-metrics.adoc b/nodes/nodes/nodes-nodes-machine-config-daemon-metrics.adoc

Original file line number	Diff line number	Diff line change
`@@ -64,6 +64,7 @@ spec:`
`64`	`64`
`65`	`65`	`. Create the object:`
`66`	`66`	`+`
	`67`	`+[source,terminal]`
`67`	`68`	`----`
`68`	`69`	`$ oc create -f <limit_range_file> -n <project> <1>`
`69`	`70`	`----`
Original file line number	Diff line number	Diff line change
`@@ -8,8 +8,9 @@`
`8`	`8`
`9`	`9`	To remove any active `LimitRange` object to no longer enforce the limits in a project:
`10`	`10`
`11`		`-. Run the following command:`
	`11`	`+* Run the following command:`
`12`	`12`	`+`
	`13`	`+[source,terminal]`
`13`	`14`	`----`
`14`	`15`	`$ oc delete limits <limit_name>`
`15`	`16`	`----`
Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ override this behavior, especially if a container memory limit is also set.`
`36`	`36`
`37`	`37`	`There are at least two ways the above can be achieved:`
`38`	`38`
`39`		`-. If the container memory limit is set and the experimental options are`
	`39`	`+* If the container memory limit is set and the experimental options are`
`40`	`40`	supported by the JVM, set `-XX:+UnlockExperimentalVMOptions
`41`	`41`	-XX:+UseCGroupMemoryLimitForHeap`.
`42`	`42`	`+`
@@ -48,7 +48,7 @@ The `UseCGroupMemoryLimitForHeap` option has been removed in JDK 11. Use `-XX:+U
`48`	`48`	This sets `-XX:MaxRAM` to the container memory limit, and the maximum heap size
`49`	`49`	(`-XX:MaxHeapSize` / `-Xmx`) to 1/`-XX:MaxRAMFraction` (1/4 by default).
`50`	`50`
`51`		-. Directly override one of `-XX:MaxRAM`, `-XX:MaxHeapSize` or `-Xmx`.
	`51`	+* Directly override one of `-XX:MaxRAM`, `-XX:MaxHeapSize` or `-Xmx`.
`52`	`52`	`+`
`53`	`53`	`This option involves hard-coding a value, but has the advantage of allowing a`
`54`	`54`	`safety margin to be calculated.`