[OSDOCS#18748]: CQA support book for 4.20

_attributes/attributes-openshift-dedicated.adoc

@@ -33,6 +33,8 @@
 :sts-first: Security Token Service (STS)
 :sts-full: Security Token Service
 :sts-short: STS
+:insights-operator: Insights Operator
+:red-hat-lightspeed: Red{nbsp}Hat Lightspeed
 //logging
 :logging-title: logging for Red Hat OpenShift
 :logging-title-uc: Logging for Red Hat OpenShift

modules/about-crio.adoc

@@ -8,4 +8,5 @@
 
 include::snippets/about-crio-snippet.adoc[]
 
+[role="_abstract"]
 When container runtime issues occur, verify the status of the `crio` systemd service on each node. Gather CRI-O journald unit logs from nodes that have container runtime issues.

modules/about-must-gather.adoc

@@ -11,7 +11,10 @@
 [id="about-must-gather_{context}"]
 = About the must-gather tool
 
-The `oc adm must-gather` CLI command collects the information from your cluster that is most likely needed for debugging issues, including:
+[role="_abstract"]
+The `oc adm must-gather` CLI command collects the information from your cluster that is most likely needed for debugging issues.
+
+This includes:
 
 * Resource definitions
 * Service logs

modules/about-sosreport.adoc

@@ -6,6 +6,7 @@
 [id="about-sosreport_{context}"]
 = About sosreport
 
+[role="_abstract"]
 `sosreport` is a tool that collects configuration details, system information, and diagnostic data from {op-system-base-full} and {op-system-first} systems. `sosreport` provides a standardized way to collect diagnostic information relating to a node, which can then be provided to Red Hat Support for issue diagnosis.
 
 In some support interactions, Red Hat Support may ask you to collect a `sosreport` archive for a specific {product-title} node. For example, it might sometimes be necessary to review system logs or other node-specific data that is not included within the output of `oc adm must-gather`.

modules/about-toolbox.adoc

@@ -6,6 +6,7 @@
 [id="about-toolbox_{context}"]
 = About `toolbox`
 
+[role="_abstract"]
 ifndef::openshift-origin[]
 `toolbox` is a tool that starts a container on a {op-system-first} system. The tool is primarily used to start a container that includes the required binaries and plugins that are needed to run commands such as `sosreport`.
 

modules/accessing-running-pods.adoc

@@ -6,6 +6,7 @@
 [id="accessing-running-pods_{context}"]
 = Accessing running pods
 
+[role="_abstract"]
 You can review running pods dynamically by opening a shell inside a pod or by gaining network access through port forwarding.
 
 .Prerequisites
@@ -32,9 +33,12 @@ $ oc project <namespace>
 +
 [source,terminal]
 ----
-$ oc rsh <pod_name>  <1>
+$ oc rsh <pod_name>
 ----
-<1> If a pod has multiple containers, `oc rsh` defaults to the first container unless `-c <container_name>` is specified.
++
+where:
+
+`<pod_name>`:: If a pod has multiple containers, `oc rsh` defaults to the first container unless `-c <container_name>` is specified.
 
 . Start a remote shell into a specific container within a pod:
 +
@@ -47,6 +51,9 @@ $ oc rsh -c <container_name> pod/<pod_name>
 +
 [source,terminal]
 ----
-$ oc port-forward <pod_name> <host_port>:<pod_port>  <1>
+$ oc port-forward <pod_name> <host_port>:<pod_port>
 ----
-<1> Enter `Ctrl+C` to cancel the port forwarding session.
++
+where:
+
+`<pod_name> <host_port>:<pod_port>`:: Enter `Ctrl+C` to cancel the port forwarding session.

modules/accessing-windows-node-using-rdp.adoc

@@ -7,6 +7,7 @@
 [id="accessing-windows-node-using-rdp_{context}"]
 = Accessing a Windows node using RDP
 
+[role="_abstract"]
 You can access a Windows node by using a Remote Desktop Protocol (RDP).
 
 .Prerequisites
@@ -42,4 +43,4 @@ $ oc get nodes <node_name> -o jsonpath={.status.addresses[?\(@.type==\"InternalI
 C:\> net user <username> *
 ----
 +
-Specify the cloud provider user name, such as `Administrator` for AWS or `capi` for Azure. You can now remotely access the Windows node at `localhost:2020` using an RDP client.
+Specify the cloud provider user name, such as `Administrator` for AWS or `capi` for Azure. You can now remotely access the Windows node at `localhost:2020` by using an RDP client.

modules/accessing-windows-node-using-ssh.adoc

@@ -7,6 +7,7 @@
 [id="accessing-windows-node-using-ssh_{context}"]
 = Accessing a Windows node using SSH
 
+[role="_abstract"]
 You can access a Windows node by using a secure shell (SSH).
 
 .Prerequisites

modules/checking-load-balancer-configuration.adoc

@@ -6,7 +6,8 @@
 [id="checking-load-balancer-configuration_{context}"]
 = Checking a load balancer configuration before {product-title} installation
 
-Check your load balancer configuration prior to starting an {product-title} installation.
+[role="_abstract"]
+Check your load balancer configuration before starting an {product-title} installation.
 
 .Prerequisites
 

modules/cleaning-crio-storage.adoc

@@ -7,16 +7,17 @@
 
 = Cleaning CRI-O storage
 
+[role="_abstract"]
 You can manually clear the CRI-O ephemeral storage if you experience the following issues:
 
-* A node cannot run any pods and this error appears:
+* A node cannot run any pods and this error is displayed:
 [source,terminal]
 +
 ----
 Failed to create pod sandbox: rpc error: code = Unknown desc = failed to mount container XXX: error recreating the missing symlinks: error reading name of symlink for XXX: open /var/lib/containers/storage/overlay/XXX/link: no such file or directory
 ----
 +
-* You cannot create a new container on a working node and the  “can’t stat lower layer” error appears:
+* You cannot create a new container on a working node and the  “can’t stat lower layer” error is displayed:
 [source,terminal]
 +
 ----

modules/cluster-resources.adoc

@@ -3,7 +3,7 @@
 = Interacting with your cluster resources
 
 [role="_abstract"]
-You can use the {oc-first} tool to interact with and edit cluster resources in {product-title} to manage your cluster configuration.
+To view and edit the global configuration of your {product-title} cluster, use the {oc-first} to query and change cluster resources.
 
 .Prerequisites
 
@@ -17,7 +17,7 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 
 .Procedure
 
-. To see which configuration Operators have been applied, run the following command:
+. To check which configuration Operators apply to your cluster, run the following command:
 +
 [source,terminal]
 ----

modules/collecting-containerd-logs-windows.adoc

@@ -7,6 +7,7 @@
 [id="collecting-docker-logs-windows_{context}"]
 = Collecting containerd logs for Windows containers
 
+[role="_abstract"]
 The Windows containerd container service does not stream log data to stdout, but instead, it stream log data to the Windows event log. You can view the containerd event logs to investigate issues you think might be caused by the Windows containerd container service.
 
 .Prerequisites

modules/collecting-kube-node-logs-windows.adoc

@@ -7,6 +7,7 @@
 [id="collecting-kube-node-logs-windows_{context}"]
 = Collecting Kubernetes node logs for Windows containers
 
+[role="_abstract"]
 Windows container logging works differently from Linux container logging; the Kubernetes node logs for Windows workloads are streamed to the `C:\var\logs` directory by default. Therefore, you must gather the Windows node logs from that directory.
 
 .Prerequisites

modules/collecting-windows-application-event-logs.adoc

@@ -7,6 +7,7 @@
 [id="collecting-windows-application-event-logs_{context}"]
 = Collecting Windows application event logs
 
+[role="_abstract"]
 The `Get-WinEvent` shim on the kubelet `logs` endpoint can be used to collect application event logs from Windows machines.
 
 .Prerequisites

modules/configuring-ovnk-use-second-ovs-bridge.adoc

@@ -237,10 +237,15 @@ spec:
           mode: 0420
           overwrite: true
           contents:
-            source: data:text/plain;charset=utf-8,bond0 <1>
+            source: data:text/plain;charset=utf-8,bond0
           filesystem: root
 ----
-<1> Ensure `bond0` exists on the node before you apply the machine configuration file to the node.
++
+where:
++
+--
+* Ensure `bond0` exists on the node before you apply the machine configuration file to the node.
+--
 +
 .. Before you apply the configuration to all new nodes in your cluster, reboot the host node to verify that `br-ex` selects the intended interface and does not conflict with the new interfaces that you defined on `br-ex1`.
 +

modules/configuring-ovs-log-level-permanently.adoc

@@ -6,6 +6,7 @@
 [id="configuring-ovs-log-level-permanently_{context}"]
 = Configuring the Open vSwitch log level permanently
 
+[role="_abstract"]
 For long-term changes to the Open vSwitch (OVS) log level, you can change the log level permanently.
 
 .Prerequisites
@@ -24,7 +25,7 @@ apiVersion: machineconfiguration.openshift.io/v1
 kind: MachineConfig
 metadata:
   labels:
-    machineconfiguration.openshift.io/role: master  <1>
+    machineconfiguration.openshift.io/role: master
   name: 99-change-ovs-loglevel
 spec:
   config:
@@ -35,13 +36,16 @@ spec:
       - dropins:
         - contents: |
             [Service]
-              ExecStartPost=-/usr/bin/ovs-appctl vlog/set syslog:dbg  <2>
+              ExecStartPost=-/usr/bin/ovs-appctl vlog/set syslog:dbg
               ExecReload=-/usr/bin/ovs-appctl vlog/set syslog:dbg
           name: 20-ovs-vswitchd-restart.conf
         name: ovs-vswitchd.service
 ----
-<1> After you perform this procedure to configure control plane nodes, repeat the procedure and set the role to `worker` to configure worker nodes.
-<2> Set the `syslog:<log_level>` value. Log levels are `off`, `emer`, `err`, `warn`, `info`, or `dbg`. Setting the value to `off` filters out all log messages.
++
+where:
+
+`metadata.labels.machineconfiguration.openshift.io/role`:: After you perform this procedure to configure control plane nodes, repeat the procedure and set the role to `worker` to configure worker nodes.
+`spec.systemmd.units.dropins.contents.ExecStartPost`:: Set the `syslog:<log_level>` value. Log levels are `off`, `emer`, `err`, `warn`, `info`, or `dbg`. Setting the value to `off` filters out all log messages.
 
 . Apply the machine config:
 +

modules/configuring-ovs-log-level-temp.adoc

@@ -2,7 +2,9 @@
 [id="configuring-ovs-log-level-temp_{context}"]
 = Configuring the Open vSwitch log level temporarily
 
+[role="_abstract"]
 For short-term troubleshooting, you can configure the Open vSwitch (OVS) log level temporarily.
+
 The following procedure does not require rebooting the node.
 In addition, the configuration change does not persist whenever you reboot the node.
 

modules/copying-files-pods-and-containers.adoc

@@ -6,6 +6,7 @@
 [id="copying-files-pods-and-containers_{context}"]
 = Copying files to and from pods and containers
 
+[role="_abstract"]
 You can copy files to and from a pod to test configuration changes or gather diagnostic information.
 
 .Prerequisites
@@ -25,17 +26,19 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
 +
 [source,terminal]
 ----
-$ oc cp <local_path> <pod_name>:/<path> -c <container_name>  <1>
+$ oc cp <local_path> <pod_name>:/<path> -c <container_name>
 ----
-<1> The first container in a pod is selected if the `-c` option is not specified.
++
+`-c <container_name>` refers to the desired container in a pod. If you do not specify a container with the `-c` option, then the first container in a pod is selected.
 
 . Copy a file from a pod:
 +
 [source,terminal]
 ----
-$ oc cp <pod_name>:/<path>  -c <container_name> <local_path>  <1>
+$ oc cp <pod_name>:/<path> -c <container_name> <local_path>
 ----
-<1> The first container in a pod is selected if the `-c` option is not specified.
++
+`-c <container_name>` refers to the desired container in a pod. If you do not specify a container with the `-c` option, then the first container in a pod is selected.
 +
 [NOTE]
 ====

modules/determining-where-installation-issues-occur.adoc

@@ -6,6 +6,7 @@
 [id="determining-where-installation-issues-occur_{context}"]
 = Determining where installation issues occur
 
+[role="_abstract"]
 When troubleshooting {product-title} installation issues, you can monitor installation logs to determine at which stage issues occur. Then, retrieve diagnostic data relevant to that stage.
 
 {product-title} installation proceeds through the following stages:

modules/disabling-insights-operator-alerts.adoc

@@ -57,5 +57,5 @@ data:
 . Click *Save*. The `insights-config` ConfigMap details page opens.
 
 . Verify that the value of the `config.yaml` `alerting` attribute is set to `disabled: true`.
-
++
 After you save the changes, {insights-operator} no longer sends alerts to the cluster Prometheus instance.

modules/displaying-ovs-logs.adoc

@@ -2,6 +2,7 @@
 [id="displaying-ovs-logs_{context}"]
 = Displaying Open vSwitch logs
 
+[role="_abstract"]
 Use the following procedure to display Open vSwitch (OVS) logs.
 
 .Prerequisites

modules/displaying-the-insights-status-in-the-web-console.adoc

@@ -5,20 +5,27 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="displaying-the-insights-status-in-the-web-console_{context}"]
-= Displaying the {red-hat-lightspeed} status in the web console
+= Displaying the {red-hat-lightspeed} advisor status in the web console
 
-{red-hat-lightspeed} repeatedly analyzes your cluster and you can display the status of identified potential issues of your cluster in the {product-title} web console. This status shows the number of issues in the different categories and, for further details, links to the reports in {cluster-manager-url}.
+[role="_abstract"]
+View the health status of your cluster and potential issues identified by the {red-hat-lightspeed} advisor service in the {product-title} web console. Issues are grouped by risk category with links to detailed reports in the {hybrid-console-second}.
 
 .Prerequisites
 
-* Your cluster is registered in {cluster-manager-url}.
+* Your cluster is registered with {cluster-manager}.
 * Remote health reporting is enabled, which is the default.
 * You are logged in to the {product-title} web console.
 
 .Procedure
 
 . Navigate to *Home* -> *Overview* in the {product-title} web console.
 
-. Click *{red-hat-lightspeed}* on the *Status* card.
+. Click *Insights* on the *Status* card.
 +
-The pop-up window lists potential issues grouped by risk. Click the individual categories or *View all recommendations in {red-hat-lightspeed} Advisor* to display more details.
+A list of potential issues that are grouped by risk is displayed.
+. Click *View all recommendations in {red-hat-lightspeed} Advisor* or click a specific category to view detailed reports in the {hybrid-console-second}.
+
+[role="_additional-resources"]
+.Additional resources
+
+* link:https://console.redhat.com/openshift/insights/advisor/recommendations[{red-hat-lightspeed} Advisor recommendations]

modules/enabling-insights-advisor-recommendations.adoc

@@ -6,6 +6,7 @@
 [id="enabling-insights-advisor-recommendations_{context}"]
 = Enabling a previously disabled {red-hat-lightspeed} advisor service recommendation
 
+[role="_abstract"]
 When a recommendation is disabled for all clusters, you no longer see the recommendation in the {red-hat-lightspeed} advisor service. You can change this behavior.
 
 .Prerequisites

modules/enabling-insights-operator-alerts.adoc

@@ -52,5 +52,5 @@ data:
 . Click *Save*. The `insights-config` `ConfigMap` details page opens.
 
 . Verify that the value of the `config.yaml` `alerting` attribute is set to `disabled: false`.
-
++
 After you save the changes, {insights-operator} again sends alerts to the cluster Prometheus instance.

modules/enabling-insights-operator-gather.adoc

@@ -6,6 +6,7 @@
 [id="enabling-insights-operator-gather_{context}"]
 = Re-enabling the {insights-operator} periodic gather operations
 
+[role="_abstract"]
 If you disabled the default `InsightsDataGather` data gather operations, you can enable them again so that the {insights-operator} resumes the periodic data collection, and sends the resulting {red-hat-lightspeed} cluster reports to Red{nbsp}Hat.
 
 :FeatureName: The `InsightsDataGather` custom resource
@@ -36,8 +37,7 @@ endif::openshift-rosa,openshift-dedicated[]
 +
 [source,yaml]
 ----
-
-apiVersion: insights.openshift.io/v1alpha2
+apiVersion: insights.openshift.io/v1
 kind: InsightsDataGather
 metadata:
   name: cluster
@@ -51,7 +51,7 @@ spec:
 +
 [source,yaml]
 ----
-apiVersion: insights.openshift.io/v1alpha2
+apiVersion: insights.openshift.io/v1
 kind: InsightsDataGather
 metadata:
   name: cluster
@@ -72,8 +72,8 @@ spec:
 
 . Click *Save*.
 +
-After you save the changes, the {insights-operator} gather configurations are updated and the affected gather operations start.
-
+The {insights-operator} updates the gather configurations and starts the affected gather operations.
++
 [NOTE]
 ====
 Disabling gather operations restricts the ability of the {red-hat-lightspeed} advisor service to offer effective recommendations for your cluster.

modules/enabling-remote-health-reporting.adoc

@@ -6,6 +6,7 @@
 [id="enabling-remote-health-reporting_{context}"]
 = Enabling remote health reporting
 
+[role="_abstract"]
 If you or your organization have disabled remote health reporting, you can enable this feature again. You can see that remote health reporting is disabled from the message `Insights not available` in the *Status* tile on the {product-title} web console *Overview* page.
 
 To enable remote health reporting, you must change the global cluster pull secret with a new authorization token. Enabling remote health reporting enables both {insights-operator} and Telemetry.