diff --git a/_attributes/attributes-openshift-dedicated.adoc b/_attributes/attributes-openshift-dedicated.adoc index e5039d33a9e..8f47b5c13fc 100644 --- a/_attributes/attributes-openshift-dedicated.adoc +++ b/_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 diff --git a/modules/about-crio.adoc b/modules/about-crio.adoc index 10a3b5616d9..bf7528d948a 100644 --- a/modules/about-crio.adoc +++ b/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. diff --git a/modules/about-must-gather.adoc b/modules/about-must-gather.adoc index cdc6fe84253..df7475c03b6 100644 --- a/modules/about-must-gather.adoc +++ b/modules/about-must-gather.adoc @@ -11,6 +11,7 @@ [id="about-must-gather_{context}"] = About the must-gather tool +[role="_abstract"] The `oc adm must-gather` CLI command collects the information from your cluster that is most likely needed for debugging issues, including: * Resource definitions @@ -30,7 +31,7 @@ $ oc adm must-gather \ --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} ---- -- To collect the audit logs, use the `-- /usr/bin/gather_audit_logs` argument, as described in a following section. +* To collect the audit logs, use the `-- /usr/bin/gather_audit_logs` argument, as described in a following section. + For example: diff --git a/modules/about-sosreport.adoc b/modules/about-sosreport.adoc index 76487183ed2..c2ba0bfadda 100644 --- a/modules/about-sosreport.adoc +++ b/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`. diff --git a/modules/about-toolbox.adoc b/modules/about-toolbox.adoc index 6cda61ced3e..7d5fa40524e 100644 --- a/modules/about-toolbox.adoc +++ b/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`. diff --git a/modules/accessing-running-pods.adoc b/modules/accessing-running-pods.adoc index 2ead4efe3e3..af218c4af6c 100644 --- a/modules/accessing-running-pods.adoc +++ b/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 + [source,terminal] ---- -$ oc rsh <1> +$ oc rsh ---- -<1> If a pod has multiple containers, `oc rsh` defaults to the first container unless `-c ` is specified. ++ +where: + +``:: If a pod has multiple containers, `oc rsh` defaults to the first container unless `-c ` is specified. . Start a remote shell into a specific container within a pod: + @@ -47,6 +51,9 @@ $ oc rsh -c pod/ + [source,terminal] ---- -$ oc port-forward : <1> +$ oc port-forward : ---- -<1> Enter `Ctrl+C` to cancel the port forwarding session. ++ +where: + +` :`:: Enter `Ctrl+C` to cancel the port forwarding session. diff --git a/modules/accessing-windows-node-using-rdp.adoc b/modules/accessing-windows-node-using-rdp.adoc index c8e215ddddc..defa647163d 100644 --- a/modules/accessing-windows-node-using-rdp.adoc +++ b/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 @@ -22,7 +23,7 @@ You can access a Windows node by using a Remote Desktop Protocol (RDP). + [source,terminal] ---- -$ ssh -L 2020::3389 \ <1> +$ ssh -L 2020::3389 \ core@$(oc get service --all-namespaces -l run=ssh-bastion -o go-template="{{ with (index (index .items 0).status.loadBalancer.ingress 0) }}{{ or .hostname .ip }}{{end}}") ---- + diff --git a/modules/accessing-windows-node-using-ssh.adoc b/modules/accessing-windows-node-using-ssh.adoc index 0096b00029c..da3c8716319 100644 --- a/modules/accessing-windows-node-using-ssh.adoc +++ b/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 @@ -24,7 +25,7 @@ You can access a Windows node by using a secure shell (SSH). ---- $ ssh -t -o StrictHostKeyChecking=no -o ProxyCommand='ssh -A -o StrictHostKeyChecking=no \ -o ServerAliveInterval=30 -W %h:%p core@$(oc get service --all-namespaces -l run=ssh-bastion \ - -o go-template="{{ with (index (index .items 0).status.loadBalancer.ingress 0) }}{{ or .hostname .ip }}{{end}}")' @ <1> <2> + -o go-template="{{ with (index (index .items 0).status.loadBalancer.ingress 0) }}{{ or .hostname .ip }}{{end}}")' @ ---- + where: diff --git a/modules/checking-load-balancer-configuration.adoc b/modules/checking-load-balancer-configuration.adoc index 6f1099c1643..ac59988ae02 100644 --- a/modules/checking-load-balancer-configuration.adoc +++ b/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 diff --git a/modules/cleaning-crio-storage.adoc b/modules/cleaning-crio-storage.adoc index ed9e78c024e..51bcf3086d8 100644 --- a/modules/cleaning-crio-storage.adoc +++ b/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] + ---- diff --git a/modules/cluster-resources.adoc b/modules/cluster-resources.adoc index 5c8ebf2db08..7a79a7cf767 100644 --- a/modules/cluster-resources.adoc +++ b/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 @@ -43,4 +43,4 @@ $ oc get .config -o yaml [source,terminal] ---- $ oc edit .config -o yaml ----- +---- \ No newline at end of file diff --git a/modules/collecting-containerd-logs-windows.adoc b/modules/collecting-containerd-logs-windows.adoc index d492e6c5041..ae5f4123a9a 100644 --- a/modules/collecting-containerd-logs-windows.adoc +++ b/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 diff --git a/modules/collecting-kube-node-logs-windows.adoc b/modules/collecting-kube-node-logs-windows.adoc index 0fe2a295077..daeb23d08c6 100644 --- a/modules/collecting-kube-node-logs-windows.adoc +++ b/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 diff --git a/modules/collecting-windows-application-event-logs.adoc b/modules/collecting-windows-application-event-logs.adoc index b5cb5dfc253..69c3f69984d 100644 --- a/modules/collecting-windows-application-event-logs.adoc +++ b/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 diff --git a/modules/configuring-ovnk-use-second-ovs-bridge.adoc b/modules/configuring-ovnk-use-second-ovs-bridge.adoc index 4b9b1f804ef..72bed67e065 100644 --- a/modules/configuring-ovnk-use-second-ovs-bridge.adoc +++ b/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`. + diff --git a/modules/configuring-ovs-log-level-permanently.adoc b/modules/configuring-ovs-log-level-permanently.adoc index 16453eb32f4..c2240d5384f 100644 --- a/modules/configuring-ovs-log-level-permanently.adoc +++ b/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:` 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:` 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: + diff --git a/modules/configuring-ovs-log-level-temp.adoc b/modules/configuring-ovs-log-level-temp.adoc index 6f9eba59a76..524f56d0961 100644 --- a/modules/configuring-ovs-log-level-temp.adoc +++ b/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. diff --git a/modules/copying-files-pods-and-containers.adoc b/modules/copying-files-pods-and-containers.adoc index 025e8994aad..bcc6934843b 100644 --- a/modules/copying-files-pods-and-containers.adoc +++ b/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 :/ -c <1> +$ oc cp :/ -c ---- -<1> The first container in a pod is selected if the `-c` option is not specified. ++ +`-c ` 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 :/ -c <1> +$ oc cp :/ -c ---- -<1> The first container in a pod is selected if the `-c` option is not specified. ++ +`-c ` 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] ==== diff --git a/modules/determining-where-installation-issues-occur.adoc b/modules/determining-where-installation-issues-occur.adoc index c3123490c82..28a94f39e0a 100644 --- a/modules/determining-where-installation-issues-occur.adoc +++ b/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: diff --git a/modules/disabling-insights-operator-alerts.adoc b/modules/disabling-insights-operator-alerts.adoc index b4e70731bc0..a4189e375b7 100644 --- a/modules/disabling-insights-operator-alerts.adoc +++ b/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. diff --git a/modules/displaying-ovs-logs.adoc b/modules/displaying-ovs-logs.adoc index 28b37cd57ab..b590b59eeed 100644 --- a/modules/displaying-ovs-logs.adoc +++ b/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 diff --git a/modules/displaying-the-insights-status-in-the-web-console.adoc b/modules/displaying-the-insights-status-in-the-web-console.adoc index db200169070..130ef080afe 100644 --- a/modules/displaying-the-insights-status-in-the-web-console.adoc +++ b/modules/displaying-the-insights-status-in-the-web-console.adoc @@ -5,9 +5,10 @@ :_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 += Display 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 @@ -21,4 +22,4 @@ . Click *{red-hat-lightspeed}* 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. +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. \ No newline at end of file diff --git a/modules/enabling-insights-advisor-recommendations.adoc b/modules/enabling-insights-advisor-recommendations.adoc index 4956da58bd7..f2da5956fdd 100644 --- a/modules/enabling-insights-advisor-recommendations.adoc +++ b/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 diff --git a/modules/enabling-insights-operator-alerts.adoc b/modules/enabling-insights-operator-alerts.adoc index 39c78ffa34f..fe0043aac10 100644 --- a/modules/enabling-insights-operator-alerts.adoc +++ b/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. diff --git a/modules/enabling-insights-operator-gather.adoc b/modules/enabling-insights-operator-gather.adoc index cf7d3f28960..806abcf839d 100644 --- a/modules/enabling-insights-operator-gather.adoc +++ b/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,7 +37,6 @@ endif::openshift-rosa,openshift-dedicated[] + [source,yaml] ---- - apiVersion: insights.openshift.io/v1alpha2 kind: InsightsDataGather metadata: @@ -73,7 +73,7 @@ spec: . Click *Save*. + After you save the changes, the {insights-operator} gather configurations are updated and the affected gather operations start. - ++ [NOTE] ==== Disabling gather operations restricts the ability of the {red-hat-lightspeed} advisor service to offer effective recommendations for your cluster. diff --git a/modules/enabling-remote-health-reporting.adoc b/modules/enabling-remote-health-reporting.adoc index 6c87bdf06cf..af99efbcb5c 100644 --- a/modules/enabling-remote-health-reporting.adoc +++ b/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. diff --git a/modules/filtering-insights-advisor-recommendations.adoc b/modules/filtering-insights-advisor-recommendations.adoc index 37fd1c1fc48..2d3a1bc4119 100644 --- a/modules/filtering-insights-advisor-recommendations.adoc +++ b/modules/filtering-insights-advisor-recommendations.adoc @@ -6,6 +6,7 @@ [id="filtering-unnecessary-advisor-recommendations_{context}"] = Filtering {red-hat-lightspeed} advisor service recommendations +[role="_abstract"] As an {product-title} cluster manager, you can filter the recommendations that are displayed on the recommendations list. By applying filters, you can reduce the number of reported recommendations and concentrate on your highest priority recommendations. The following procedure demonstrates how to set and remove *Category* filters; however, the procedure is applicable to any of the filter types and respective values. @@ -23,8 +24,8 @@ The following procedure demonstrates how to set and remove *Category* filters; h . Expand the filter-value drop-down list and select the checkbox next to each category of recommendation you want to view. Leave the checkboxes for unnecessary categories clear. . Optional: Add additional filters to further refine the list. - -Only recommendations from the selected categories are shown in the list. ++ +Only recommendations from the selected categories are shown in the list. .Verification diff --git a/modules/gathering-application-diagnostic-data.adoc b/modules/gathering-application-diagnostic-data.adoc index 4ad99f8a5c2..b5e9c3a1b60 100644 --- a/modules/gathering-application-diagnostic-data.adoc +++ b/modules/gathering-application-diagnostic-data.adoc @@ -6,6 +6,7 @@ [id="gathering-application-diagnostic-data_{context}"] = Gathering application diagnostic data to investigate application failures +[role="_abstract"] Application failures can occur within running application pods. In these situations, you can retrieve diagnostic information with these strategies: * Review events relating to the application pods. diff --git a/modules/gathering-bootstrap-diagnostic-data.adoc b/modules/gathering-bootstrap-diagnostic-data.adoc index dc40584a129..a2eb7a1adf4 100644 --- a/modules/gathering-bootstrap-diagnostic-data.adoc +++ b/modules/gathering-bootstrap-diagnostic-data.adoc @@ -6,6 +6,7 @@ [id="gathering-bootstrap-diagnostic-data_{context}"] = Gathering bootstrap node diagnostic data +[role="_abstract"] When experiencing bootstrap-related issues, you can gather `bootkube.service` `journald` unit logs and container logs from the bootstrap node. .Prerequisites @@ -26,9 +27,10 @@ When experiencing bootstrap-related issues, you can gather `bootkube.service` `j + [source,terminal] ---- -$ curl -I http://:/bootstrap.ign <1> +$ curl -I http://:/bootstrap.ign ---- -<1> The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. ++ +The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. + .. To verify that the Ignition file was received by the bootstrap node, query the HTTP server logs on the serving host. For example, if you are using an Apache web server to serve Ignition files, enter the following command: + diff --git a/modules/gathering-crio-logs.adoc b/modules/gathering-crio-logs.adoc index 6fc4f70c913..8462777f8d4 100644 --- a/modules/gathering-crio-logs.adoc +++ b/modules/gathering-crio-logs.adoc @@ -6,6 +6,7 @@ [id="gathering-crio-logs_{context}"] = Gathering CRI-O journald unit logs +[role="_abstract"] If you experience CRI-O issues, you can obtain CRI-O journald unit logs from a node. .Prerequisites diff --git a/modules/gathering-data-network-logs.adoc b/modules/gathering-data-network-logs.adoc index b1d5fe75a2f..b21d2eb8f57 100644 --- a/modules/gathering-data-network-logs.adoc +++ b/modules/gathering-data-network-logs.adoc @@ -7,6 +7,7 @@ [id="gathering-data-network-logs_{context}"] = Gathering network logs +[role="_abstract"] You can gather network logs on all nodes in a cluster. .Procedure @@ -26,8 +27,9 @@ By default, the `must-gather` tool collects the OVN `nbdb` and `sbdb` databases + [source,terminal] ---- -$ tar cvaf must-gather-`date +"%m-%d-%Y-%H-%M-%S"`-.tar.gz <1> +$ tar cvaf must-gather-`date +"%m-%d-%Y-%H-%M-%S"`-.tar.gz ---- -<1> Replace `` with the actual directory name. ++ +Replace the `` placeholder with the actual directory name. -. Attach the compressed file to your support case on the link:https://access.redhat.com/support/cases/#/case/list[the *Customer Support* page] of the Red Hat Customer Portal. +. Attach the compressed file to your support case on the link:https://access.redhat.com/support/cases/#/case/list[*Customer Support* page] of the Red Hat Customer Portal. diff --git a/modules/gathering-data-specific-features.adoc b/modules/gathering-data-specific-features.adoc index c1565c47c37..37ba4373380 100644 --- a/modules/gathering-data-specific-features.adoc +++ b/modules/gathering-data-specific-features.adoc @@ -14,6 +14,7 @@ endif::[] [id="gathering-data-specific-features_{context}"] = Gathering data about specific features +[role="_abstract"] You can gather debugging information about specific features by using the `oc adm must-gather` CLI command with the `--image` or `--image-stream` argument. The `must-gather` tool supports multiple images, so you can gather data about more than one feature by running a single command. ifdef::from-main-support-section[] @@ -172,11 +173,9 @@ For example, the following command gathers both the default cluster data and inf [source,terminal,subs="attributes+"] ---- $ oc adm must-gather \ - --image-stream=openshift/must-gather \ <1> - --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} <2> + --image-stream=openshift/must-gather \ + --image=registry.redhat.io/container-native-virtualization/cnv-must-gather-rhel9:v{HCOVersion} ---- -<1> The default {product-title} `must-gather` image -<2> The must-gather image for {VirtProductName} + You can use the `must-gather` tool with additional arguments to gather data that is specifically related to OpenShift Logging and the ifndef::openshift-dedicated[] @@ -194,8 +193,6 @@ $ oc adm must-gather --image=$(oc -n openshift-logging get deployment.apps/clust ---- + .Example `must-gather` output for OpenShift Logging -[%collapsible] -==== [source,terminal] ---- ├── cluster-logging @@ -358,7 +355,6 @@ endif::openshift-dedicated[] └── openshift-operators-redhat ├── ... ---- -==== endif::openshift-origin[] . Run the `oc adm must-gather` command with one or more `--image` or `--image-stream` arguments. For example, the following command gathers both the default cluster data and information specific to KubeVirt: @@ -366,20 +362,21 @@ endif::openshift-origin[] [source,terminal] ---- $ oc adm must-gather \ - --image-stream=openshift/must-gather \ <1> - --image=quay.io/kubevirt/must-gather <2> + --image-stream=openshift/must-gather \ + --image=quay.io/kubevirt/must-gather ---- -<1> The default {product-title} `must-gather` image -<2> The must-gather image for KubeVirt ifndef::openshift-origin[] . Create a compressed file from the `must-gather` directory that was just created in your working directory. Make sure you provide the date and cluster ID for the unique must-gather data. For more information about how to find the cluster ID, see link:https://access.redhat.com/solutions/5280291[How to find the cluster-id or name on OpenShift cluster]. For example, on a computer that uses a Linux operating system, run the following command: + [source,terminal] ---- -$ tar cvaf must-gather-`date +"%m-%d-%Y-%H-%M-%S"`-.tar.gz <1> +$ tar cvaf must-gather-`date +"%m-%d-%Y-%H-%M-%S"`-.tar.gz ---- -<1> Replace `` with the actual directory name. ++ +where: + +``:: Replace with the actual directory name. . Attach the compressed file to your support case on the link:https://access.redhat.com/support/cases/#/case/list[the *Customer Support* page] of the Red Hat Customer Portal. endif::openshift-origin[] diff --git a/modules/gathering-operator-logs.adoc b/modules/gathering-operator-logs.adoc index 5a8799280c8..ac40a77b147 100644 --- a/modules/gathering-operator-logs.adoc +++ b/modules/gathering-operator-logs.adoc @@ -6,6 +6,7 @@ [id="gathering-operator-logs_{context}"] = Gathering Operator logs +[role="_abstract"] If you experience Operator issues, you can gather detailed diagnostic information from Operator pod logs. .Prerequisites diff --git a/modules/gathering-s2i-diagnostic-data.adoc b/modules/gathering-s2i-diagnostic-data.adoc index 33dee1e3c60..d157c8e6635 100644 --- a/modules/gathering-s2i-diagnostic-data.adoc +++ b/modules/gathering-s2i-diagnostic-data.adoc @@ -6,7 +6,10 @@ [id="gathering-s2i-diagnostic-data_{context}"] = Gathering Source-to-Image diagnostic data -The S2I tool runs a build pod and a deployment pod in sequence. The deployment pod is responsible for deploying the application pods based on the application container image created in the build stage. Watch build, deployment and application pod status to determine where in the S2I process a failure occurs. Then, focus diagnostic data collection accordingly. +[role="_abstract"] +The S2I tool runs a build pod and a deployment pod in sequence. The deployment pod is responsible for deploying the application pods based on the application container image created in the build stage. + +Watch build, deployment and application pod status to determine where in the S2I process a failure occurs. Then, focus diagnostic data collection accordingly. .Prerequisites @@ -25,9 +28,10 @@ endif::openshift-rosa,openshift-dedicated[] + [source,terminal] ---- -$ oc get pods -w <1> +$ oc get pods -w ---- -<1> Use `-w` to monitor pods for changes until you quit the command using `Ctrl+C`. ++ +Use the `-w` flag to monitor pods for changes until you quit the command using `Ctrl+C`. . Review a failed pod's logs for errors. + diff --git a/modules/insights-operator-about.adoc b/modules/insights-operator-about.adoc index 32eb19d97d7..42e546551aa 100644 --- a/modules/insights-operator-about.adoc +++ b/modules/insights-operator-about.adoc @@ -6,6 +6,7 @@ [id="insights-operator-about_{context}"] = About the {insights-operator} +[role="_abstract"] The {insights-operator} periodically gathers configuration and component failure status and, by default, reports that data every two hours to Red{nbsp}Hat. This information enables Red{nbsp}Hat to assess configuration and deeper failure data than is reported through Telemetry. Users of {product-title} can display the report of each cluster in the {insights-advisor-url} service on {hybrid-console}. If any issues have been identified, {red-hat-lightspeed} provides further details and, if available, steps on how to solve a problem. diff --git a/modules/insights-operator-downloading-archive.adoc b/modules/insights-operator-downloading-archive.adoc index de1c9bf4002..2819e85898b 100644 --- a/modules/insights-operator-downloading-archive.adoc +++ b/modules/insights-operator-downloading-archive.adoc @@ -6,6 +6,7 @@ [id="insights-operator-downloading-archive_{context}"] = Downloading your {insights-operator} archive +[role="_abstract"] {insights-operator} stores gathered data in an archive located in the `openshift-insights` namespace of your cluster. You can download and review the data that is gathered by the {insights-operator}. .Prerequisites @@ -30,8 +31,9 @@ $ oc get pods --namespace=openshift-insights -o custom-columns=:metadata.name -- + [source,terminal] ---- -$ oc cp openshift-insights/:/var/lib/insights-operator ./insights-data <1> +$ oc cp openshift-insights/:/var/lib/insights-operator ./insights-data ---- -<1> Replace `` with the pod name output from the preceding command. - ++ +Replace `` with the pod name output from the preceding command. ++ The recent {insights-operator} archives are now available in the `insights-data` directory. diff --git a/modules/insights-operator-enable-obfuscation.adoc b/modules/insights-operator-enable-obfuscation.adoc index ebc5c2fa16d..32bfdeaeded 100644 --- a/modules/insights-operator-enable-obfuscation.adoc +++ b/modules/insights-operator-enable-obfuscation.adoc @@ -6,6 +6,7 @@ [id="insights-operator-enable-obfuscation_{context}"] = Enabling {insights-operator} data obfuscation +[role="_abstract"] You can enable obfuscation to mask sensitive and identifiable IPv4 addresses and cluster base domains that the {insights-operator} sends to link:https://console.redhat.com[console.redhat.com]. [WARNING] diff --git a/modules/insights-operator-enabling-sca.adoc b/modules/insights-operator-enabling-sca.adoc index 4b2939a14c7..40a103a5341 100644 --- a/modules/insights-operator-enabling-sca.adoc +++ b/modules/insights-operator-enabling-sca.adoc @@ -7,6 +7,7 @@ [id="insights-operator-enabling-sca_{context}"] = Enabling a previously disabled simple content access import +[role="_abstract"] If the importing of simple content access entitlements is disabled, the {insights-operator} does not import simple content access entitlements. You can change this behavior. .Prerequisites diff --git a/modules/insights-operator-gather-duration.adoc b/modules/insights-operator-gather-duration.adoc index 665119b60e7..493e6944710 100644 --- a/modules/insights-operator-gather-duration.adoc +++ b/modules/insights-operator-gather-duration.adoc @@ -6,6 +6,7 @@ [id="insights-operator-gather-duration_{context}"] = Viewing {insights-operator} gather durations +[role="_abstract"] You can view the time it takes for the {insights-operator} to gather the information contained in the archive. This helps you to understand {insights-operator} resource usage and issues with {red-hat-lightspeed} Advisor. .Prerequisites @@ -22,13 +23,13 @@ The file contains a list of {insights-operator} gather operations: ---- { "name": "clusterconfig/authentication", - "duration_in_ms": 730, <1> + "duration_in_ms": 730, "records_count": 1, "errors": null, "panic": null } ---- + -<1> `duration_in_ms` is the amount of time in milliseconds for each gather operation. +The `duration_in_ms` field is the amount of time in milliseconds for each gather operation. . Inspect each gather operation for abnormalities. diff --git a/modules/insights-operator-insights-config.adoc b/modules/insights-operator-insights-config.adoc new file mode 100644 index 00000000000..e37d7097192 --- /dev/null +++ b/modules/insights-operator-insights-config.adoc @@ -0,0 +1,60 @@ +// Module included in the following assemblies: +// +// * support/remote_health_monitoring/using-insights-operator.adoc + +:_mod-docs-content-type: PROCEDURE +[id="insights-operator-insights-config_{context}"] += Creating the insights-config ConfigMap object + +[role="_abstract"] +You can create the `insights-config` `ConfigMap` object for the {insights-operator} with custom configurations. + +[IMPORTANT] +==== +Red{nbsp}Hat recommends you consult Red{nbsp}Hat Support before making changes to the default {insights-operator} configuration. +==== + +.Prerequisites + +* Remote health reporting is enabled, which is the default. +* You are logged in to the {product-title} web console as a user with `cluster-admin` role. + +.Procedure + +. Go to *Workloads* -> *ConfigMaps* and select *Project: openshift-insights*. + +. Click *Create ConfigMap*. + +. Select *Configure via: YAML view* and enter your configuration preferences, for example: ++ +[source,yaml] +---- +apiVersion: v1 +kind: ConfigMap +metadata: + name: insights-config + namespace: openshift-insights +data: + config.yaml: | + dataReporting: + obfuscation: + - networking + - workload_names + sca: + disabled: false + interval: 2h + alerting: + disabled: false +binaryData: {} +immutable: false +---- + +. Optional: Select *Form view* and enter the necessary information that way. + +. In the *ConfigMap Name* field, enter *insights-config*. + +. In the *Key* field, enter *config.yaml*. + +. For the *Value* field, either browse for a file to drag and drop into the field or enter your configuration parameters manually. + +. Click *Create*. The `ConfigMap` object and configuration information are displayed. diff --git a/modules/insights-operator-manual-upload.adoc b/modules/insights-operator-manual-upload.adoc index c10e134e5fd..bfde0c3360e 100644 --- a/modules/insights-operator-manual-upload.adoc +++ b/modules/insights-operator-manual-upload.adoc @@ -2,12 +2,11 @@ // // * support/remote_health_monitoring/remote-health-reporting-from-restricted-network.adoc - - :_mod-docs-content-type: PROCEDURE [id="insights-operator-manual-upload_{context}"] = Uploading an {insights-operator} archive +[role="_abstract"] You can manually upload an {insights-operator} archive to link:https://console.redhat.com[console.redhat.com] to diagnose potential issues. .Prerequisites @@ -35,10 +34,10 @@ $ oc extract secret/pull-secret -n openshift-config --to=. "auth": "__", "email": "asd@redhat.com" } + } } ---- - . Upload the archive to link:https://console.redhat.com[console.redhat.com]: + [source,terminal,subs="+quotes"] @@ -55,7 +54,6 @@ where: If the operation is successful, the command returns a `"request_id"` and `"account_number"`: + .Example output -+ [source,terminal] ---- * Connection #0 to host console.redhat.com left intact @@ -64,7 +62,7 @@ If the operation is successful, the command returns a `"request_id"` and `"accou .Verification -. Log in to link:https://console.redhat.com/openshift[]. +. Log in to link:https://console.redhat.com/openshift[console.redhat.com]. . Click the *Cluster List* menu in the left pane. diff --git a/modules/insights-operator-new-pull-secret-disabled.adoc b/modules/insights-operator-new-pull-secret-disabled.adoc index 6a06c5dfec6..38004b57842 100644 --- a/modules/insights-operator-new-pull-secret-disabled.adoc +++ b/modules/insights-operator-new-pull-secret-disabled.adoc @@ -6,6 +6,7 @@ [id="insights-operator-new-pull-secret_{context}"] = Disabling remote health reporting +[role="_abstract"] You can change your existing global cluster pull secret to disable remote health reporting. This configuration disables both Telemetry and the {insights-operator}. .Prerequisites diff --git a/modules/insights-operator-new-pull-secret-enable.adoc b/modules/insights-operator-new-pull-secret-enable.adoc index 580cf1dd71d..73e046ad75a 100644 --- a/modules/insights-operator-new-pull-secret-enable.adoc +++ b/modules/insights-operator-new-pull-secret-enable.adoc @@ -6,6 +6,7 @@ [id="insights-operator-new-pull-secret-enable_{context}"] = Changing your global cluster pull secret to enable remote health reporting +[role="_abstract"] You can change your existing global cluster pull secret to enable remote health reporting. If you have disabled remote health monitoring, you must download a new pull secret with your `console.openshift.com` access token from {cluster-manager-first}. .Prerequisites diff --git a/modules/insights-operator-one-time-gather.adoc b/modules/insights-operator-one-time-gather.adoc index 571e7f2f3cd..71bec3e9c23 100644 --- a/modules/insights-operator-one-time-gather.adoc +++ b/modules/insights-operator-one-time-gather.adoc @@ -6,6 +6,7 @@ [id="insights-operator-one-time-gather_{context}"] = Running an {insights-operator} gather operation +[role="_abstract"] You must run a gather operation to create an {insights-operator} archive. .Prerequisites @@ -14,12 +15,7 @@ You must run a gather operation to create an {insights-operator} archive. .Procedure -. Create a file named `gather-job.yaml` using this template: -+ -[source,yaml] ----- -include::https://raw.githubusercontent.com/openshift/insights-operator/release-4.20/docs/gather-job.yaml[] ----- +. Create a file named `gather-job.yaml` using this https://raw.githubusercontent.com/openshift/insights-operator/release-4.20/docs/gather-job.yaml[template]. . Copy your `insights-operator` image version: + @@ -29,7 +25,6 @@ $ oc get -n openshift-insights deployment insights-operator -o yaml ---- + .Example output -+ [source,yaml] ---- apiVersion: apps/v1 @@ -49,7 +44,7 @@ spec: # ... ---- + -The `spec.template.spec.containers.image` field specifies your insights-operator image version. +The `spec.template.spec.containers.image` field specifies your `insights-operator` image version. . Paste your image version in `gather-job.yaml`: + diff --git a/modules/insights-operator-register-disconnected-cluster.adoc b/modules/insights-operator-register-disconnected-cluster.adoc index 14242f47377..12b9fe010b6 100644 --- a/modules/insights-operator-register-disconnected-cluster.adoc +++ b/modules/insights-operator-register-disconnected-cluster.adoc @@ -6,7 +6,10 @@ [id="insights-operator-register-disconnected-cluster_{context}"] = Registering your disconnected cluster -Register your disconnected {product-title} cluster on the {hybrid-console} so that your cluster does not get impacted by disabling remote health reporting. For more information, see "Consequences of disabling remote health reporting". +[role="_abstract"] +Register your disconnected {product-title} cluster on the {hybrid-console} so that your cluster does not get impacted by disabling remote health reporting. + +For more information, see "Consequences of disabling remote health reporting". [IMPORTANT] ==== diff --git a/modules/insights-operator-showing-data-collected-from-the-cluster.adoc b/modules/insights-operator-showing-data-collected-from-the-cluster.adoc index 9a6e6de2525..ae656372550 100644 --- a/modules/insights-operator-showing-data-collected-from-the-cluster.adoc +++ b/modules/insights-operator-showing-data-collected-from-the-cluster.adoc @@ -6,6 +6,7 @@ [id="insights-operator-showing-data-collected-from-the-cluster_{context}"] = Showing data collected by the {insights-operator} +[role="_abstract"] You can review the data that is collected by the {insights-operator}. .Prerequisites @@ -27,5 +28,5 @@ $ INSIGHTS_OPERATOR_POD=$(oc get pods --namespace=openshift-insights -o custom-c ---- $ oc cp openshift-insights/$INSIGHTS_OPERATOR_POD:/var/lib/insights-operator ./insights-data ---- - ++ The recent {insights-operator} archives are now available in the `insights-data` directory. diff --git a/modules/inspecting-pod-and-container-logs.adoc b/modules/inspecting-pod-and-container-logs.adoc index ff9197ce795..09b09bb8474 100644 --- a/modules/inspecting-pod-and-container-logs.adoc +++ b/modules/inspecting-pod-and-container-logs.adoc @@ -6,6 +6,7 @@ [id="inspecting-pod-and-container-logs_{context}"] = Inspecting pod and container logs +[role="_abstract"] You can inspect pod and container logs for warnings and error messages related to explicit pod failures. Depending on policy and exit code, pod and container logs remain available after pods have been terminated. .Prerequisites diff --git a/modules/installation-bootstrap-gather.adoc b/modules/installation-bootstrap-gather.adoc index 5877eb15432..b1c762b4791 100644 --- a/modules/installation-bootstrap-gather.adoc +++ b/modules/installation-bootstrap-gather.adoc @@ -34,12 +34,9 @@ $ ./openshift-install gather bootstrap --dir + The `installation_directory` placeholder is for the directory you specified when you ran `./openshift-install create cluster`. This directory contains the {product-title} definition files that the installation program creates. + -For installer-provisioned infrastructure, the installation program stores -information about the cluster, so you do not specify the hostnames or IP -addresses. +For installer-provisioned infrastructure, the installation program stores information about the cluster, so you do not specify the hostnames or IP addresses. -** If you used infrastructure that you provisioned yourself, change to the directory that contains the installation program and run the following -command: +** If you used infrastructure that you provisioned yourself, change to the directory that contains the installation program and run the following command: + [source,terminal] ---- @@ -52,6 +49,7 @@ $ ./openshift-install gather bootstrap --dir \ + where: + +-- * `installation_directory`:: Specifies the same directory you specified when you ran `./openshift-install create cluster`. This directory contains the {product-title} definition files that the installation program creates. * ``:: Specifies the fully qualified domain name or IP address of the cluster's bootstrap machine. * ``:: For each control plane, or master, machine in your cluster, replace this placeholder with its fully qualified domain name or IP address. @@ -60,6 +58,7 @@ where: ==== A default cluster contains three control plane machines. List all of your control plane machines as shown, no matter how many your cluster uses. ==== +-- + .Example output [source,terminal] diff --git a/modules/investigating-etcd-installation-issues.adoc b/modules/investigating-etcd-installation-issues.adoc index 3f68450eee4..fb6b7f85029 100644 --- a/modules/investigating-etcd-installation-issues.adoc +++ b/modules/investigating-etcd-installation-issues.adoc @@ -6,6 +6,7 @@ [id="investigating-etcd-installation-issues_{context}"] = Investigating etcd installation issues +[role="_abstract"] If you experience etcd issues during installation, you can check etcd pod status and collect etcd pod logs. You can also verify etcd DNS records and check DNS availability on control plane nodes. .Prerequisites diff --git a/modules/investigating-kernel-crashes.adoc b/modules/investigating-kernel-crashes.adoc index 95ae47b7355..2192e713fb6 100644 --- a/modules/investigating-kernel-crashes.adoc +++ b/modules/investigating-kernel-crashes.adoc @@ -6,4 +6,5 @@ [id="investigating-kernel-crashes"] = Investigating kernel crashes +[role="_abstract"] The `kdump` service, included in the `kexec-tools` package, provides a crash-dumping mechanism. You can use this service to save the contents of a system's memory for later analysis. diff --git a/modules/investigating-kubelet-api-installation-issues.adoc b/modules/investigating-kubelet-api-installation-issues.adoc index 6c634f35962..83b7669b3b3 100644 --- a/modules/investigating-kubelet-api-installation-issues.adoc +++ b/modules/investigating-kubelet-api-installation-issues.adoc @@ -6,6 +6,7 @@ [id="investigating-kubelet-api-installation-issues_{context}"] = Investigating control plane node kubelet and API server issues +[role="_abstract"] To investigate control plane node kubelet and API server issues during installation, check DNS, DHCP, and load balancer functionality. Also, verify that certificates have not expired. .Prerequisites diff --git a/modules/investigating-master-node-installation-issues.adoc b/modules/investigating-master-node-installation-issues.adoc index 902f91cf71b..27e13e6cdad 100644 --- a/modules/investigating-master-node-installation-issues.adoc +++ b/modules/investigating-master-node-installation-issues.adoc @@ -6,6 +6,7 @@ [id="investigating-master-node-installation-issues_{context}"] = Investigating control plane node installation issues +[role="_abstract"] If you experience control plane node installation issues, determine the control plane node {product-title} software defined network (SDN), and network Operator status. Collect `kubelet.service`, `crio.service` journald unit logs, and control plane node container logs for visibility into control plane node agent, CRI-O container runtime, and pod activity. .Prerequisites @@ -38,9 +39,10 @@ The initial `kubeadmin` password can be found in `/auth/kubea + [source,terminal] ---- -$ curl -I http://:/master.ign <1> +$ curl -I http://:/master.ign ---- -<1> The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. ++ +The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. + .. To verify that the Ignition file was received by the control plane node query the HTTP server logs on the serving host. For example, if you are using an Apache web server to serve Ignition files: + diff --git a/modules/investigating-why-windows-machine-compute-node.adoc b/modules/investigating-why-windows-machine-compute-node.adoc index 40dc2d18cb7..b9c67927898 100644 --- a/modules/investigating-why-windows-machine-compute-node.adoc +++ b/modules/investigating-why-windows-machine-compute-node.adoc @@ -3,9 +3,11 @@ // * support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc // * windows_containers/windows-containers-troubleshooting.adoc +:_mod-docs-content-type: PROCEDURE [id="investigating-why-windows-machine-compute-node_{context}"] = Investigating why Windows Machine does not become compute node +[role="_abstract"] There are various reasons why a Windows Machine does not become a compute node. The best way to investigate this problem is to collect the Windows Machine Config Operator (WMCO) logs. .Prerequisites diff --git a/modules/investigating-worker-node-installation-issues.adoc b/modules/investigating-worker-node-installation-issues.adoc index b5cbf6d226c..bfbfc70b679 100644 --- a/modules/investigating-worker-node-installation-issues.adoc +++ b/modules/investigating-worker-node-installation-issues.adoc @@ -6,7 +6,10 @@ [id="investigating-worker-node-installation-issues_{context}"] = Investigating worker node installation issues -If you experience worker node installation issues, you can review the worker node status. Collect `kubelet.service`, `crio.service` journald unit logs and the worker node container logs for visibility into the worker node agent, CRI-O container runtime and pod activity. Additionally, you can check the Ignition file and Machine API Operator functionality. If worker node postinstallation configuration fails, check Machine Config Operator (MCO) and DNS functionality. You can also verify system clock synchronization between the bootstrap, master, and worker nodes, and validate certificates. +[role="_abstract"] +If you experience worker node installation issues, you can review the worker node status. Collect `kubelet.service`, `crio.service` journald unit logs and the worker node container logs for visibility into the worker node agent, CRI-O container runtime and pod activity. + +Additionally, you can check the Ignition file and Machine API Operator functionality. If worker node postinstallation configuration fails, check Machine Config Operator (MCO) and DNS functionality. You can also verify system clock synchronization between the bootstrap, master, and worker nodes, and validate certificates. .Prerequisites @@ -38,9 +41,10 @@ The initial `kubeadmin` password can be found in `/auth/kubea + [source,terminal] ---- -$ curl -I http://:/worker.ign <1> +$ curl -I http://:/worker.ign ---- -<1> The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. ++ +The `-I` option returns the header only. If the Ignition file is available on the specified URL, the command returns `200 OK` status. If it is not available, the command returns `404 file not found`. + .. To verify that the Ignition file was received by the worker node, query the HTTP server logs on the HTTP host. For example, if you are using an Apache web server to serve Ignition files: + diff --git a/modules/managed-cluster-notification-view-in-hcc.adoc b/modules/managed-cluster-notification-view-in-hcc.adoc index 02d7a119e4e..67a98f03a38 100644 --- a/modules/managed-cluster-notification-view-in-hcc.adoc +++ b/modules/managed-cluster-notification-view-in-hcc.adoc @@ -7,10 +7,11 @@ [id="managed-cluster-notification-view-hcc_{context}"] = Viewing cluster notifications using the {hybrid-console} -Cluster notifications provide important information about the health of your cluster. You can view notifications that have been sent to your cluster in the **Cluster history** tab on the {hybrid-console}. +[role="_abstract"] +Cluster notifications give important information about the health of your cluster. You can view notifications sent to your cluster in the **Cluster history** tab on the {hybrid-console}. .Prerequisites -* You are logged in to the {hybrid-console-second}. +* You have logged in to the {hybrid-console-second}. .Procedure . Navigate to the link:https://console.redhat.com/openshift[Clusters] page of the {hybrid-console-second}. @@ -18,12 +19,6 @@ Cluster notifications provide important information about the health of your clu . Click the **Cluster history** tab. + Cluster notifications appear under the Cluster history heading. -. Optional: Filter for relevant cluster notifications +. Optional: Filter for relevant cluster notifications. + -Use the filter controls to hide cluster notifications that are not relevant to you, so that you can focus on your area of expertise or on resolving a critical issue. You can filter notifications based on text in the notification description, severity level, notification type, when the notification was received, and which system or person triggered the notification. - -// .Additional resources -// * Cluster notification types -// * Cluster notification severity levels -// * Cluster notification emails -// * Troubleshooting: Cluster notifications \ No newline at end of file +Use the filter controls to hide cluster notifications that are not relevant to you, so that you can focus on your area of expertise or on resolving a critical issue. You can filter notifications based on text in the notification description, severity level, notification type, when you received the notification, and the system or person that triggered the notification. \ No newline at end of file diff --git a/modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc b/modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc index af3829e7e8d..90aebb8401e 100644 --- a/modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc +++ b/modules/monitoring-determining-why-prometheus-is-consuming-disk-space.adoc @@ -7,7 +7,10 @@ [id="determining-why-prometheus-is-consuming-disk-space_{context}"] = Determining why Prometheus is consuming a lot of disk space -Developers can create labels to define attributes for metrics in the form of key-value pairs. The number of potential key-value pairs corresponds to the number of possible values for an attribute. An attribute that has an unlimited number of potential values is called an unbound attribute. For example, a `customer_id` attribute is unbound because it has an infinite number of possible values. +[role="_abstract"] +Developers can create labels to define attributes for metrics in the form of key-value pairs. The number of potential key-value pairs corresponds to the number of possible values for an attribute. + +An attribute that has an unlimited number of potential values is called an unbound attribute. For example, a `customer_id` attribute is unbound because it has an infinite number of possible values. Every assigned key-value pair has a unique time series. The use of many unbound attributes in labels can result in an exponential increase in the number of time series created. This can impact Prometheus performance and can consume a lot of disk space. diff --git a/modules/monitoring-installation-progress.adoc b/modules/monitoring-installation-progress.adoc index dd9f63f9d9c..5f9dc6a3a0b 100644 --- a/modules/monitoring-installation-progress.adoc +++ b/modules/monitoring-installation-progress.adoc @@ -6,6 +6,7 @@ [id="monitoring-installation-progress_{context}"] = Monitoring installation progress +[role="_abstract"] You can monitor high-level installation, bootstrap, and control plane logs as an {product-title} installation progresses. This provides greater visibility into how an installation progresses and helps identify the stage at which an installation failure occurs. .Prerequisites diff --git a/modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc b/modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc index cb81ab180fc..c0ee5048914 100644 --- a/modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc +++ b/modules/monitoring-investigating-why-user-defined-metrics-are-unavailable.adoc @@ -7,7 +7,10 @@ [id="investigating-why-user-defined-metrics-are-unavailable_{context}"] = Investigating why user-defined project metrics are unavailable -`ServiceMonitor` resources enable you to determine how to use the metrics exposed by a service in user-defined projects. Follow the steps outlined in this procedure if you have created a `ServiceMonitor` resource but cannot see any corresponding metrics in the Metrics UI. +[role="_abstract"] +`ServiceMonitor` resources enable you to determine how to use the metrics exposed by a service in user-defined projects. + +Follow the steps outlined in this procedure if you have created a `ServiceMonitor` resource but cannot see any corresponding metrics in the Metrics UI. .Prerequisites diff --git a/modules/monitoring-resolving-the-kubepersistentvolumefillingup-alert-firing-for-prometheus.adoc b/modules/monitoring-resolving-the-kubepersistentvolumefillingup-alert-firing-for-prometheus.adoc index 473c1aaa8f9..0f6648ac0c1 100644 --- a/modules/monitoring-resolving-the-kubepersistentvolumefillingup-alert-firing-for-prometheus.adoc +++ b/modules/monitoring-resolving-the-kubepersistentvolumefillingup-alert-firing-for-prometheus.adoc @@ -7,6 +7,7 @@ [id="resolving-the-kubepersistentvolumefillingup-alert-firing-for-prometheus_{context}"] = Resolving the KubePersistentVolumeFillingUp alert firing for Prometheus +[role="_abstract"] As a cluster administrator, you can resolve the `KubePersistentVolumeFillingUp` alert being triggered for Prometheus. The critical alert fires when a persistent volume (PV) claimed by a `prometheus-k8s-*` pod in the `openshift-monitoring` project has less than 3% total space remaining. This can cause Prometheus to function abnormally. @@ -23,12 +24,12 @@ To address this issue, you can remove Prometheus time-series database (TSDB) blo .Prerequisites -ifndef::openshift-dedicated,openshift-rosa-hcp,openshift-rosa[] +ifndef::openshift-dedicated,openshift-rosa[] * You have access to the cluster as a user with the `cluster-admin` cluster role. -endif::openshift-dedicated,openshift-rosa-hcp,openshift-rosa[] -ifdef::openshift-dedicated,openshift-rosa-hcp,openshift-rosa[] +endif::openshift-dedicated,openshift-rosa[] +ifdef::openshift-dedicated,openshift-rosa[] * You have access to the cluster as a user with the `dedicated-admin` role. -endif::openshift-dedicated,openshift-rosa-hcp,openshift-rosa[] +endif::openshift-dedicated,openshift-rosa[] * You have installed the {oc-first}. .Procedure @@ -37,12 +38,13 @@ endif::openshift-dedicated,openshift-rosa-hcp,openshift-rosa[] + [source,terminal] ---- -$ oc debug -n openshift-monitoring \// <1> --c prometheus --image=$(oc get po -n openshift-monitoring \// <1> +$ oc debug -n openshift-monitoring \ +-c prometheus --image=$(oc get po -n openshift-monitoring \ -o jsonpath='{.spec.containers[?(@.name=="prometheus")].image}') \ -- sh -c 'cd /prometheus/;du -hs $(ls -dtr */ | grep -Eo "[0-9|A-Z]{26}")' ---- -<1> Replace `` with the pod mentioned in the `KubePersistentVolumeFillingUp` alert description. ++ +Replace `` with the pod mentioned in the `KubePersistentVolumeFillingUp` alert description. + .Example output [source,terminal] @@ -74,11 +76,12 @@ while read BLOCK; do rm -r /prometheus/$BLOCK; done' + [source,terminal] ---- -$ oc debug -n openshift-monitoring \// <1> ---image=$(oc get po -n openshift-monitoring \// <1> +$ oc debug -n openshift-monitoring \ +--image=$(oc get po -n openshift-monitoring \ -o jsonpath='{.spec.containers[?(@.name=="prometheus")].image}') -- df -h /prometheus/ ---- -<1> Replace `` with the pod mentioned in the `KubePersistentVolumeFillingUp` alert description. ++ +Replace `` with the pod mentioned in the `KubePersistentVolumeFillingUp` alert description. + The following example output shows the mounted PV claimed by the `prometheus-k8s-0` pod that has 63% of space remaining: + diff --git a/modules/must-gather-flags.adoc b/modules/must-gather-flags.adoc index f5bea4896c4..193f772e63c 100644 --- a/modules/must-gather-flags.adoc +++ b/modules/must-gather-flags.adoc @@ -6,6 +6,7 @@ [id="must-gather-flags_{context}"] = Must-gather flags +[role="_abstract"] The flags listed in the following table are available to use with the `oc adm must-gather` command. .{product-title} flags for `oc adm must-gather` diff --git a/modules/must-gather-storage-limit.adoc b/modules/must-gather-storage-limit.adoc index 6362c965119..4043fced05b 100644 --- a/modules/must-gather-storage-limit.adoc +++ b/modules/must-gather-storage-limit.adoc @@ -6,15 +6,10 @@ [id="must-gather-storage-limit_{context}"] = Changing the must-gather storage limit -When using the `oc adm must-gather` command to collect data the default maximum storage for the information is 30% of the storage capacity of the container. After the 30% limit is reached the container is killed and the gathering process stops. Information already gathered is downloaded to your local storage. To run the must-gather command again, you need either a container with more storage capacity or to adjust the maximum volume percentage. +[role="_abstract"] +When using the `oc adm must-gather` command to collect data the default maximum storage for the information is 30% of the storage capacity of the container. After the 30% limit is reached the container is killed and the gathering process stops. -If the container reaches the storage limit, an error message similar to the following example is generated. - -.Example output -[source,terminal] ----- -Disk usage exceeds the volume percentage of 30% for mounted directory. Exiting... ----- +Information already gathered is downloaded to your local storage. To run the must-gather command again, you need either a container with more storage capacity or to adjust the maximum volume percentage. .Prerequisites @@ -28,4 +23,11 @@ Disk usage exceeds the volume percentage of 30% for mounted directory. Exiting.. [source,terminal] ---- $ oc adm must-gather --volume-percentage +---- ++ +If the container reaches the storage limit, an error message similar to the following example is generated: ++ +[source,terminal] +---- +Disk usage exceeds the volume percentage of 30% for mounted directory. Exiting... ---- \ No newline at end of file diff --git a/modules/nw-how-nw-iface-selected.adoc b/modules/nw-how-nw-iface-selected.adoc index 985b4875334..6cac4821433 100644 --- a/modules/nw-how-nw-iface-selected.adoc +++ b/modules/nw-how-nw-iface-selected.adoc @@ -6,7 +6,10 @@ [id="nw-how-nw-iface-selected_{context}"] = How the network interface is selected -For installations on bare metal or with virtual machines that have more than one network interface controller (NIC), the NIC that {product-title} uses for communication with the Kubernetes API server is determined by the `nodeip-configuration.service` service unit that is run by systemd when the node boots. The `nodeip-configuration.service` selects the IP from the interface associated with the default route. +[role="_abstract"] +For installations on bare metal or with virtual machines that have more than one network interface controller (NIC), the NIC that {product-title} uses for communication with the Kubernetes API server is determined by the `nodeip-configuration.service` service unit that is run by systemd when the node boots. + +The `nodeip-configuration.service` selects the IP from the interface associated with the default route. After the `nodeip-configuration.service` service determines the correct NIC, the service creates the `/etc/systemd/system/kubelet.service.d/20-nodenet.conf` file. The `20-nodenet.conf` file sets the `KUBELET_NODE_IP` environment variable to the IP address that the service selected. diff --git a/modules/nw-troubleshoot-ovs.adoc b/modules/nw-troubleshoot-ovs.adoc index f33e8007e82..b70a25cc546 100644 --- a/modules/nw-troubleshoot-ovs.adoc +++ b/modules/nw-troubleshoot-ovs.adoc @@ -6,6 +6,7 @@ [id="nw-troubleshoot-ovs_{context}"] = Troubleshooting Open vSwitch issues +[role="_abstract"] To troubleshoot some Open vSwitch (OVS) issues, you might need to configure the log level to include more information. If you modify the log level on a node temporarily, be aware that you can receive log messages from the machine config daemon on the node like the following example: diff --git a/modules/obfuscating-dvo-data.adoc b/modules/obfuscating-dvo-data.adoc index bb7ced3b1ac..5321cf93ddf 100644 --- a/modules/obfuscating-dvo-data.adoc +++ b/modules/obfuscating-dvo-data.adoc @@ -6,7 +6,9 @@ [id="obfuscating-deployment-validation-operator-data_{context}"] = Obfuscating Deployment Validation Operator data -By default, when you install the Deployment Validation Operator (DVO), the name and unique identifier (UID) of a resource are included in the data that is captured and processed by the {insights-operator} for {product-title}. +[role="_abstract"] +By default, when you install the Deployment Validation Operator (DVO), the name and unique identifier (UID) of a resource are included in the data that is captured and processed by the {insights-operator} for {product-title}. + If you are a cluster administrator, you can configure the {insights-operator} to obfuscate data from the Deployment Validation Operator (DVO). For example, you can obfuscate workload names in the archive file that is then sent to Red{nbsp}Hat. diff --git a/modules/olm-cs-status-cli.adoc b/modules/olm-cs-status-cli.adoc index c0f5071dc17..633caf3b678 100644 --- a/modules/olm-cs-status-cli.adoc +++ b/modules/olm-cs-status-cli.adoc @@ -14,6 +14,7 @@ endif::[] [id="olm-cs-status-cli_{context}"] = Viewing Operator catalog source status by using the CLI +[role="_abstract"] You can view the status of an Operator catalog source by using the CLI. .Prerequisites diff --git a/modules/olm-refresh-subs.adoc b/modules/olm-refresh-subs.adoc index d32453197dd..7bfe56f26d8 100644 --- a/modules/olm-refresh-subs.adoc +++ b/modules/olm-refresh-subs.adoc @@ -7,6 +7,7 @@ [id="olm-refresh-subs_{context}"] = Refreshing failing subscriptions +[role="_abstract"] In Operator Lifecycle Manager (OLM), if you subscribe to an Operator that references images that are not accessible on your network, you can find jobs in the `openshift-marketplace` namespace that are failing with the following errors: [source,terminal] diff --git a/modules/olm-reinstall.adoc b/modules/olm-reinstall.adoc index 413af11bdbd..e4d49eff844 100644 --- a/modules/olm-reinstall.adoc +++ b/modules/olm-reinstall.adoc @@ -6,9 +6,11 @@ [id="olm-reinstall_{context}"] = Reinstalling Operators after failed uninstallation +[role="_abstract"] You must successfully and completely uninstall an Operator prior to attempting to reinstall the same Operator. Failure to fully uninstall the Operator properly can leave resources, such as a project or namespace, stuck in a "Terminating" state and cause "error resolving resource" messages. For example: -.Example `Project` resource description +**Example `Project` resource description** + ---- ... message: 'Failed to delete all resource types, 1 remaining: Internal error occurred: diff --git a/modules/olm-status-conditions.adoc b/modules/olm-status-conditions.adoc index 7902523cb81..9596e6656e0 100644 --- a/modules/olm-status-conditions.adoc +++ b/modules/olm-status-conditions.adoc @@ -7,6 +7,7 @@ [id="olm-status-conditions_{context}"] = Operator subscription condition types +[role="_abstract"] Subscriptions can report the following condition types: .Subscription condition types diff --git a/modules/olm-status-viewing-cli.adoc b/modules/olm-status-viewing-cli.adoc index 791bbaad3d7..d6398561d55 100644 --- a/modules/olm-status-viewing-cli.adoc +++ b/modules/olm-status-viewing-cli.adoc @@ -7,6 +7,7 @@ [id="olm-status-viewing-cli_{context}"] = Viewing Operator subscription status by using the CLI +[role="_abstract"] You can view Operator subscription status by using the CLI. .Prerequisites @@ -55,7 +56,7 @@ Conditions: Type: CatalogSourcesUnhealthy # ... ---- - ++ [NOTE] ==== Default {product-title} cluster Operators are managed by the Cluster Version Operator (CVO) and they do not have a `Subscription` object. Application Operators are managed by Operator Lifecycle Manager (OLM) and they have a `Subscription` object. diff --git a/modules/osd-on-gcp-troubleshoot-cluster-install.adoc b/modules/osd-on-gcp-troubleshoot-cluster-install.adoc index 2bf3ef6af86..6009ef7302d 100644 --- a/modules/osd-on-gcp-troubleshoot-cluster-install.adoc +++ b/modules/osd-on-gcp-troubleshoot-cluster-install.adoc @@ -6,6 +6,7 @@ [id="osd-on-gcp-troubleshoot-cluster-install_{context}"] = Troubleshooting {product-title} on {gcp-short} installation error codes +[role="_abstract"] The following table lists {product-title} on {gcp-first} installation error codes and what you can do to resolve these errors. .{product-title} on {gcp-short} installation error codes diff --git a/modules/querying-bootstrap-node-journal-logs.adoc b/modules/querying-bootstrap-node-journal-logs.adoc index cddc6b3acee..fb532f1571a 100644 --- a/modules/querying-bootstrap-node-journal-logs.adoc +++ b/modules/querying-bootstrap-node-journal-logs.adoc @@ -6,6 +6,7 @@ [id="querying-bootstrap-node-journal-logs_{context}"] = Querying bootstrap node journal logs +[role="_abstract"] If you experience bootstrap-related issues, you can gather `bootkube.service` `journald` unit logs and container logs from the bootstrap node. .Prerequisites diff --git a/modules/querying-cluster-node-journal-logs.adoc b/modules/querying-cluster-node-journal-logs.adoc index 83b34cb73b7..042095e07c9 100644 --- a/modules/querying-cluster-node-journal-logs.adoc +++ b/modules/querying-cluster-node-journal-logs.adoc @@ -7,6 +7,7 @@ [id="querying-cluster-node-journal-logs_{context}"] = Querying cluster node journal logs +[role="_abstract"] You can gather `journald` unit logs and other logs within `/var/log` on individual cluster nodes. .Prerequisites diff --git a/modules/querying-kubelet-status-on-a-node.adoc b/modules/querying-kubelet-status-on-a-node.adoc index 24e0a601734..a8e6d65bb1e 100644 --- a/modules/querying-kubelet-status-on-a-node.adoc +++ b/modules/querying-kubelet-status-on-a-node.adoc @@ -6,6 +6,7 @@ [id="querying-kubelet-status-on-a-node_{context}"] = Querying the kubelet's status on a node +[role="_abstract"] You can review cluster node health status, resource consumption statistics, and node logs. Additionally, you can query `kubelet` status on individual nodes. .Prerequisites diff --git a/modules/querying-operator-pod-status.adoc b/modules/querying-operator-pod-status.adoc index ce32a1aa763..7ab890d536e 100644 --- a/modules/querying-operator-pod-status.adoc +++ b/modules/querying-operator-pod-status.adoc @@ -6,6 +6,7 @@ [id="querying-operator-pod-status_{context}"] = Querying Operator pod status +[role="_abstract"] You can list Operator pods within a cluster and their status. You can also collect a detailed Operator pod summary. .Prerequisites diff --git a/modules/querying-operator-status-after-installation.adoc b/modules/querying-operator-status-after-installation.adoc index cb077626d6b..4fd1f77ad41 100644 --- a/modules/querying-operator-status-after-installation.adoc +++ b/modules/querying-operator-status-after-installation.adoc @@ -6,6 +6,7 @@ [id="querying-operator-status-after-installation_{context}"] = Querying Operator status after installation +[role="_abstract"] You can check Operator status at the end of an installation. Retrieve diagnostic data for Operators that do not become available. Review logs for any Operator pods that are listed as `Pending` or have an error status. Validate base images used by problematic pods. .Prerequisites @@ -39,17 +40,18 @@ $ oc get csr [source,terminal] ---- NAME AGE REQUESTOR CONDITION -csr-8b2br 15m system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending <1> +csr-8b2br 15m system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending csr-8vnps 15m system:serviceaccount:openshift-machine-config-operator:node-bootstrapper Pending -csr-bfd72 5m26s system:node:ip-10-0-50-126.us-east-2.compute.internal Pending <2> +csr-bfd72 5m26s system:node:ip-10-0-50-126.us-east-2.compute.internal Pending csr-c57lv 5m26s system:node:ip-10-0-95-157.us-east-2.compute.internal Pending ... ---- -<1> A client request CSR. -<2> A server request CSR. ++ +* In this example, `csr-8b2br` represents a client request CSR. +* The `csr-bfd72` represents a server request CSR. + In this example, two machines are joining the cluster. You might see more approved CSRs in the list. - ++ .. If the CSRs were not approved, after all of the pending CSRs for the machines you added are in `Pending` status, approve the CSRs for your cluster machines: + [NOTE] @@ -66,9 +68,8 @@ For clusters running on platforms that are not machine API enabled, such as bare + [source,terminal] ---- -$ oc adm certificate approve <1> +$ oc adm certificate approve ---- -<1> `` is the name of a CSR from the list of current CSRs. ** To approve all pending CSRs, run the following command: + diff --git a/modules/removing-filters-from-insights-advisor-recommendations.adoc b/modules/removing-filters-from-insights-advisor-recommendations.adoc index f2c523ab147..e5b237c7217 100644 --- a/modules/removing-filters-from-insights-advisor-recommendations.adoc +++ b/modules/removing-filters-from-insights-advisor-recommendations.adoc @@ -6,6 +6,7 @@ [id="removing-filters-from-insights-recommendations_{context}"] = Removing filters from {red-hat-lightspeed} advisor service recommendations +[role="_abstract"] You can apply multiple filters to the list of recommendations. When ready, you can remove them individually or completely reset them. .Procedure diff --git a/modules/reviewing-node-status-usage-and-configuration.adoc b/modules/reviewing-node-status-usage-and-configuration.adoc index fb37331cecb..c285b4629af 100644 --- a/modules/reviewing-node-status-usage-and-configuration.adoc +++ b/modules/reviewing-node-status-usage-and-configuration.adoc @@ -6,6 +6,7 @@ [id="reviewing-node-status-use-and-configuration_{context}"] = Reviewing node status, resource usage, and configuration +[role="_abstract"] Review cluster node health status, resource consumption statistics, and node logs. Additionally, query `kubelet` status on individual nodes. .Prerequisites diff --git a/modules/reviewing-pod-status.adoc b/modules/reviewing-pod-status.adoc index adaf100a335..067da8cba1d 100644 --- a/modules/reviewing-pod-status.adoc +++ b/modules/reviewing-pod-status.adoc @@ -6,6 +6,7 @@ [id="reviewing-pod-status_{context}"] = Reviewing pod status +[role="_abstract"] You can query pod status and error states. You can also query a pod's associated deployment configuration and review base image availability. .Prerequisites diff --git a/modules/rosa-hcp-no-console-access.adoc b/modules/rosa-hcp-no-console-access.adoc index 656fe1d9696..ea1decada51 100644 --- a/modules/rosa-hcp-no-console-access.adoc +++ b/modules/rosa-hcp-no-console-access.adoc @@ -5,9 +5,14 @@ [id="rosa-hcp-no-console-access_{context}"] = Troubleshooting access to {hybrid-console} -In {product-title} clusters, the {product-title} OAuth server is hosted in the Red Hat service's AWS account while the web console service is published using the cluster's default ingress controller in the cluster's AWS account. If you can log in to your cluster using the OpenShift CLI (oc) but cannot access the {product-title} web console, verify the following criteria are met: +[role="_abstract"] +In {product-title} clusters, the {product-title} OAuth server is hosted in the Red Hat service's AWS account while the web console service is published by using the cluster's default ingress controller in the cluster's AWS account. -* The console workloads are running. -* The default ingress controller's load balancer is active. -* You are accessing the console from a machine that has network connectivity to the cluster's VPC network. +If you can log in to your cluster by using the OpenShift CLI (oc) but cannot access the {product-title} web console, verify the following criteria are met: + +.Procedure + +* Verify the console workloads are running. +* Verify the default ingress controller's load balancer is active. +* Verify you are accessing the console from a machine that has network connectivity to the cluster's VPC network. diff --git a/modules/rosa-hcp-private-ready-no-console-access.adoc b/modules/rosa-hcp-private-ready-no-console-access.adoc index 67b9afd3063..26c2e6fd404 100644 --- a/modules/rosa-hcp-private-ready-no-console-access.adoc +++ b/modules/rosa-hcp-private-ready-no-console-access.adoc @@ -5,8 +5,11 @@ [id="rosa-hcp-private-ready-no-console-access_{context}"] = Verifying access to {hybrid-console} for private {product-title} clusters +[role="_abstract"] The console of the private cluster is private by default. During cluster installation, the default Ingress Controller managed by OpenShift's Ingress Operator is configured with an internal AWS Network Load Balancer (NLB). -If your private {product-title} cluster shows a `ready` status but you cannot access the {product-title} web console for the cluster, try accessing the cluster console from either within the cluster VPC or from a network that is connected to the VPC. +.Procedure + +* If your private {product-title} cluster shows a `ready` status but you cannot access the {product-title} web console for the cluster, try accessing the cluster console from either within the cluster VPC or from a network that is connected to the VPC. diff --git a/modules/rosa-hcp-ready-no-console-access.adoc b/modules/rosa-hcp-ready-no-console-access.adoc index 356af272437..01656afe24a 100644 --- a/modules/rosa-hcp-ready-no-console-access.adoc +++ b/modules/rosa-hcp-ready-no-console-access.adoc @@ -5,8 +5,13 @@ [id="rosa-hcp-ready-no-console-access_{context}"] = Verifying access to {product-title} web console for {product-title} cluster in ready state -{product-title} clusters return a `ready` status when the control plane hosted in the {product-title} service account becomes ready. Cluster console workloads are deployed on the cluster's worker nodes. The {product-title} web console will not be available and accessible until the worker nodes have joined the cluster and console workloads are running. +[role="_abstract"] +{product-title} clusters return a `ready` status when the control plane hosted in the {product-title} service account becomes ready. Cluster console workloads are deployed on the cluster's worker nodes. -If your {product-title} cluster is ready but you are unable to access the {product-title} web console for the cluster, wait for the worker nodes to join the cluster and retry accessing the console. +The {product-title} web console will not be available and accessible until the worker nodes have joined the cluster and console workloads are running. +.Procedure + +* If your {product-title} cluster is ready but you are unable to access the {product-title} web console for the cluster, wait for the worker nodes to join the cluster and retry accessing the console. ++ You can either log in to the {product-title} cluster or use the `rosa describe machinepool` command in the `rosa` CLI watch the nodes. diff --git a/modules/rosa-sts-ocm-and-user-role-troubleshooting.adoc b/modules/rosa-sts-ocm-and-user-role-troubleshooting.adoc index ea557028cc1..d9b739495b3 100644 --- a/modules/rosa-sts-ocm-and-user-role-troubleshooting.adoc +++ b/modules/rosa-sts-ocm-and-user-role-troubleshooting.adoc @@ -6,15 +6,8 @@ [id="rosa-sts-ocm-roles-and-permissions-troubleshooting_{context}"] = Resolving issues with ocm-roles and user-role IAM resources -You may receive an error when trying to create a cluster using the {product-title} (ROSA) CLI, `rosa`. - -.Example output -[source,terminal] ----- -E: Failed to create cluster: The sts_user_role is not linked to account '1oNl'. Please create a user role and link it to the account. ----- - -This error means that the `user-role` IAM role is not linked to your AWS account. The most likely cause of this error is that another user in your Red{nbsp}Hat organization created the `ocm-role` IAM role. Your `user-role` IAM role needs to be created. +[role="_abstract"] +You might receive an error when trying to create a cluster by using the {rosa-cli-first}. This error means that the `user-role` IAM role is not linked to your AWS account. The most likely cause of this error is that another user in your Red{nbsp}Hat organization created the `ocm-role` IAM role. Your `user-role` IAM role needs to be created. [NOTE] ==== @@ -22,6 +15,7 @@ After any user sets up an `ocm-role` IAM resource linked to a Red{nbsp}Hat accou ==== .Procedure + * Assess the status of your `ocm-role` and `user-role` IAM roles with the following commands: + [source,terminal] @@ -30,7 +24,6 @@ $ rosa list ocm-role ---- + .Example output -+ [source,terminal] ---- I: Fetching ocm roles @@ -44,12 +37,11 @@ $ rosa list user-role ---- + .Example output -+ [source,terminal] ---- I: Fetching user roles ROLE NAME ROLE ARN LINKED ManagedOpenShift-User.osdocs-Role arn:aws:iam::2066:role/ManagedOpenShift-User.osdocs-Role Yes ---- - ++ With the results of these commands, you can create and link the missing IAM resources. diff --git a/modules/rosa-troubleshoot-hcp-install.adoc b/modules/rosa-troubleshoot-hcp-install.adoc index d65fb41b658..159ce99d048 100644 --- a/modules/rosa-troubleshoot-hcp-install.adoc +++ b/modules/rosa-troubleshoot-hcp-install.adoc @@ -6,6 +6,7 @@ [id="rosa-troubleshoot-hcp-install_{context}"] = Troubleshooting {product-title} installation error codes +[role="_abstract"] The following table lists {product-title} installation error codes and what you can do to troubleshoot these errors. .{product-title} installation error codes @@ -47,7 +48,7 @@ For more information about {product-title} IAM role resources, see _ROSA IAM rol | OCM5007 | Unable to create AWS STS prerequisites for the cluster. -| Verify that account and operator roles have been created and are correct. For more information, see _AWS STS and ROSA with HCP explained_ in the _Additional resources_ section. +| Verify that account and Operator roles have been created and are correct. For more information, see _AWS STS and ROSA with HCP explained_ in the _Additional resources_ section. | OCM5008 | The provided cluster flavour is incorrect. diff --git a/modules/rosa-troubleshooting-awsapiratelimitexceeded-failure-deployment.adoc b/modules/rosa-troubleshooting-awsapiratelimitexceeded-failure-deployment.adoc index a9856f2f278..23f4940238d 100644 --- a/modules/rosa-troubleshooting-awsapiratelimitexceeded-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-awsapiratelimitexceeded-failure-deployment.adoc @@ -5,15 +5,18 @@ [id="rosa-troubleshooting-awsapiratelimitexceeded-failure-deployment_{context}"] = Troubleshooting cluster creation with an AWSAPIRateLimitExceeded error +[role="_abstract"] If a cluster creation action fails, you might receive the following error messages. -.Example install logs output +The following example shows the install logs output: + [source,terminal] ---- level=error\nlevel=error msg=Error: error waiting for Route53 Hosted Zone .* creation: timeout while waiting for state to become 'INSYNC' (last state: 'PENDING', timeout: 15m0s) ---- -.Example {cluster-manager} output +The following example shows the {cluster-manager} output: + [source,terminal] ---- Provisioning Error Code: OCM3008 diff --git a/modules/rosa-troubleshooting-awsec2quotaexceeded-failure-deployment.adoc b/modules/rosa-troubleshooting-awsec2quotaexceeded-failure-deployment.adoc index ea73bf9da2c..1b98aadaaa3 100644 --- a/modules/rosa-troubleshooting-awsec2quotaexceeded-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-awsec2quotaexceeded-failure-deployment.adoc @@ -5,9 +5,11 @@ [id="rosa-troubleshooting-awsec2quotaexceeded-failure-deployment_{context}"] = Troubleshooting cluster creation with an AWSEC2QuotaExceeded error +[role="_abstract"] If a cluster creation action fails, you might receive the following error message. -.Example output +The following example shows the output: + [source,terminal] ---- Provisioning Error Code: OCM3042 @@ -18,21 +20,21 @@ This error indicates that you have reached the EC2 quota limit for the region me .Procedure -Request a quota increase from AWS or delete unused EC2 instances. - -* Request a quota increase from AWS. +* To fix this issue, try one of the following methods: ++ +** Request a quota increase from AWS: .. Sign in to the link:https://aws.amazon.com/console/[AWS Management Console]. .. Click your user name and select **Service Quotas**. .. Under **Manage quotas**, select an AWS service to view available quotas. .. If the quota is adjustable, you can choose the button or the name, and then choose **Request quota increase**. - -* Delete unused EC2 instances using the console. ++ +** Delete unused EC2 instances using the console: .. Before you delete an EC2 instance, verify your data by checking that your Amazon EBS volumes will still exist after you delete the unused EC2 instances. .. Ensure you have copied any data that you need from your instance store volumes to persistent storage, such as Amazon EBS or Amazon S3. .. If you have a CNAME record for your domain that points to your load balancer, point it to a new location and wait for the DNS change to take effect before deleting your load balancer. .. Open the link:https://console.aws.amazon.com/ec2/[Amazon EC2 console]. .. On the navigation pane, choose **Instances**. -.. Select the instance, and choose **Terminate instance**. +.. Select the instance, and choose **Stop instance**. diff --git a/modules/rosa-troubleshooting-awsinsufficientcapacity-failure-deployment.adoc b/modules/rosa-troubleshooting-awsinsufficientcapacity-failure-deployment.adoc index 586ef562aff..4d88c3c5325 100644 --- a/modules/rosa-troubleshooting-awsinsufficientcapacity-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-awsinsufficientcapacity-failure-deployment.adoc @@ -5,9 +5,11 @@ [id="rosa-troubleshooting-awsinsufficientcapacity-failure-deployment_{context}"] = Troubleshooting cluster creation with an AWSInsufficientCapacity error -If a cluster creation action fails, you might receive the following error message. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message. + +For example: -.Example output [source,terminal] ---- Provisioning Error Code: OCM3052 diff --git a/modules/rosa-troubleshooting-awsinsufficientpermission-failure-deployment.adoc b/modules/rosa-troubleshooting-awsinsufficientpermission-failure-deployment.adoc index 90f85ae9b36..3f47670bf92 100644 --- a/modules/rosa-troubleshooting-awsinsufficientpermission-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-awsinsufficientpermission-failure-deployment.adoc @@ -5,9 +5,11 @@ [id="rosa-troubleshooting-awsinsufficientpermission-failure-deployment_{context}"] = Troubleshooting cluster creation with an AWSInsufficientPermissions error +[role="_abstract"] If a cluster creation action fails, you might receive the following error message. -.Example {cluster-manager} output +The following example shows the {cluster-manager} output: + [source,terminal] ---- Provisioning Error Code: OCM3033 @@ -18,9 +20,14 @@ This error indicates that the cluster installation is blocked due to missing or .Procedure -Ensure that the prerequisites are met by reviewing _Detailed requirements for deploying ROSA (classic architecture) using STS_ or _Deploying ROSA without AWS STS_ in _Additional resources_ depending on your choice of credential mode for installing clusters. - -include::snippets/snip_rosa-sts.adoc[] +. Ensure that the prerequisites are met by reviewing _Detailed requirements for deploying ROSA (classic architecture) using STS_ or _Deploying ROSA without AWS STS_ in _Additional resources_ depending on your choice of credential mode for installing clusters. ++ +[TIP] +==== +[role="_abstract"] +AWS Security Token Service (STS) is the recommended credential mode for installing and interacting with clusters on {product-title} because it provides enhanced security. +==== ++ . If needed, you can re-create the permissions and policies by using the `-f` flag: + [source,terminal] @@ -43,7 +50,7 @@ $ rosa create account-roles -f $ rosa create operator-roles -c ${CLUSTER} -f ---- -. Validate all the prerequisites and attempt cluster reinstallation. +. Validate all the prerequisites and attempt cluster re-installation. diff --git a/modules/rosa-troubleshooting-awsnatgatewaylimitexceeded-failure-deployment.adoc b/modules/rosa-troubleshooting-awsnatgatewaylimitexceeded-failure-deployment.adoc index 5c0506f35d7..8a5d78ecbe4 100644 --- a/modules/rosa-troubleshooting-awsnatgatewaylimitexceeded-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-awsnatgatewaylimitexceeded-failure-deployment.adoc @@ -5,15 +5,18 @@ [id="rosa-troubleshooting-awsnatgatewaylimitexceeded-failure-deployment_{context}"] = Troubleshooting cluster creation with an AWSNATGatewayLimitExceeded error -If a cluster creation action fails, you might receive the following error messages. +[role="_abstract"] +If a cluster creation action fails, you might receive an error messages. + +The following example shows the install logs output: -.Example install logs output [source,terminal] ---- Failed to create cluster: Error creating NAT Gateway: NatGatewayLimitExceeded: Performing this operation would exceed the limit of 5 NAT gateways. ---- -.Example {cluster-manager} output +The following example shows the {cluster-manager} output: + [source,terminal] ---- Provisioning Error Code: OCM3019 @@ -24,11 +27,8 @@ This error indicates that you have reached the quota for the number of NAT gatew .Procedure -. To fix this issue, try one of the following methods: - -* Request an increase in the **NAT gateways per Availability Zone quota** page by using the **Service Quotas** console (AWS). - -* Check the status of your NAT gateway. A status of `Pending`, `Available`, or `Deleting` counts against your quota. If you have recently deleted a NAT gateway, wait a few minutes for the status to go from `Deleting` to `Deleted`. Then try creating a new NAT gateway. - -* If you do not need your NAT gateway in a specific availability zone, try creating a NAT gateway in an availability zone where you have not reached your quota. +* To fix this issue, try one of the following methods: +** Request an increase in the **NAT gateways per Availability Zone quota** page by using the **Service Quotas** console (AWS). +** Check the status of your NAT gateway. A status of `Pending`, `Available`, or `Deleting` counts against your quota. If you have recently deleted a NAT gateway, wait a few minutes for the status to go from `Deleting` to `Deleted`. Then try creating a new NAT gateway. +** If you do not need your NAT gateway in a specific availability zone, try creating a NAT gateway in an availability zone where you have not reached your quota. diff --git a/modules/rosa-troubleshooting-awssubnetnotexist-failure-deployment.adoc b/modules/rosa-troubleshooting-awssubnetnotexist-failure-deployment.adoc index a59fc33274c..eccf7e1bcd0 100644 --- a/modules/rosa-troubleshooting-awssubnetnotexist-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-awssubnetnotexist-failure-deployment.adoc @@ -5,15 +5,18 @@ [id="rosa-troubleshooting-awssubnetnotexist-failure-deployment_{context}"] = Troubleshooting cluster creation with an AWSSubnetDoesNotExist error -If a cluster creation action fails, you can receive the following error messages. +[role="_abstract"] +If a cluster creation action fails, you can receive an error messages. + +The following example shows the install logs output: -.Example install logs output [source,terminal] ---- The subnet ID 'subnet-' does not exist. ---- -.Example {cluster-manager} output +The following example shows the {cluster-manager} output: + [source,terminal] ---- Provisioning Error Code: OCM3032 @@ -27,6 +30,6 @@ This error indicates that the cluster installation is blocked by an invalid subn * Check your subnets provided in the `platform.aws.subnets` parameter during installation. The subnets must be a part of the same machine Network CIDR ranges that you specify. ** For a standard cluster, specify a public and a private subnet for each availability zone. ** For a private cluster, specify a private subnet for each availability zone. - ++ For more information about AWS VPC and subnet requirements and optional parameters, see the _VPC_ section in the _AWS prerequisites for ROSA_ guide. diff --git a/modules/rosa-troubleshooting-awsvpclimit-failure-deployment.adoc b/modules/rosa-troubleshooting-awsvpclimit-failure-deployment.adoc index 55926747357..4a821013a86 100644 --- a/modules/rosa-troubleshooting-awsvpclimit-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-awsvpclimit-failure-deployment.adoc @@ -5,9 +5,11 @@ [id="rosa-troubleshooting-awsvpclimit-failure-deployment_{context}"] = Troubleshooting cluster creation with an AWSVPCLimitExceeded error -If a cluster creation action fails, you might receive the following error message. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message. + +The following example shows the {cluster-manager} output: -.Example {cluster-manager} output [source,terminal] ---- Provisioning Error Code: OCM3013 @@ -18,19 +20,19 @@ This error indicates that you have reached the quota for the number of VPCs. .Procedure -Request a quota increase from AWS or delete unused VPCs. - -* Request a quota increase from AWS. +* To fix this issue, try one of the following methods: ++ +* Request a quota increase from AWS: .. Sign in to the link:https://aws.amazon.com/console/[AWS Management Console]. .. Click your user name and select **Service Quotas**. .. Under **Manage quotas**, select a service to view available quotas. .. If the quota is adjustable, you can choose the button or the name, and then choose **Request increase**. .. For **Increase quota value**, enter the new value. The new value must be greater than the current value. .. Choose **Request**. - -* Clean unused VPCs. Before you can delete a VPC, you must first terminate or delete any resources that created a requester-managed network interface in the VPC. For example, you must terminate your EC2 instances and delete your load balancers, NAT gateways, transit gateways, and interface VPC endpoints before deleting a VPC. ++ +* Clean unused VPCs. Before you can delete a VPC, you must first stop or delete any resources that created a requester-managed network interface in the VPC. For example, you must stop your EC2 instances and delete your load balancers, NAT gateways, transit gateways, and interface VPC endpoints before deleting a VPC: .. Sign in to the link:https://console.aws.amazon.com/ec2/[AWS EC2 console]. -.. Terminate all instances in the VPC. For more information, see link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html[Terminate Amazon EC2 instances]. +.. Stop all instances in the VPC. For more information, see link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html[Stop Amazon EC2 instances]. .. Open the link:https://console.aws.amazon.com/vpc[Amazon VPC console]. .. In the navigation pane, choose **Your VPCs**. .. Select the VPC to delete and choose **Actions, Delete VPC**. diff --git a/modules/rosa-troubleshooting-cluster-deletion.adoc b/modules/rosa-troubleshooting-cluster-deletion.adoc index 29247cf04c2..ca7e730debc 100644 --- a/modules/rosa-troubleshooting-cluster-deletion.adoc +++ b/modules/rosa-troubleshooting-cluster-deletion.adoc @@ -5,7 +5,8 @@ [id="rosa-troubleshooting-cluster-deletion_{context}"] = Repairing a cluster that cannot be deleted -In specific cases, the following error appears in {cluster-manager-url} if you attempt to delete your cluster. +[role="_abstract"] +In specific cases, the following error is displayed in {cluster-manager-url} if you attempt to delete your cluster: [source,terminal] ---- @@ -15,7 +16,7 @@ CLUSTERS-MGMT-400: Failed to delete cluster : sts_user_role is not linked Operation ID: b0572d6e-fe54-499b-8c97-46bf6890011c ---- -If you try to delete your cluster from the CLI, the following error appears. +If you try to delete your cluster from the CLI, the following error is displayed: [source,terminal] ---- diff --git a/modules/rosa-troubleshooting-deleteiamrole-deployment.adoc b/modules/rosa-troubleshooting-deleteiamrole-deployment.adoc index b55a692d05f..d2b201c8da8 100644 --- a/modules/rosa-troubleshooting-deleteiamrole-deployment.adoc +++ b/modules/rosa-troubleshooting-deleteiamrole-deployment.adoc @@ -5,27 +5,27 @@ [id="rosa-troubleshooting-deleteiamrole-deployment_{context}"] = Troubleshooting cluster creation with a DeletingIAMRole error -If a cluster creation action fails, you might receive the following error message. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message: -.Example output [source,terminal] ---- OCM3031: Error deleting IAM Role (role-name): DeleteConflict: Cannot delete entity, must detach all policies first.\nlevel=error msg=\tstatus code: 409 ---- + The cluster's installation was blocked as the cluster installer was not able to delete the roles it used during the installation. .Procedure -To unblock the cluster installation, ensure that no policies are added to new roles by default. - -* Run the following command to list all managed policies that are attached to the specified role: +* To unblock the cluster installation, ensure that no policies are added to new roles by default by running the following command to list all managed policies that are attached to the specified role: + [source,terminal] ---- $ aws iam list-attached-role-policies --role-name ---- + -.Example output +This command returns output similar to the following: ++ [source,terminal] ---- { @@ -38,8 +38,7 @@ $ aws iam list-attached-role-policies --role-name "IsTruncated": false } ---- - + If there are no policies attached to the specified role (or none that match the specified path prefix), the command returns an empty list. - ++ For more information about the list-attached-role-policies command, see link:https://docs.aws.amazon.com/cli/latest/reference/iam/list-attached-role-policies.html[list-attached-role-policies] in the official AWS documentation. diff --git a/modules/rosa-troubleshooting-elb-service-role.adoc b/modules/rosa-troubleshooting-elb-service-role.adoc index 64783c1be89..beca5ffbed2 100644 --- a/modules/rosa-troubleshooting-elb-service-role.adoc +++ b/modules/rosa-troubleshooting-elb-service-role.adoc @@ -5,7 +5,10 @@ [id="rosa-troubleshooting-elb-service-role_{context}"] = Creating the Elastic Load Balancing (ELB) service-linked role -If you have not created a load balancer in your AWS account, it is possible that the service-linked role for Elastic Load Balancing (ELB) might not exist yet. You may receive the following error: +[role="_abstract"] +If you have not created a load balancer in your AWS account, it is possible that the service-linked role for Elastic Load Balancing (ELB) might not exist yet. + +You might receive the following error: [source,terminal] ---- diff --git a/modules/rosa-troubleshooting-expired-token.adoc b/modules/rosa-troubleshooting-expired-token.adoc index 957e0e96389..7846d6c0e0e 100644 --- a/modules/rosa-troubleshooting-expired-token.adoc +++ b/modules/rosa-troubleshooting-expired-token.adoc @@ -8,9 +8,11 @@ [id="rosa-troubleshooting-expired-offline-access-tokens_{context}"] = Troubleshooting expired offline access tokens -If you use the {product-title} (ROSA) CLI, `rosa`, and your api.openshift.com offline access token expires, an error message appears. This happens when sso.redhat.com invalidates the token. +[role="_abstract"] +If you use the {product-title} (ROSA) CLI, `rosa`, and your api.openshift.com offline access token expires, an error message is displayed. This happens when sso.redhat.com invalidates the token. + +The following example shows the output: -.Example output [source,terminal] ---- Can't get tokens .... @@ -18,6 +20,4 @@ Can't get access tokens .... ---- .Procedure -* Generate a new offline access token at the following URL. A new offline access token is generated every time you visit the URL. - -** {product-title} (ROSA): https://console.redhat.com/openshift/token/rosa +* Generate a new offline access token at the following URL. The {cluster-manager-url} URL generates a new offline access token every time you visit it. diff --git a/modules/rosa-troubleshooting-general-deployment.adoc b/modules/rosa-troubleshooting-general-deployment.adoc index 524c6c6a5ad..f1b2208a707 100644 --- a/modules/rosa-troubleshooting-general-deployment.adoc +++ b/modules/rosa-troubleshooting-general-deployment.adoc @@ -5,6 +5,7 @@ [id="rosa-troubleshooting-general-deployment-failure_{context}"] = Obtaining information about a failed cluster +[role="_abstract"] If a cluster deployment fails, the cluster is put into an "error" state. .Procedure diff --git a/modules/rosa-troubleshooting-installing.adoc b/modules/rosa-troubleshooting-installing.adoc index ebbfad5e683..3dc28cd359a 100644 --- a/modules/rosa-troubleshooting-installing.adoc +++ b/modules/rosa-troubleshooting-installing.adoc @@ -6,35 +6,34 @@ [id="rosa-troubleshooting-installing_{context}"] = Installation troubleshooting -[id="rosa-troubleshooting-install-uninstall-logs_{context}"] -== Inspect install or uninstall logs +[role="_abstract"] +This procedure describes how to troubleshoot installation issues for {product-title} clusters. -To display install logs: +.Procedure -* Run the following command, replacing `` with the name of your cluster: +* Inspect install or uninstall logs: +** To display install logs, run the following command, replacing `` with the name of your cluster: + [source,terminal] ---- $ rosa logs install --cluster= ---- + -* To watch the logs, include the `--watch` flag: +** To watch the logs, include the `--watch` flag: + [source,terminal] ---- $ rosa logs install --cluster= --watch ---- - -To display uninstall logs: - -* Run the following command, replacing `` with the name of your cluster: ++ +** To display uninstall logs, run the following command, replacing `` with the name of your cluster: + [source,terminal] ---- $ rosa logs uninstall --cluster= ---- + -* To watch the logs, include the `--watch` flag: +** To watch the logs, include the `--watch` flag: + [source,terminal] ---- @@ -42,36 +41,33 @@ $ rosa logs uninstall --cluster= --watch ---- ifndef::openshift-rosa-hcp[] -[id="rosa-faq-verify-permissions-for-clusters-without-sts_{context}"] -== Verify your AWS account permissions for clusters without STS - +* Verify your AWS account permissions for clusters without STS: ++ Run the following command to verify if your AWS account has the correct permissions. This command verifies permissions only for clusters that do not use the AWS Security Token Service (STS): - ++ [source,terminal] ---- $ rosa verify permissions ---- - ++ If you receive any errors, double check to ensure than an link:https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_type-auth.html#orgs_manage_policies_scp[SCP] is not applied to your AWS account. If you are required to use an SCP, see link:https://www.openshift.com/dedicated/ccs#scp[Red{nbsp}Hat Requirements for Customer Cloud Subscriptions] for details on the minimum required SCP. endif::openshift-rosa-hcp[] -[id="rosa-faq-verify-aws-quota_{context}"] -== Verify your AWS account and quota - +* Verify your AWS account and quota: ++ Run the following command to verify you have the available quota on your AWS account: - ++ [source,terminal] ---- $ rosa verify quota ---- ++ +AWS quotas change based on region. Be sure you are verifying your quota for the correct AWS region. If you need to increase your quota, go to your link:https://aws.amazon.com/console/[AWS console], and request a quota increase for the service that failed. -AWS quotas change based on region. Be sure you are verifying your quota for the correct AWS region. If you need to increase your quota, navigate to your link:https://aws.amazon.com/console/[AWS console], and request a quota increase for the service that failed. - -[id="rosa-faq-aws-notification-emails_{context}"] -== AWS notification emails - +* AWS notification emails: ++ When creating a cluster, the {product-title} service creates small instances in all supported regions. This check ensures the AWS account being used can deploy to each supported region. - -For AWS accounts that are not using all supported regions, AWS may send one or more emails confirming that "Your Request For Accessing AWS Resources Has Been Validated". Typically the sender of this email is aws-verification@amazon.com. - ++ +For AWS accounts that are not using all supported regions, AWS might send one or more emails confirming that "Your Request For Accessing AWS Resources Has Been Validated." Typically the sender of this email is aws-verification@amazon.com. ++ This is expected behavior as the {product-title} service is validating your AWS account configuration. diff --git a/modules/rosa-troubleshooting-invalidinstallconfigsubnet-failure-deployment.adoc b/modules/rosa-troubleshooting-invalidinstallconfigsubnet-failure-deployment.adoc index 05a77e9d037..09b2fc46ba6 100644 --- a/modules/rosa-troubleshooting-invalidinstallconfigsubnet-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-invalidinstallconfigsubnet-failure-deployment.adoc @@ -5,28 +5,30 @@ [id="rosa-troubleshooting-invalidinstallconfigsubnet-failure-deployment_{context}"] = Troubleshooting cluster creation with an InvalidInstallConfigSubnet error -If a cluster creation action fails, you might receive the following error messages. +[role="_abstract"] +If a cluster creation action fails, you might receive an error messages. + +The following example shows the install logs output: -.Example install logs output [source,terminal] ---- -platform.aws.subnets[1]: Invalid value: "subnet-0babad72exxxxxxxx": subnet's CIDR range start 10.69.1x.3x is outside of the specified machine networks +platform.aws.subnets[1]: Invalid value: "subnet-0babad72exxxxxxxx": subnet CIDR range start 10.69.1x.3x is outside of the specified machine networks ---- -.Example {cluster-manager} output +The following example shows the {cluster-manager} output: + [source,terminal] ---- Provisioning Error Code: OCM3020 Provisioning Error Message: Subnet CIDR ranges are outside of specified machine CIDR. ---- -These errors indicate that a subnet's CIDR range start is outside of the specified machine networks. +These errors indicate that a subnet CIDR range start is outside of the specified machine networks. .Procedure . Check your subnet configuration. -. Edit your machine CIDR range to include all subnet CIDR ranges. -Generally, your machine CIDR should match your VPC CIDR. - +. Edit your machine CIDR range to include all subnet CIDR ranges. Generally, your machine CIDR should match your VPC CIDR. ++ For more information about CIDR ranges, see _CIDR range definitions_ in the _Additional resources_ section . diff --git a/modules/rosa-troubleshooting-invalidkmskey-failure-deployment.adoc b/modules/rosa-troubleshooting-invalidkmskey-failure-deployment.adoc index 342443381eb..10a6f98cfb8 100644 --- a/modules/rosa-troubleshooting-invalidkmskey-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-invalidkmskey-failure-deployment.adoc @@ -5,15 +5,18 @@ [id="rosa-troubleshooting-invalidkmskey-failure-deployment_{context}"] = Troubleshooting cluster creation with an invalidKMSKey error -If a cluster creation action fails, you might receive the following error messages. +[role="_abstract"] +If a cluster creation action fails, you might receive an error messages. + +The following example shows the install logs output: -.Example install logs output [source,terminal] ---- Client.InvalidKMSKey.InvalidState: The KMS key provided is in an incorrect state ---- -.Example {cluster-manager} output +The following example shows the {cluster-manager} output: + [source,terminal] ---- Provisioning Error Code: OCM3055 diff --git a/modules/rosa-troubleshooting-lblimitexceeded-failure-deployment.adoc b/modules/rosa-troubleshooting-lblimitexceeded-failure-deployment.adoc index 56cde7b4022..23d8e69fa60 100644 --- a/modules/rosa-troubleshooting-lblimitexceeded-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-lblimitexceeded-failure-deployment.adoc @@ -5,9 +5,11 @@ [id="rosa-troubleshooting-lblimitexceeded-failure-deployment_{context}"] = Troubleshooting cluster creation with an ALoadBalancerLimitExceeded error -If a cluster creation action fails, you might receive the following error message. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message. + +For example: -.Example output [source,terminal] ---- Provisioning Error Code: OCM3036 @@ -18,18 +20,17 @@ This error indicates that you have reached the quota for the number of load bala .Procedure -Request a quota increase from AWS or delete unused load balancers. - -* Request a quota increase from AWS. +* To fix this issue, try one of the following methods: ++ +** Request a quota increase from AWS: .. Sign in to the link:https://aws.amazon.com/console/[AWS Management Console]. .. Click your user name and select **Service Quotas**. .. Under **Manage quotas**, select a service to view available quotas. .. If the quota is adjustable, you can choose the button or the name, and then choose Request quota increase. -.. If the quota is adjustable, you can choose the button or the name, and then choose Request quota increase. .. For **Change quota value**, enter the new value. The new value must be greater than the current value. .. Choose **Request**. - -* Delete a load balancer using the console. ++ +** Delete a load balancer using the console: .. If you have a CNAME record for your domain that points to your load balancer, point it to a new location and wait for the DNS change to take effect before deleting your load balancer. .. Open the link:https://console.aws.amazon.com/ec2/[Amazon EC2 console]. .. On the navigation pane, under **LOAD BALANCING**, choose **Load Balancers**. diff --git a/modules/rosa-troubleshooting-multipleroute53zonesfound-failure-deployment.adoc b/modules/rosa-troubleshooting-multipleroute53zonesfound-failure-deployment.adoc index 1c6582d63d0..9c09dba01ac 100644 --- a/modules/rosa-troubleshooting-multipleroute53zonesfound-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-multipleroute53zonesfound-failure-deployment.adoc @@ -5,9 +5,11 @@ [id="rosa-troubleshooting-multipleroute53zonesfound-failure-deployment_{context}"] = Troubleshooting cluster creation with a MultipleRoute53ZonesFound error -If a cluster creation action fails, you might receive the following error message. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message. + +For example: -.Example output [source,terminal] ---- Provisioning Error Code: OCM3049 diff --git a/modules/rosa-troubleshooting-networking-nlb.adoc b/modules/rosa-troubleshooting-networking-nlb.adoc index 003c9eac415..f9f15113214 100644 --- a/modules/rosa-troubleshooting-networking-nlb.adoc +++ b/modules/rosa-troubleshooting-networking-nlb.adoc @@ -3,8 +3,13 @@ // * support/rosa-troubleshooting-deployments.adoc :_mod-docs-content-type: PROCEDURE [id="rosa-troubleshooting-general-deployment-failure_{context}"] -= Connectivity issues on clusters with private Network Load Balancers += Connectivity issues on clusters with private network load balancers -{product-title} clusters created with version {product-version} deploy AWS Network Load Balancers (NLB) by default for the `default` ingress controller. In the case of a private NLB, the NLB's client IP address preservation might cause connections to be dropped where the source and destination are the same host. See the AWS's documentation about how to link:https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-troubleshooting.html#loopback-timeout[Troubleshoot your Network Load Balancer]. This IP address preservation has the implication that any customer workloads cohabitating on the same node with the router pods, may not be able send traffic to the private NLB fronting the ingress controller router. +[role="_abstract"] +{product-title} clusters created with version {product-version} deploy AWS Network Load Balancers (NLB) by default for the `default` ingress controller. -To mitigate this impact, customers should reschedule their workloads onto nodes separate from those where the router pods are scheduled. Alternatively, customers should rely on the internal pod and service networks for accessing other workloads co-located within the same cluster. +In the case of a private NLB, the NLB client IP address preservation might drop connections where the source and destination are the same host. See the AWS documentation about how to link:https://docs.aws.amazon.com/elasticloadbalancing/latest/network/load-balancer-troubleshooting.html#loopback-timeout[Troubleshoot your Network Load Balancer]. This IP address preservation means that customer workloads co-located on the same node with the router pods might not be able to send traffic to the private NLB fronting the ingress controller router. + +.Procedure + +* To mitigate this impact, reschedule your workloads onto nodes separate from those where the router pods run. Or, rely on the internal pod and service networks for accessing other workloads co-located within the same cluster. diff --git a/modules/rosa-troubleshooting-osdccsadmin-deployment.adoc b/modules/rosa-troubleshooting-osdccsadmin-deployment.adoc index 7803f1c26ee..3a998eb93b1 100644 --- a/modules/rosa-troubleshooting-osdccsadmin-deployment.adoc +++ b/modules/rosa-troubleshooting-osdccsadmin-deployment.adoc @@ -5,16 +5,17 @@ [id="rosa-troubleshooting-deployment-failure-osdccsadmin_{context}"] = Troubleshooting cluster creation with an osdCcsAdmin error -If a cluster creation action fails, you might receive the following error message. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message. + +The following example shows the output: -.Example output [source,terminal] ---- Failed to create cluster: Unable to create cluster spec: Failed to get access keys for user 'osdCcsAdmin': NoSuchEntity: The user with name osdCcsAdmin cannot be found. ---- .Procedure -To fix this issue: . Delete the stack: + @@ -22,7 +23,7 @@ To fix this issue: ---- $ rosa init --delete ---- - ++ . Reinitialize your account: + [source,terminal] diff --git a/modules/rosa-troubleshooting-pendingverification-failure-deployment.adoc b/modules/rosa-troubleshooting-pendingverification-failure-deployment.adoc index 5abc19960f5..6a29babc619 100644 --- a/modules/rosa-troubleshooting-pendingverification-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-pendingverification-failure-deployment.adoc @@ -5,9 +5,11 @@ [id="rosa-troubleshooting-pendingverification-failure-deployment_{context}"] = Troubleshooting cluster creation with a PendingVerification error -If a cluster creation action fails, you might receive the following error message. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message. + +The following example shows the output: -.Example output [source,terminal] ---- Provisioning Error Code: OCM3021 @@ -16,9 +18,9 @@ Provisioning Error Message: Account pending verification for region. Verify the When creating a cluster, the {product-title} service creates small instances in all supported regions. This check ensures the AWS account being used can deploy to each supported region. -For AWS accounts that are not using all supported regions, AWS may send one or more emails confirming that "Your Request For Accessing AWS Resources Has Been Validated". Typically the sender of this email is aws-verification@amazon.com. This is expected behavior as the {product-title} service is validating your AWS account configuration. +For AWS accounts that are not using all supported regions, AWS might send one or more emails confirming that "Your Request For Accessing AWS Resources Has Been Validated". Typically the sender of this email is aws-verification@amazon.com. This is expected behavior as the {product-title} service is validating your AWS account configuration. -Normally, this validation gets completed within 15 minutes, but in some cases it can take up to 4 hours for AWS to validate. In order to attempt successful provisioning, Red{nbsp}Hat has configured our installer to reattempt installation if this issue occurs, but the installation can still fail if the validation continues to time out or if the validation itself fails. +Normally, this validation gets completed within 15 minutes, but in some cases it can take up to 4 hours for AWS to validate. To attempt successful provisioning, Red{nbsp}Hat has configured our installer to reattempt installation if this issue occurs, but the installation can still fail if the validation continues to time out or if the validation itself fails. .Procedure * Reinstall the cluster or select a different AWS region or different availability zone(s). diff --git a/modules/rosa-troubleshooting-s3bucketslimitexceeded-failure-deployment.adoc b/modules/rosa-troubleshooting-s3bucketslimitexceeded-failure-deployment.adoc index 48f0648a6b9..d9094a97d17 100644 --- a/modules/rosa-troubleshooting-s3bucketslimitexceeded-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-s3bucketslimitexceeded-failure-deployment.adoc @@ -5,15 +5,18 @@ [id="rosa-troubleshooting-s3bucketslimitexceeded_{context}"] = Troubleshooting cluster creation with an S3BucketsLimitExceeded error -If a cluster creation action fails, you might receive the following error messages. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message. + +The following example shows the install logs output: -.Example install logs output [source,terminal] ---- level=error msg="Error: Error creating S3 bucket: TooManyBuckets: You have attempted to create more buckets than allowed" ---- -.Example {cluster-manager} output +The following example shows the {cluster-manager} output: + [source,terminal] ---- Provisioning Error Code: OCM3014 @@ -24,15 +27,15 @@ This type of error indicates that you have reached the quota for the number of S .Procedure -Request a quota increase from AWS or clean unused S3 buckets. - -* Request a quota increase from AWS. +* To fix this issue, try one of the following methods: ++ +** Request a quota increase from AWS: .. Sign in to the link:https://aws.amazon.com/console/[AWS Management Console]. .. Click your user name and select **Service Quotas**. .. Under **Manage quotas**, select an AWS service to view available quotas. .. If the quota is adjustable, you can choose the button or the name, and then choose **Request quota increase**. - -* Clean unused S3 buckets. You can only delete buckets that do not have any objects in them. Make sure the bucket is empty. ++ +** Clean unused S3 buckets. You can only delete buckets that do not have any objects in them. Make sure the bucket is empty: .. Sign in to the link:https://aws.amazon.com/console/[AWS Management Console]. .. Open the **Amazon S3** console. .. In the **Buckets** list, select the option next to the name of the bucket that you want to delete, and then choose **Delete** at the top of the page. diff --git a/modules/rosa-troubleshooting-toomanyroute53zones-failure-deployment.adoc b/modules/rosa-troubleshooting-toomanyroute53zones-failure-deployment.adoc index 387e9bba0e3..f545d778e9f 100644 --- a/modules/rosa-troubleshooting-toomanyroute53zones-failure-deployment.adoc +++ b/modules/rosa-troubleshooting-toomanyroute53zones-failure-deployment.adoc @@ -5,15 +5,18 @@ [id="rosa-troubleshooting-toomanyroute53zones-failure-deployment_{context}"] = Troubleshooting cluster creation with a TooManyRoute53Zones error -If a cluster creation action fails, you might receive the following error messages. +[role="_abstract"] +If a cluster creation action fails, you might receive an error message. + +The following example shows the install logs output: -.Example install logs output [source,terminal] ---- error msg=Error: error creating Route53 Hosted Zone: TooManyHostedZones: Limits Exceeded: MAX_HOSTED_ZONES_BY_OWNER - Cannot create more hosted zones.\\nlevel=error msg=\\tstatus code: 400 ---- -.Example {cluster-manager} output +The following example shows the {cluster-manager} output: + [source,terminal] ---- Provisioning Error Code: OCM3006 @@ -26,19 +29,19 @@ The error suggests that the hosted zone quota is at capacity. By default, each A .Procedure -Request a quota increase from AWS or delete unused VPCs. - -* Request a quota increase from AWS. +* To fix this issue, try one of the following methods: ++ +** Request a quota increase from AWS: .. Sign in to the link:https://aws.amazon.com/console/[AWS Management Console]. .. Click your user name and select **Service Quotas**. .. Under **Manage quotas**, select a service to view available quotas. .. If the quota is adjustable, you can choose the button or the name, and then choose **Request increase**. .. For **Increase quota value**, enter the new value. The new value must be greater than the current value. .. Choose **Request**. - -* Delete unused VPCs. Before you can delete a VPC, you must first terminate or delete any resources that created a requester-managed network interface in the VPC. For example, you must terminate your EC2 instances and delete your load balancers, NAT gateways, transit gateways, and interface VPC endpoints. ++ +** Delete unused VPCs. Before you can delete a VPC, you must first stop or delete any resources that created a requester-managed network interface in the VPC. For example, you must stop your EC2 instances and delete your load balancers, NAT gateways, transit gateways, and interface VPC endpoints: .. Sign in to the link:https://console.aws.amazon.com/ec2/[AWS EC2 console]. -.. Terminate all instances in the VPC. For more information, see link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html[Terminate Amazon EC2 instances]. +.. Stop all instances in the VPC. For more information, see link:https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/terminating-instances.html[Stop Amazon EC2 instances]. .. Open the link:https://console.aws.amazon.com/vpc[Amazon VPC console]. .. In the navigation pane, choose **Your VPCs**. .. Select the VPC to delete and choose **Actions, Delete VPC**. diff --git a/modules/rosa-verify-hcp-install.adoc b/modules/rosa-verify-hcp-install.adoc index ea840db7ece..28f00275b92 100644 --- a/modules/rosa-verify-hcp-install.adoc +++ b/modules/rosa-verify-hcp-install.adoc @@ -5,4 +5,13 @@ [id="rosa-verify-hcp-install_{context}"] = Verifying installation of {product-title} clusters -If the {hcp-title} cluster is in the installing state for over 30 minutes and has not become ready, ensure the AWS account environment is prepared for the required cluster configurations. If the AWS account environment is prepared for the required cluster configurations correctly, try to delete and recreate the cluster. If the problem persists, contact support. \ No newline at end of file +[role="_abstract"] +If the {product-title} cluster is in the installing state for over 30 minutes and has not become ready, ensure the AWS account environment is prepared for the required cluster configurations. + +If the AWS account environment is prepared for the required cluster configurations correctly, try to delete and re-create the cluster. If the problem persists, contact support. + +.Procedure + +* Verify the AWS account environment is prepared for the required cluster configurations. +* If the AWS account environment is prepared correctly, try to delete and re-create the cluster. +* If the problem persists, contact support. \ No newline at end of file diff --git a/modules/running-insights-operator-gather-cli.adoc b/modules/running-insights-operator-gather-cli.adoc index 54e7fec7f07..03e71aac190 100644 --- a/modules/running-insights-operator-gather-cli.adoc +++ b/modules/running-insights-operator-gather-cli.adoc @@ -7,7 +7,9 @@ [id="running-insights-operator-gather-openshift-cli_{context}"] = Gathering data on demand with the {insights-operator} from the OpenShift CLI +[role="_abstract"] You can run a custom {insights-operator} gather operation on-demand from the {product-title} command-line interface (CLI). + An on-demand `DataGather` operation is useful for one-off data collections that require different configurations to the periodic data gathering (`InsightsDataGather`) specification. Use the following procedure to create a `DataGather` custom resource definition (CRD), and then run the data gather operation on demand from the CLI. diff --git a/modules/running-insights-operator-gather-web-console.adoc b/modules/running-insights-operator-gather-web-console.adoc index 16fe88773f6..2baff91d05b 100644 --- a/modules/running-insights-operator-gather-web-console.adoc +++ b/modules/running-insights-operator-gather-web-console.adoc @@ -6,7 +6,10 @@ [id="running-insights-operator-gather-web-console_{context}"] = Gathering data on demand with the {insights-operator} from the web console -You can run a custom {insights-operator} gather operation on-demand from the {product-title} web console. An on-demand `DataGather` operation is useful for one-off data collections that require different configurations to the periodic data gathering (`InsightsDataGather`) specification. +[role="_abstract"] +You can run a custom {insights-operator} gather operation on-demand from the {product-title} web console. + +An on-demand `DataGather` operation is useful for one-off data collections that require different configurations to the periodic data gathering (`InsightsDataGather`) specification. Use the following procedure to create a `DataGather` custom resource definition (CRD), and then run the data gather operation on demand from the web console. diff --git a/modules/specifying-oc-log-levels.adoc b/modules/specifying-oc-log-levels.adoc index 604a2b2a157..99abd7a2ecc 100644 --- a/modules/specifying-oc-log-levels.adoc +++ b/modules/specifying-oc-log-levels.adoc @@ -6,6 +6,7 @@ [id="specifying-oc-log-levels_{context}"] = Specifying OpenShift CLI (`oc`) log levels +[role="_abstract"] You can investigate OpenShift CLI (`oc`) issues by increasing the command's log level. The {product-title} user's current session token is typically included in logged `curl` requests where required. You can also obtain the current user's session token manually, for use when testing aspects of an `oc` command's underlying process step-by-step. diff --git a/modules/specifying-openshift-installer-log-levels.adoc b/modules/specifying-openshift-installer-log-levels.adoc index 62916c13c0e..9dacfc426a0 100644 --- a/modules/specifying-openshift-installer-log-levels.adoc +++ b/modules/specifying-openshift-installer-log-levels.adoc @@ -6,7 +6,10 @@ [id="specifying-openshift-installer-log-levels_{context}"] = Specifying {product-title} installer log levels -By default, the {product-title} installer log level is set to `info`. If more detailed logging is required when diagnosing a failed {product-title} installation, you can increase the `openshift-install` log level to `debug` when starting the installation again. +[role="_abstract"] +By default, the {product-title} installer log level is set to `info`. + +If more detailed logging is required when diagnosing a failed {product-title} installation, you can increase the `openshift-install` log level to `debug` when starting the installation again. .Prerequisites @@ -18,6 +21,7 @@ By default, the {product-title} installer log level is set to `info`. If more de + [source,terminal] ---- -$ ./openshift-install --dir wait-for bootstrap-complete --log-level debug <1> +$ ./openshift-install --dir wait-for bootstrap-complete --log-level debug ---- -<1> Possible log levels include `info`, `warn`, `error,` and `debug`. ++ +Possible log levels include `info`, `warn`, `error,` and `debug`. diff --git a/modules/starting-debug-pods-with-root-access.adoc b/modules/starting-debug-pods-with-root-access.adoc index 64e82118b77..7eb1e167b0a 100644 --- a/modules/starting-debug-pods-with-root-access.adoc +++ b/modules/starting-debug-pods-with-root-access.adoc @@ -6,7 +6,10 @@ [id="starting-debug-pods-with-root-access_{context}"] = Starting debug pods with root access -You can start a debug pod with root access, based on a problematic pod's deployment or deployment configuration. Pod users typically run with non-root privileges, but running troubleshooting pods with temporary root privileges can be useful during issue investigation. +[role="_abstract"] +You can start a debug pod with root access, based on a problematic pod's deployment or deployment configuration. + +Pod users typically run with non-root privileges, but running troubleshooting pods with temporary root privileges can be useful during issue investigation. .Prerequisites @@ -50,7 +53,7 @@ $ oc get deploymentconfigs -n ---- $ oc debug deploymentconfig/my-deployment-configuration --as-root -n ---- - ++ [NOTE] ==== You can append `-- ` to the preceding `oc debug` commands to run individual commands within a debug pod, instead of running an interactive shell. diff --git a/modules/storage-multi-attach-error.adoc b/modules/storage-multi-attach-error.adoc index 94afcb90161..649881c9f3d 100644 --- a/modules/storage-multi-attach-error.adoc +++ b/modules/storage-multi-attach-error.adoc @@ -6,6 +6,7 @@ [id="storage-multi-attach-error_{context}"] = Resolving multi-attach errors +[role="_abstract"] When a node crashes or shuts down abruptly, the attached ReadWriteOnce (RWO) volume is expected to be unmounted from the node so that it can be used by a pod scheduled on another node. However, mounting on a new node is not possible because the failed node is unable to unmount the attached volume. @@ -13,24 +14,23 @@ However, mounting on a new node is not possible because the failed node is unabl A multi-attach error is reported: [source,terminal] --- +---- Unable to attach or mount volumes: unmounted volumes=[sso-mysql-pvol], unattached volumes=[sso-mysql-pvol default-token-x4rzc]: timed out waiting for the condition Multi-Attach error for volume "pvc-8837384d-69d7-40b2-b2e6-5df86943eef9" Volume is already used by pod(s) sso-mysql-1-ns6b4 --- +---- .Procedure -To resolve the multi-attach issue, use one of the following solutions: - -* Enable multiple attachments by using RWX volumes. +* To resolve the multi-attach issue, use one of the following solutions: +** Enable multiple attachments by using RWX volumes: + For most storage solutions, you can use ReadWriteMany (RWX) volumes to prevent multi-attach errors. + -* Recover or delete the failed node when using an RWO volume. +** Recover or delete the failed node when using an RWO volume: + For storage that does not support RWX, such as VMware vSphere, RWO volumes must be used instead. However, RWO volumes cannot be mounted on multiple nodes. + -If you encounter a multi-attach error message with an RWO volume, force delete the pod on a shutdown or crashed node to avoid data loss in critical workloads, such as when dynamic persistent volumes are attached. +If you encounter a multi-attach error message with an RWO volume, force delete the pod on a shutdown or crashed node to avoid data loss in critical workloads, such as when dynamic persistent volumes are attached: + [source,terminal] ---- diff --git a/modules/strategies-for-s2i-troubleshooting.adoc b/modules/strategies-for-s2i-troubleshooting.adoc index 12e9671fe48..804a960cc16 100644 --- a/modules/strategies-for-s2i-troubleshooting.adoc +++ b/modules/strategies-for-s2i-troubleshooting.adoc @@ -6,7 +6,10 @@ [id="strategies-for-s2i-troubleshooting_{context}"] = Strategies for Source-to-Image troubleshooting -Use Source-to-Image (S2I) to build reproducible, Docker-formatted container images. You can create ready-to-run images by injecting application source code into a container image and assembling a new image. The new image incorporates the base image (the builder) and built source. +[role="_abstract"] +Use Source-to-Image (S2I) to build reproducible, Docker-formatted container images. You can create ready-to-run images by injecting application source code into a container image and assembling a new image. + +The new image incorporates the base image (the builder) and built source. .Procedure diff --git a/modules/summarizing-cluster-specifications-through-clusterversion.adoc b/modules/summarizing-cluster-specifications-through-clusterversion.adoc index 05cb745a9e6..bac17640631 100644 --- a/modules/summarizing-cluster-specifications-through-clusterversion.adoc +++ b/modules/summarizing-cluster-specifications-through-clusterversion.adoc @@ -7,7 +7,7 @@ = Summarizing cluster specifications by using a cluster version object [role="_abstract"] -You can obtain a summary of {product-title} cluster specifications by querying the `clusterversion` resource. +To verify your cluster version, check update history, and confirm component status, query the `clusterversion` resource. .Prerequisites @@ -17,7 +17,7 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] ifdef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] * You have access to the cluster as a user with the `dedicated-admin` role. endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -* You have installed the OpenShift CLI (`oc`). +* You have installed the {oc-first}. .Procedure diff --git a/modules/support-collecting-host-network-trace.adoc b/modules/support-collecting-host-network-trace.adoc index e0456d604c1..b48f95c8b25 100644 --- a/modules/support-collecting-host-network-trace.adoc +++ b/modules/support-collecting-host-network-trace.adoc @@ -6,6 +6,7 @@ [id="support-collecting-host-network-trace_{context}"] = Collecting a host network trace +[role="_abstract"] Sometimes, troubleshooting a network-related issue is simplified by tracing network communication and capturing packets on multiple nodes at the same time. ifndef::openshift-origin[] @@ -49,23 +50,26 @@ ifndef::openshift-origin[] [source,terminal] ---- $ oc adm must-gather \ - --dest-dir /tmp/captures \// <.> - --source-dir '/tmp/tcpdump/' \// <.> - --image registry.redhat.io/openshift4/network-tools-rhel8:latest \// <.> - --node-selector 'node-role.kubernetes.io/worker' \// <.> - --host-network=true \// <.> - --timeout 30s \// <.> + --dest-dir /tmp/captures \ + --source-dir '/tmp/tcpdump/' \ + --image registry.redhat.io/openshift4/network-tools-rhel8:latest \ + --node-selector 'node-role.kubernetes.io/worker' \ + --host-network=true \ + --timeout 30s \ -- \ - tcpdump -i any \// <.> + tcpdump -i any \ -w /tmp/tcpdump/%Y-%m-%dT%H:%M:%S.pcap -W 1 -G 300 ---- -<.> The `--dest-dir` argument specifies that `oc adm must-gather` stores the packet captures in directories that are relative to `/tmp/captures` on the client machine. You can specify any writable directory. -<.> When `tcpdump` is run in the debug pod that `oc adm must-gather` starts, the `--source-dir` argument specifies that the packet captures are temporarily stored in the `/tmp/tcpdump` directory on the pod. -<.> The `--image` argument specifies a container image that includes the `tcpdump` command. -<.> The `--node-selector` argument and example value specifies to perform the packet captures on the worker nodes. As an alternative, you can specify the `--node-name` argument instead to run the packet capture on a single node. If you omit both the `--node-selector` and the `--node-name` argument, the packet captures are performed on all nodes. -<.> The `--host-network=true` argument is required so that the packet captures are performed on the network interfaces of the node. -<.> The `--timeout` argument and value specify to run the debug pod for 30 seconds. If you do not specify the `--timeout` argument and a duration, the debug pod runs for 10 minutes. -<.> The `-i any` argument for the `tcpdump` command specifies to capture packets on all network interfaces. As an alternative, you can specify a network interface name. ++ +where: + +`--dest-dir /tmp/captures`:: The `--dest-dir` argument specifies that `oc adm must-gather` stores the packet captures in directories that are relative to `/tmp/captures` on the client machine. You can specify any writable directory. +`--source-dir '/tmp/tcpdump/'`:: When `tcpdump` is run in the debug pod that `oc adm must-gather` starts, the `--source-dir` argument specifies that the packet captures are temporarily stored in the `/tmp/tcpdump` directory on the pod. +`--image registry.redhat.io/openshift4/network-tools-rhel8:latest`:: The `--image` argument specifies a container image that includes the `tcpdump` command. +`--node-selector 'node-role.kubernetes.io/worker'`:: The `--node-selector` argument and example value specifies to perform the packet captures on the worker nodes. As an alternative, you can specify the `--node-name` argument instead to run the packet capture on a single node. If you omit both the `--node-selector` and the `--node-name` argument, the packet captures are performed on all nodes. +`--host-network=true`:: The `--host-network=true` argument is required so that the packet captures are performed on the network interfaces of the node. +`--timeout 30s`:: The `--timeout` argument and value specify to run the debug pod for 30 seconds. If you do not specify the `--timeout` argument and a duration, the debug pod runs for 10 minutes. +`-i any`:: The `-i any` argument for the `tcpdump` command specifies to capture packets on all network interfaces. As an alternative, you can specify a network interface name. endif::openshift-origin[] ifdef::openshift-origin[] @@ -74,23 +78,26 @@ ifdef::openshift-origin[] [source,terminal] ---- $ oc adm must-gather \ - --dest-dir /tmp/captures \ <1> - --source-dir '/tmp/tcpdump/' \ <2> - --image quay.io/openshift/origin-network-tools:latest \ <3> - --node-selector 'node-role.kubernetes.io/worker' \ <4> - --host-network=true \ <5> - --timeout 30s \ <6> + --dest-dir /tmp/captures \ + --source-dir '/tmp/tcpdump/' \ + --image quay.io/openshift/origin-network-tools:latest \ + --node-selector 'node-role.kubernetes.io/worker' \ + --host-network=true \ + --timeout 30s \ -- \ - tcpdump -i any \ <7> + tcpdump -i any \ -w /tmp/tcpdump/%Y-%m-%dT%H:%M:%S.pcap -W 1 -G 300 ---- -<1> The `--dest-dir` argument specifies that `oc adm must-gather` stores the packet captures in directories that are relative to `/tmp/captures` on the client machine. You can specify any writable directory. -<2> When `tcpdump` is run in the debug pod that `oc adm must-gather` starts, the `--source-dir` argument specifies that the packet captures are temporarily stored in the `/tmp/tcpdump` directory on the pod. -<3> The `--image` argument specifies a container image that includes the `tcpdump` command. -<4> The `--node-selector` argument and example value specifies to perform the packet captures on the worker nodes. As an alternative, you can specify the `--node-name` argument instead to run the packet capture on a single node. If you omit both the `--node-selector` and the `--node-name` argument, the packet captures are performed on all nodes. -<5> The `--host-network=true` argument is required so that the packet captures are performed on the network interfaces of the node. -<6> The `--timeout` argument and value specify to run the debug pod for 30 seconds. If you do not specify the `--timeout` argument and a duration, the debug pod runs for 10 minutes. -<7> The `-i any` argument for the `tcpdump` command specifies to capture packets on all network interfaces. As an alternative, you can specify a network interface name. ++ +where: + +`--dest-dir /tmp/captures`:: The `--dest-dir` argument specifies that `oc adm must-gather` stores the packet captures in directories that are relative to `/tmp/captures` on the client machine. You can specify any writable directory. +`--source-dir '/tmp/tcpdump/'`:: When `tcpdump` is run in the debug pod that `oc adm must-gather` starts, the `--source-dir` argument specifies that the packet captures are temporarily stored in the `/tmp/tcpdump` directory on the pod. +`--image quay.io/openshift/origin-network-tools:latest`:: The `--image` argument specifies a container image that includes the `tcpdump` command. +`--node-selector 'node-role.kubernetes.io/worker'`:: The `--node-selector` argument and example value specifies to perform the packet captures on the worker nodes. As an alternative, you can specify the `--node-name` argument instead to run the packet capture on a single node. If you omit both the `--node-selector` and the `--node-name` argument, the packet captures are performed on all nodes. +`--host-network=true`:: The `--host-network=true` argument is required so that the packet captures are performed on the network interfaces of the node. +`--timeout 30s`:: The `--timeout` argument and value specify to run the debug pod for 30 seconds. If you do not specify the `--timeout` argument and a duration, the debug pod runs for 10 minutes. +`-i any`:: The `-i any` argument for the `tcpdump` command specifies to capture packets on all network interfaces. As an alternative, you can specify a network interface name. endif::openshift-origin[] . Perform the action, such as accessing a web application, that triggers the network communication issue while the network trace captures packets. @@ -102,17 +109,19 @@ ifndef::openshift-origin[] ---- tmp/captures ├── event-filter.html -├── ip-10-0-192-217-ec2-internal <1> +├── ip-10-0-192-217-ec2-internal │ └── registry-redhat-io-openshift4-network-tools-rhel8-sha256-bca... │ └── 2022-01-13T19:31:31.pcap -├── ip-10-0-201-178-ec2-internal <1> +├── ip-10-0-201-178-ec2-internal │ └── registry-redhat-io-openshift4-network-tools-rhel8-sha256-bca... │ └── 2022-01-13T19:31:30.pcap ├── ip-... └── timestamp ---- + -<1> The packet captures are stored in directories that identify the hostname, container, and file name. +where: + +`ip-10-0-192-217-ec2-internal`, `ip-10-0-201-178-ec2-internal`:: The packet captures are stored in directories that identify the hostname, container, and file name. If you did not specify the `--node-selector` argument, then the directory level for the hostname is not present. endif::openshift-origin[] @@ -123,16 +132,18 @@ ifdef::openshift-origin[] ---- tmp/captures ├── event-filter.html -├── ip-10-0-192-217-ec2-internal <1> +├── ip-10-0-192-217-ec2-internal │ └── quay.io/openshift/origin-network-tools:latest... │ └── 2022-01-13T19:31:31.pcap -├── ip-10-0-201-178-ec2-internal <1> +├── ip-10-0-201-178-ec2-internal │ └── quay.io/openshift/origin-network-tools:latest... │ └── 2022-01-13T19:31:30.pcap ├── ip-... └── timestamp ---- + -<1> The packet captures are stored in directories that identify the hostname, container, and file name. +where: + +`ip-10-0-192-217-ec2-internal`, `ip-10-0-201-178-ec2-internal`:: The packet captures are stored in directories that identify the hostname, container, and file name. If you did not specify the `--node-selector` argument, then the directory level for the hostname is not present. endif::openshift-origin[] diff --git a/modules/support-collecting-network-trace.adoc b/modules/support-collecting-network-trace.adoc index 884ea2856fe..9455857efd6 100644 --- a/modules/support-collecting-network-trace.adoc +++ b/modules/support-collecting-network-trace.adoc @@ -6,7 +6,10 @@ [id="support-collecting-network-trace_{context}"] = Collecting a network trace from an {product-title} node or container -When investigating potential network-related {product-title} issues, Red Hat Support might request a network packet trace from a specific {product-title} cluster node or from a specific container. The recommended method to capture a network trace in {product-title} is through a debug pod. +[role="_abstract"] +When investigating potential network-related {product-title} issues, Red Hat Support might request a network packet trace from a specific {product-title} cluster node or from a specific container. + +The recommended method to capture a network trace in {product-title} is through a debug pod. .Prerequisites @@ -80,9 +83,12 @@ If an existing `toolbox` pod is already running, the `toolbox` command outputs ` + [source,terminal] ---- -$ tcpdump -nn -s 0 -i ens5 -w /host/var/tmp/my-cluster-node_$(date +%d_%m_%Y-%H_%M_%S-%Z).pcap <1> +$ tcpdump -nn -s 0 -i ens5 -w /host/var/tmp/my-cluster-node_$(date +%d_%m_%Y-%H_%M_%S-%Z).pcap ---- -<1> The `tcpdump` capture file's path is outside of the `chroot` environment because the toolbox container mounts the host's root directory at `/host`. ++ +where: + +`/host/var/tmp/my-cluster-node_$(date +%d_%m_%Y-%H_%M_%S-%Z).pcap`:: The `tcpdump` capture file's path is outside of the `chroot` environment because the toolbox container mounts the host's root directory at `/host`. . If a `tcpdump` capture is required for a specific container on the node, follow these steps. .. Determine the target container ID. The `chroot host` command precedes the `crictl` command in this step because the toolbox container mounts the host's root directory at `/host`: @@ -103,9 +109,12 @@ $ tcpdump -nn -s 0 -i ens5 -w /host/var/tmp/my-cluster-node_$(date +%d_%m_%Y-%H_ + [source,terminal] ---- -# nsenter -n -t 49628 -- tcpdump -nn -i ens5 -w /host/var/tmp/my-cluster-node-my-container_$(date +%d_%m_%Y-%H_%M_%S-%Z).pcap <1> +# nsenter -n -t 49628 -- tcpdump -nn -i ens5 -w /host/var/tmp/my-cluster-node-my-container_$(date +%d_%m_%Y-%H_%M_%S-%Z).pcap ---- -<1> The `tcpdump` capture file's path is outside of the `chroot` environment because the toolbox container mounts the host's root directory at `/host`. ++ +where: + +`/host/var/tmp/my-cluster-node-my-container_$(date +%d_%m_%Y-%H_%M_%S-%Z).pcap`:: The `tcpdump` capture file's path is outside of the `chroot` environment because the toolbox container mounts the host's root directory at `/host`. . Provide the `tcpdump` capture file to Red Hat Support for analysis, using one of the following methods. + @@ -115,9 +124,12 @@ $ tcpdump -nn -s 0 -i ens5 -w /host/var/tmp/my-cluster-node_$(date +%d_%m_%Y-%H_ + [source,terminal] ---- -$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/my-tcpdump-capture-file.pcap' > /tmp/my-tcpdump-capture-file.pcap <1> +$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/my-tcpdump-capture-file.pcap' > /tmp/my-tcpdump-capture-file.pcap ---- -<1> The debug container mounts the host's root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. ++ +where: + +`/host/var/tmp/my-tcpdump-capture-file.pcap`:: The debug container mounts the host's root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] + [NOTE] diff --git a/modules/support-gather-data.adoc b/modules/support-gather-data.adoc index cf1a0d8334f..3ed73a46c38 100644 --- a/modules/support-gather-data.adoc +++ b/modules/support-gather-data.adoc @@ -6,6 +6,7 @@ [id="support_gathering_data_{context}"] = Gathering data about your cluster for Red Hat Support +[role="_abstract"] You can gather debugging information about your cluster by using the `oc adm must-gather` CLI command. ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] @@ -79,9 +80,12 @@ Contact Red Hat Support for the recommended resources to gather. + [source,terminal] ---- -$ tar cvaf must-gather-`date +"%m-%d-%Y-%H-%M-%S"`-.tar.gz <1> +$ tar cvaf must-gather-`date +"%m-%d-%Y-%H-%M-%S"`-.tar.gz ---- -<1> Replace `` with the actual directory name. ++ +where: + +``:: Replace with the actual directory name. ifndef::openshift-origin[] . Attach the compressed file to your support case on the link:https://access.redhat.com/support/cases/#/case/list[the *Customer Support* page] of the Red Hat Customer Portal. diff --git a/modules/support-generating-a-sosreport-archive.adoc b/modules/support-generating-a-sosreport-archive.adoc index bbeefe93431..521b4d9791d 100644 --- a/modules/support-generating-a-sosreport-archive.adoc +++ b/modules/support-generating-a-sosreport-archive.adoc @@ -6,6 +6,7 @@ [id="support-generating-a-sosreport-archive_{context}"] = Generating a sosreport archive for an {product-title} cluster node +[role="_abstract"] The recommended way to generate a `sosreport` for an {product-title} {product-version} cluster node is through a debug pod. .Prerequisites @@ -86,9 +87,12 @@ If an existing `toolbox` pod is already running, the `toolbox` command outputs ` + [source,terminal] ---- -# sos report -k crio.all=on -k crio.logs=on -k podman.all=on -k podman.logs=on <1> +# sos report -k crio.all=on -k crio.logs=on -k podman.all=on -k podman.logs=on ---- -<1> `-k` enables you to define `sosreport` plugin parameters outside of the defaults. ++ +where: ++ +`-k` enables you to define `sosreport` plugin parameters outside of the defaults. + .. Optional: To include information on OVN-Kubernetes networking configurations from a node in your report, run the following command: + @@ -106,11 +110,14 @@ If an existing `toolbox` pod is already running, the `toolbox` command outputs ` [source,terminal] ---- Your sosreport has been generated and saved in: - /host/var/tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz <1> + /host/var/tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz The checksum is: 382ffc167510fd71b4f12a4f40b97a4e ---- -<1> The `sosreport` archive's file path is outside of the `chroot` environment because the toolbox container mounts the host's root directory at `/host`. ++ +where: ++ +The `sosreport` archive's file path is outside of the `chroot` environment because the toolbox container mounts the host's root directory at `/host`. . Provide the `sosreport` archive to Red Hat Support for analysis, using one of the following methods. + @@ -119,9 +126,12 @@ The checksum is: 382ffc167510fd71b4f12a4f40b97a4e + [source,terminal] ---- -$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz' > /tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz <1> +$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz' > /tmp/sosreport-my-cluster-node-01234567-2020-05-28-eyjknxt.tar.xz ---- -<1> The debug container mounts the host's root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. ++ +where: ++ +The debug container mounts the host's root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. + [NOTE] ==== diff --git a/modules/support-get-cluster-id.adoc b/modules/support-get-cluster-id.adoc index bc9d4d09e91..c1658118449 100644 --- a/modules/support-get-cluster-id.adoc +++ b/modules/support-get-cluster-id.adoc @@ -6,7 +6,10 @@ [id="support-get-cluster-id_{context}"] = Obtaining your cluster ID -When providing information to Red Hat Support, it is helpful to provide the unique identifier for your cluster. You can have your cluster ID autofilled by using the {product-title} web console. You can also manually obtain your cluster ID by using the web console or the OpenShift CLI (`oc`). +[role="_abstract"] +When providing information to Red Hat Support, it is helpful to provide the unique identifier for your cluster. You can have your cluster ID autofilled by using the {product-title} web console. + +You can also manually obtain your cluster ID by using the web console or the OpenShift CLI (`oc`). .Prerequisites diff --git a/modules/support-installing-packages-to-a-toolbox-container.adoc b/modules/support-installing-packages-to-a-toolbox-container.adoc index 9a026a537eb..0dd05ae7e9a 100644 --- a/modules/support-installing-packages-to-a-toolbox-container.adoc +++ b/modules/support-installing-packages-to-a-toolbox-container.adoc @@ -6,8 +6,11 @@ [id="installing-packages-to-a-toolbox-container_{context}"] = Installing packages to a `toolbox` container +[role="_abstract"] ifndef::openshift-origin[] -By default, running the `toolbox` command starts a container with the `registry.redhat.io/rhel9/support-tools:latest` image. This image contains the most frequently used support tools. If you need to collect node-specific data that requires a support tool that is not part of the image, you can install additional packages. +By default, running the `toolbox` command starts a container with the `registry.redhat.io/rhel9/support-tools:latest` image. This image contains the most frequently used support tools. + +If you need to collect node-specific data that requires a support tool that is not part of the image, you can install additional packages. endif::openshift-origin[] ifdef::openshift-origin[] diff --git a/modules/support-log-gather-config-params.adoc b/modules/support-log-gather-config-params.adoc index 8f39ac11366..71ab2e7c69c 100644 --- a/modules/support-log-gather-config-params.adoc +++ b/modules/support-log-gather-config-params.adoc @@ -7,7 +7,9 @@ [id="support-log-gather-config-params_{context}"] = Configuration parameters for MustGather custom resource +[role="_abstract"] You can manage your `MustGather` custom resource (CR) by creating a YAML file that specifies the parameters for data collection and the upload process. + The following table provides an overview of the parameters that you can configure in the `MustGather` CR. [cols="1,3,1", options="header"] diff --git a/modules/support-log-gather-configure-cli.adoc b/modules/support-log-gather-configure-cli.adoc index 4ab39f745a8..39a57e82395 100644 --- a/modules/support-log-gather-configure-cli.adoc +++ b/modules/support-log-gather-configure-cli.adoc @@ -6,7 +6,10 @@ [id="support-log-gather-config-cli_{context}"] = Configuring a {support-log-gather} instance -You must create a `MustGather` custom resource (CR) from the command-line interface (CLI) to automate the collection of diagnostic data from your cluster. This process also automatically uploads the data to a Red{nbsp}Hat Support case. +[role="_abstract"] +You must create a `MustGather` custom resource (CR) from the command-line interface (CLI) to automate the collection of diagnostic data from your cluster. + +This process also automatically uploads the data to a Red{nbsp}Hat Support case. :FeatureName: Support Log Gather include::snippets/technology-preview.adoc[] @@ -21,14 +24,15 @@ include::snippets/technology-preview.adoc[] * You have created a Kubernetes secret containing your Red Hat Customer Portal credentials. The secret must contain a username field and a password field. -* You have created a service account. +* If you are using a custom image, you have configured an `ImageStream` resource in the Operator namespace that references an approved custom image URL. + +* You have created a service account. If you are using a custom image, you have created a service account with permissions to access the `ImageStream` resource. .Procedure -. Create a YAML file for the `MustGather` CR, such as `support-log-gather.yaml`, that contains the following basic configuration:: +. Create a YAML file for the `MustGather` CR, such as `support-log-gather.yaml`, that contains the following configuration: + .Example `support-log-gather.yaml` -+ [source, yaml] ---- apiVersion: operator.openshift.io/v1alpha1 @@ -37,8 +41,16 @@ metadata: name: example-mg namespace: must-gather-operator spec: - serviceAccountName: must-gather-operator - audit: true + serviceAccountName: my-service-account + gatherSpec: + command: + - "/usr/bin/custom-gather" + args: + - "--verbose" + - "--subsystem=network" + imageStreamRef: + name: "network-debug-tools" + tag: "v1.2" proxyConfig: httpProxy: "http://proxy.example.com:8080" httpsProxy: "https://proxy.example.com:8443" @@ -79,7 +91,6 @@ $ oc get mustgather ---- + .Example output -+ [source, terminal] ---- NAME AGE @@ -94,7 +105,6 @@ $ oc get pods ---- + .Example output -+ [source, terminal] ---- NAME READY STATUS RESTARTS AGE diff --git a/modules/support-log-gather-install-cli.adoc b/modules/support-log-gather-install-cli.adoc index 306dbbb52b0..503f68d7a1b 100644 --- a/modules/support-log-gather-install-cli.adoc +++ b/modules/support-log-gather-install-cli.adoc @@ -6,6 +6,7 @@ [id="support-log-gather-install-cli_{context}"] = Installing {support-log-gather} by using the CLI +[role="_abstract"] To enable automated log collection for support cases, you can install {support-log-gather} from the command-line interface (CLI). :FeatureName: Support Log Gather @@ -81,7 +82,6 @@ $ oc get pods ---- + .Example output -+ [source,terminal] ---- NAME READY STATUS RESTARTS AGE diff --git a/modules/support-log-gather-install-console.adoc b/modules/support-log-gather-install-console.adoc index 2e425fdb4d9..a6b17efdbca 100644 --- a/modules/support-log-gather-install-console.adoc +++ b/modules/support-log-gather-install-console.adoc @@ -6,6 +6,7 @@ [id="support-log-gather-install-console_{context}"] = Installing {support-log-gather} by using the web console +[role="_abstract"] You can use the web console to install the {support-log-gather}. :FeatureName: Support Log Gather diff --git a/modules/support-log-gather-overview.adoc b/modules/support-log-gather-overview.adoc index 1f9ebeedbc8..d73be9361ce 100644 --- a/modules/support-log-gather-overview.adoc +++ b/modules/support-log-gather-overview.adoc @@ -6,6 +6,7 @@ [id="support-log-gather-overview_{context}"] = About {support-log-gather} +[role="_abstract"] {support-log-gather} Operator builds on the functionality of the traditional `must-gather` tool to automate the collection of debugging data. It streamlines troubleshooting by packaging the collected information into a single `.tar` file and automatically uploading it to the specified Red{nbsp}Hat Support case. :FeatureName: Support Log Gather diff --git a/modules/support-log-gather-remove-resources-console.adoc b/modules/support-log-gather-remove-resources-console.adoc index 9b18e0f9e98..9e11866a573 100644 --- a/modules/support-log-gather-remove-resources-console.adoc +++ b/modules/support-log-gather-remove-resources-console.adoc @@ -6,6 +6,7 @@ [id="support-log-gather-remove-resources-console_{context}"] = Removing {support-log-gather} resources +[role="_abstract"] Once you have uninstalled the {support-log-gather}, you can remove the associated resources from your cluster. .Prerequisites diff --git a/modules/support-log-gather-uninstall-console.adoc b/modules/support-log-gather-uninstall-console.adoc index 8738c163e5d..40b804fe97d 100644 --- a/modules/support-log-gather-uninstall-console.adoc +++ b/modules/support-log-gather-uninstall-console.adoc @@ -6,6 +6,7 @@ [id="support-log-gather-uninstall-console_{context}"] = Uninstalling {support-log-gather} +[role="_abstract"] You can uninstall the {support-log-gather} by using the web console. .Prerequisites diff --git a/modules/support-must-gather-targeted-collection-gathering-data.adoc b/modules/support-must-gather-targeted-collection-gathering-data.adoc new file mode 100644 index 00000000000..08e44fe3dd0 --- /dev/null +++ b/modules/support-must-gather-targeted-collection-gathering-data.adoc @@ -0,0 +1,37 @@ +// Module included in the following assemblies: +// +// * support/gathering-cluster-data.adoc + +:_mod-docs-content-type: PROCEDURE +[id="support-must-gather-targeted-collection-gathering-data_{context}"] += Gathering data for specific resources + +[role="_abstract"] +Instead of collecting data for the entire cluster, you can direct the `must-gather` tool to inspect a specific resource. This method is highly effective for isolating issues within a single project, Operator, or application. + +The `must-gather` tool uses `oc adm inspect` internally. You can specify what to inspect by passing the `inspect` command and its arguments after the `--` separator. + +.Procedure + +* To gather data for a specific namespace, such as `my-project`, run the following command: ++ +[source,terminal] +---- +$ oc adm must-gather --dest-dir=my-project-must-gather -- oc adm inspect ns/my-project +---- + +* This command collects all standard resources within the `my-project` namespace, including logs from pods in that namespace, but excludes cluster-scoped resources. + +* To gather data related to a specific Cluster Operator, such as `openshift-apiserver`, run the following command: ++ +[source,terminal] +---- +$ oc adm must-gather --dest-dir=apiserver-must-gather -- oc adm inspect clusteroperator/openshift-apiserver +---- + +* To exclude logs entirely and significantly reduce the size of the `must-gather` archive, add a double dash (`--`) after `oc adm must-gather` command and add the `--no-logs` argument: ++ +[source,terminal] +---- +$ oc adm must-gather -- /usr/bin/gather --no-logs +---- \ No newline at end of file diff --git a/modules/support-must-gather-targeted-collection.adoc b/modules/support-must-gather-targeted-collection.adoc new file mode 100644 index 00000000000..b6b8780386c --- /dev/null +++ b/modules/support-must-gather-targeted-collection.adoc @@ -0,0 +1,12 @@ +// Module included in the following assemblies: +// +// * support/gathering-cluster-data.adoc + +:_mod-docs-content-type: CONCEPT +[id="support-must-gather-targeted-collection_{context}"] += Reducing the size of must-gather output + +[role="_abstract"] +The `oc adm must-gather` command collects comprehensive cluster information. However, a full data collection can result in a large file that is difficult to upload and analyze and could result in timeouts. + +To manage the output size and target your data collection for more effective troubleshooting, you can pass specific flags to the underlying `gather` script or scope the collection to particular resources. \ No newline at end of file diff --git a/modules/support-network-trace-methods.adoc b/modules/support-network-trace-methods.adoc index fac2497a322..7ec2573a5da 100644 --- a/modules/support-network-trace-methods.adoc +++ b/modules/support-network-trace-methods.adoc @@ -6,6 +6,7 @@ [id="support-network-trace-methods_{context}"] = Network trace methods +[role="_abstract"] Collecting network traces, in the form of packet capture records, can assist Red Hat Support with troubleshooting network issues. {product-title} supports two ways of performing a network trace. diff --git a/modules/support-providing-diagnostic-data-to-red-hat.adoc b/modules/support-providing-diagnostic-data-to-red-hat.adoc index 7811c7208b9..f576ded7391 100644 --- a/modules/support-providing-diagnostic-data-to-red-hat.adoc +++ b/modules/support-providing-diagnostic-data-to-red-hat.adoc @@ -6,6 +6,7 @@ [id="support-providing-diagnostic-data-to-red-hat_{context}"] = Providing diagnostic data to Red Hat Support +[role="_abstract"] When investigating {product-title} issues, Red Hat Support might ask you to upload diagnostic data to a support case. Files can be uploaded to a support case through the Red Hat Customer Portal. .Prerequisites @@ -34,9 +35,12 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] + [source,terminal] ---- -$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/my-diagnostic-data.tar.gz' > /var/tmp/my-diagnostic-data.tar.gz <1> +$ oc debug node/my-cluster-node -- bash -c 'cat /host/var/tmp/my-diagnostic-data.tar.gz' > /var/tmp/my-diagnostic-data.tar.gz ---- -<1> The debug container mounts the host's root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. ++ +where: + +`/host/var/tmp/my-diagnostic-data.tar.gz`:: The debug container mounts the host's root directory at `/host`. Reference the absolute path from the debug container's root directory, including `/host`, when specifying target files for concatenation. ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] + [NOTE] diff --git a/modules/support-starting-an-alternative-image-with-toolbox.adoc b/modules/support-starting-an-alternative-image-with-toolbox.adoc index 41e1fd42315..88cd42885cc 100644 --- a/modules/support-starting-an-alternative-image-with-toolbox.adoc +++ b/modules/support-starting-an-alternative-image-with-toolbox.adoc @@ -6,6 +6,7 @@ [id="starting-an-alternative-image-with-toolbox_{context}"] = Starting an alternative image with `toolbox` +[role="_abstract"] ifndef::openshift-origin[] By default, running the `toolbox` command starts a container with the `registry.redhat.io/rhel9/support-tools:latest` image. @@ -37,13 +38,16 @@ endif::openshift-origin[] + [source,text] ---- -REGISTRY=quay.io <1> -IMAGE=fedora/fedora:latest <2> -TOOLBOX_NAME=toolbox-fedora-latest <3> +REGISTRY=quay.io +IMAGE=fedora/fedora:latest +TOOLBOX_NAME=toolbox-fedora-latest ---- -<1> Optional: Specify an alternative container registry. -<2> Specify an alternative image to start. -<3> Optional: Specify an alternative name for the toolbox container. ++ +where: + +`REGISTRY=quay.io`:: Optional: Specify an alternative container registry. +`IMAGE=fedora/fedora:latest`:: Specify an alternative image to start. +`TOOLBOX_NAME=toolbox-fedora-latest`:: Optional: Specify an alternative name for the toolbox container. . Start a toolbox container by entering the following command: + diff --git a/modules/support-submitting-a-case-enable-approved-access.adoc b/modules/support-submitting-a-case-enable-approved-access.adoc index 6d7be838a43..7fd84ca979a 100644 --- a/modules/support-submitting-a-case-enable-approved-access.adoc +++ b/modules/support-submitting-a-case-enable-approved-access.adoc @@ -5,7 +5,7 @@ :_mod-docs-content-type: PROCEDURE [id="support-submitting-a-case-enable-approved-access_{context}"] -= Enabling Approved Access for ROSA clusters by submitting a support case += Enabling approved access for ROSA clusters by submitting a support case [role="_abstract"] Enable the Approved Access feature for your {product-rosa} clusters by creating a support ticket so that you can control when Red{nbsp}Hat Site Reliability Engineering (SRE) accesses your cluster resources. diff --git a/modules/telemetry-showing-data-collected-from-the-cluster.adoc b/modules/telemetry-showing-data-collected-from-the-cluster.adoc index 2e42af09176..83cd7a33921 100644 --- a/modules/telemetry-showing-data-collected-from-the-cluster.adoc +++ b/modules/telemetry-showing-data-collected-from-the-cluster.adoc @@ -6,6 +6,7 @@ [id="showing-data-collected-from-the-cluster_{context}"] = Showing data collected by Telemetry +[role="_abstract"] You can view the cluster and components time series data captured by Telemetry. .Prerequisites @@ -30,9 +31,12 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] . Log in to a cluster. . Run the following command, which queries a cluster's Prometheus service and returns the full set of time series data captured by Telemetry: - -include::snippets/osd-aws-example-only.adoc[] - ++ +[NOTE] +==== +The following example contains some values that are specific to {product-title} on AWS. +==== ++ [source,terminal] ---- $ curl -G -k -H "Authorization: Bearer $(oc whoami -t)" \ diff --git a/modules/telemetry-user-telemetry.adoc b/modules/telemetry-user-telemetry.adoc index 9dd4322518f..f1411a4a53e 100644 --- a/modules/telemetry-user-telemetry.adoc +++ b/modules/telemetry-user-telemetry.adoc @@ -6,6 +6,7 @@ [id="telemetry-user-telemetry_{context}"] = User Telemetry +[role="_abstract"] Red Hat collects anonymized user data from your browser. This anonymized data includes what pages, features, and resource types that the user of all clusters with enabled telemetry uses. Other considerations: diff --git a/modules/troubleshooting-debugging-ignition.adoc b/modules/troubleshooting-debugging-ignition.adoc index 2a82f6cc5ee..cd813dc51e5 100644 --- a/modules/troubleshooting-debugging-ignition.adoc +++ b/modules/troubleshooting-debugging-ignition.adoc @@ -6,6 +6,7 @@ [id="debugging-ignition_{context}"] = Debugging Ignition failures +[role="_abstract"] If a machine cannot be provisioned, Ignition fails and {op-system} will boot into the emergency shell. Use the following procedure to get debugging information. .Procedure diff --git a/modules/troubleshooting-disabling-autoreboot-mco-cli.adoc b/modules/troubleshooting-disabling-autoreboot-mco-cli.adoc index 483ee2b0655..a11fa10c62c 100644 --- a/modules/troubleshooting-disabling-autoreboot-mco-cli.adoc +++ b/modules/troubleshooting-disabling-autoreboot-mco-cli.adoc @@ -6,6 +6,7 @@ [id="troubleshooting-disabling-autoreboot-mco-cli_{context}"] = Disabling the Machine Config Operator from automatically rebooting by using the CLI +[role="_abstract"] To avoid unwanted disruptions from changes made by the Machine Config Operator (MCO), you can modify the machine config pool (MCP) using the OpenShift CLI (oc) to prevent the MCO from making any changes to nodes in that pool. This prevents any reboots that would normally be part of the MCO update process. [NOTE] @@ -25,10 +26,7 @@ endif::openshift-rosa,openshift-dedicated[] .Procedure -To pause or unpause automatic MCO update rebooting: - -* Pause the autoreboot process: - +* To pause or unpause automatic MCO update rebooting: . Update the `MachineConfigPool` custom resource to set the `spec.paused` field to `true`. + .Control plane (master) nodes diff --git a/modules/troubleshooting-disabling-autoreboot-mco-console.adoc b/modules/troubleshooting-disabling-autoreboot-mco-console.adoc index a9b8cac8142..684d3f2c629 100644 --- a/modules/troubleshooting-disabling-autoreboot-mco-console.adoc +++ b/modules/troubleshooting-disabling-autoreboot-mco-console.adoc @@ -6,13 +6,9 @@ [id="troubleshooting-disabling-autoreboot-mco-console_{context}"] = Disabling the Machine Config Operator from automatically rebooting by using the console +[role="_abstract"] To avoid unwanted disruptions from changes made by the Machine Config Operator (MCO), you can use the {product-title} web console to modify the machine config pool (MCP) to prevent the MCO from making any changes to nodes in that pool. This prevents any reboots that would normally be part of the MCO update process. -[NOTE] -==== -See second `NOTE` in xref:../../support/troubleshooting/troubleshooting-operator-issues.adoc#troubleshooting-disabling-autoreboot-mco_troubleshooting-operator-issues[Disabling the Machine Config Operator from automatically rebooting]. -==== - .Prerequisites ifndef::openshift-rosa,openshift-dedicated[] @@ -24,10 +20,6 @@ endif::openshift-rosa,openshift-dedicated[] .Procedure -To pause or unpause automatic MCO update rebooting: - -* Pause the autoreboot process: - . Log in to the {product-title} web console as a user with the `cluster-admin` role. . Click *Compute* -> *MachineConfigPools*. @@ -46,10 +38,11 @@ kind: MachineConfigPool # ... spec: # ... - paused: true <1> + paused: true # ... ---- -<1> Update the `spec.paused` field to `true` to pause rebooting. ++ +Update the `spec.paused` field to `true` to pause rebooting. . To verify that the MCP is paused, return to the *MachineConfigPools* page. + @@ -82,10 +75,11 @@ kind: MachineConfigPool # ... spec: # ... - paused: false <1> + paused: false # ... ---- -<1> Update the `spec.paused` field to `false` to allow rebooting. ++ +Update the `spec.paused` field to `false` to allow rebooting. + [NOTE] ==== diff --git a/modules/troubleshooting-disabling-autoreboot-mco.adoc b/modules/troubleshooting-disabling-autoreboot-mco.adoc index 1a48e26c321..9a15b5458c9 100644 --- a/modules/troubleshooting-disabling-autoreboot-mco.adoc +++ b/modules/troubleshooting-disabling-autoreboot-mco.adoc @@ -6,6 +6,7 @@ [id="troubleshooting-disabling-autoreboot-mco_{context}"] = Disabling the Machine Config Operator from automatically rebooting +[role="_abstract"] When configuration changes are made by the Machine Config Operator (MCO), {op-system-first} must reboot for the changes to take effect. Whether the configuration change is automatic or manual, an {op-system} node reboots automatically unless it is paused. [NOTE] diff --git a/modules/troubleshooting-enabling-kdump-day-one.adoc b/modules/troubleshooting-enabling-kdump-day-one.adoc index 4a8e0966402..ea263ebefc9 100644 --- a/modules/troubleshooting-enabling-kdump-day-one.adoc +++ b/modules/troubleshooting-enabling-kdump-day-one.adoc @@ -112,4 +112,4 @@ $ butane 99-worker-kdump.bu -o 99-worker-kdump.yaml [source,terminal] ---- $ oc create -f 99-worker-kdump.yaml ----- +---- \ No newline at end of file diff --git a/modules/troubleshooting-enabling-kdump.adoc b/modules/troubleshooting-enabling-kdump.adoc index 59ff7afba62..9eb06b65d9b 100644 --- a/modules/troubleshooting-enabling-kdump.adoc +++ b/modules/troubleshooting-enabling-kdump.adoc @@ -6,12 +6,11 @@ [id="enabling-kdump"] = Enabling kdump +[role="_abstract"] {op-system} ships with the `kexec-tools` package, but manual configuration is required to enable the `kdump` service. .Procedure -Perform the following steps to enable kdump on {op-system}. - . To reserve memory for the crash kernel during the first kernel booting, provide kernel arguments by entering the following command: + [source,terminal] diff --git a/modules/troubleshooting-openshift-install-command-issues.adoc b/modules/troubleshooting-openshift-install-command-issues.adoc index 14b2ee834aa..eef45d830a0 100644 --- a/modules/troubleshooting-openshift-install-command-issues.adoc +++ b/modules/troubleshooting-openshift-install-command-issues.adoc @@ -2,9 +2,11 @@ // // * support/troubleshooting/troubleshooting-installations.adoc +:_mod-docs-content-type: CONCEPT [id="troubleshooting-openshift-install-command-issues_{context}"] = Troubleshooting openshift-install command issues +[role="_abstract"] If you experience issues running the `openshift-install` command, check the following: * The installation has been initiated within 24 hours of Ignition configuration file creation. The Ignition files are created when the following command is run: diff --git a/modules/understanding-oc-log-levels.adoc b/modules/understanding-oc-log-levels.adoc index 94f64febc6e..bda2ae0b2a8 100644 --- a/modules/understanding-oc-log-levels.adoc +++ b/modules/understanding-oc-log-levels.adoc @@ -6,6 +6,7 @@ [id="understanding-oc-log-levels_{context}"] = Understanding OpenShift CLI (`oc`) log levels +[role="_abstract"] With the OpenShift CLI (`oc`), you can create applications and manage {product-title} projects from a terminal. If `oc` command-specific issues arise, increase the `oc` log level to output API request, API response, and `curl` request details generated by the command. This provides a granular view of a particular `oc` command's underlying operation, which in turn might provide insight into the nature of a failure. diff --git a/modules/understanding-pod-error-states.adoc b/modules/understanding-pod-error-states.adoc index 8087db2439c..cd7580801a0 100644 --- a/modules/understanding-pod-error-states.adoc +++ b/modules/understanding-pod-error-states.adoc @@ -6,6 +6,7 @@ [id="understanding-pod-error-states_{context}"] = Understanding pod error states +[role="_abstract"] Pod failures return explicit error states that can be observed in the `status` field in the output of `oc get pods`. Pod error states cover image, container, and container network related failures. The following table provides a list of pod error states along with their descriptions. diff --git a/modules/understanding-telemetry-and-insights-operator-data-flow.adoc b/modules/understanding-telemetry-and-insights-operator-data-flow.adoc index 9236d895d65..ecf7b2bc7ba 100644 --- a/modules/understanding-telemetry-and-insights-operator-data-flow.adoc +++ b/modules/understanding-telemetry-and-insights-operator-data-flow.adoc @@ -6,6 +6,7 @@ [id="understanding-telemetry-and-insights-operator-data-flow_{context}"] = Understanding Telemetry and {insights-operator} data flow +[role="_abstract"] The Telemeter Client collects selected time series data from the Prometheus API. The time series data is uploaded to api.openshift.com every four minutes and thirty seconds for processing. The {insights-operator} gathers selected data from the Kubernetes API and the Prometheus API into an archive. The archive is uploaded to {cluster-manager-url} every two hours for processing. The {insights-operator} also downloads the latest {red-hat-lightspeed} analysis from {cluster-manager-url}. This is used to populate the *{red-hat-lightspeed} status* pop-up that is included in the *Overview* page in the {product-title} web console. diff --git a/modules/upi-installation-considerations.adoc b/modules/upi-installation-considerations.adoc index a010ef78662..2ec55ef86f2 100644 --- a/modules/upi-installation-considerations.adoc +++ b/modules/upi-installation-considerations.adoc @@ -2,10 +2,11 @@ // // * support/troubleshooting/troubleshooting-installations.adoc -:_mod-docs-content-type: CONCEPT +:_mod-docs-content-type: REFERENCE [id="upi-installation-considerations_{context}"] = User-provisioned infrastructure installation considerations +[role="_abstract"] The default installation method uses installer-provisioned infrastructure. With installer-provisioned infrastructure clusters, {product-title} manages all aspects of the cluster, including the operating system itself. If possible, use this feature to avoid having to provision and maintain the cluster infrastructure. You can alternatively install {product-title} {product-version} on infrastructure that you provide. If you use this installation method, follow user-provisioned infrastructure installation documentation carefully. Additionally, review the following considerations before the installation: diff --git a/modules/verifying-crio-status.adoc b/modules/verifying-crio-status.adoc index 051dfe5dae3..d703b6f8d4d 100644 --- a/modules/verifying-crio-status.adoc +++ b/modules/verifying-crio-status.adoc @@ -6,6 +6,7 @@ [id="verifying-crio-status_{context}"] = Verifying CRI-O runtime engine status +[role="_abstract"] You can verify CRI-O container runtime engine status on each cluster node. .Prerequisites diff --git a/modules/wmco-does-not-install.adoc b/modules/wmco-does-not-install.adoc index 0729f8344bf..5090b4949d6 100644 --- a/modules/wmco-does-not-install.adoc +++ b/modules/wmco-does-not-install.adoc @@ -7,6 +7,7 @@ [id="wmco-does-not-install_{context}"] = Windows Machine Config Operator does not install +[role="_abstract"] If you have completed the process of installing the Windows Machine Config Operator (WMCO), but the Operator is stuck in the `InstallWaiting` phase, your issue is likely caused by a networking issue. The WMCO requires your {product-title} cluster to be configured with hybrid networking using OVN-Kubernetes; the WMCO cannot complete the installation process without hybrid networking available. This is necessary to manage nodes on multiple operating systems (OS) and OS variants. This must be completed during the installation of your cluster. diff --git a/support/approved-access.adoc b/support/approved-access.adoc index e4b9a81bf9e..8c12dba237f 100644 --- a/support/approved-access.adoc +++ b/support/approved-access.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="approved-access"] -= Approved Access += Approved access + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] @@ -32,6 +33,7 @@ include::modules/support-reviewing-an-access-request-from-an-email-notification. include::modules/support-reviewing-an-access-request-from-the-hybrid-console.adoc[leveloffset=+1] [role="_additional-resources"] +[id="additional-resources_{context}"] == Additional resources * xref:../rosa_cluster_admin/rosa-cluster-notifications.adoc#add-notification-contact_rosa-cluster-notifications[Adding notification cluster contacts] diff --git a/support/gathering-cluster-data.adoc b/support/gathering-cluster-data.adoc index 6cbdf9e1180..3ef744450a5 100644 --- a/support/gathering-cluster-data.adoc +++ b/support/gathering-cluster-data.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="gathering-cluster-data"] = Gathering data about your cluster + include::_attributes/common-attributes.adoc[] ifdef::openshift-rosa,openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] @@ -28,11 +29,24 @@ include::modules/support-gather-data.adoc[leveloffset=+2] endif::openshift-origin[] -ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -[role="_additional-resources"] -.Additional resources -* xref:../hosted_control_planes/hcp-troubleshooting.adoc#hosted-control-planes-troubleshooting_hcp-troubleshooting[Gathering information to troubleshoot {hcp}] -endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] +ifndef::openshift-origin[] +// Reducing the size of must-gather output +include::modules/support-must-gather-targeted-collection.adoc[leveloffset=+1] + +endif::openshift-origin[] + +ifndef::openshift-origin[] +// Gathering data for specific resources +include::modules/support-must-gather-targeted-collection-gathering-data.adoc[leveloffset=+2] + +endif::openshift-origin[] + +// Commented this additional resources section out because the hosted control plane section was removed from the openshift-enterprise topic map. +//ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] +//[role="_additional-resources"] +//== Additional resources +//* xref:../hosted_control_planes/hcp-troubleshooting.adoc#hosted-control-planes-troubleshooting_hcp-troubleshooting[Gathering information to troubleshoot {hcp}] +//endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] ifndef::openshift-origin[] // Table of must-gather flags diff --git a/support/getting-support.adoc b/support/getting-support.adoc index 2e6e84c47ee..b3e812a0535 100644 --- a/support/getting-support.adoc +++ b/support/getting-support.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="getting-support"] = Getting support + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] diff --git a/support/index.adoc b/support/index.adoc index e516ee8ff3c..95dd3c2834d 100644 --- a/support/index.adoc +++ b/support/index.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id='support-overview'] = Support overview + include::_attributes/common-attributes.adoc[] :context: support-overview diff --git a/support/managing-cluster-resources.adoc b/support/managing-cluster-resources.adoc index 439e1be10af..bb5802ea30f 100644 --- a/support/managing-cluster-resources.adoc +++ b/support/managing-cluster-resources.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="managing-cluster-resources"] = Managing your cluster resources + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] @@ -10,6 +11,6 @@ endif::[] toc::[] [role="_abstract"] -You can apply global configuration options in {product-title}. Operators apply these configuration settings across the cluster. +To keep consistent behavior across your {product-title} cluster, set global configuration options that Operators apply to all nodes. include::modules/cluster-resources.adoc[leveloffset=+1] diff --git a/support/remote_health_monitoring/about-remote-health-monitoring.adoc b/support/remote_health_monitoring/about-remote-health-monitoring.adoc index e40b6daf2ac..421eabba814 100644 --- a/support/remote_health_monitoring/about-remote-health-monitoring.adoc +++ b/support/remote_health_monitoring/about-remote-health-monitoring.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="about-remote-health-monitoring"] = About remote health monitoring + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] @@ -9,6 +10,7 @@ endif::[] toc::[] +[role="_abstract"] {product-title} collects telemetry and configuration data about your cluster and reports it to Red{nbsp}Hat by using the Telemeter Client and the {insights-operator}. The data that is provided to Red{nbsp}Hat enables the benefits outlined in this document. A cluster that reports data to Red Hat through Telemetry and the {insights-operator} is considered a _connected cluster_. @@ -32,16 +34,16 @@ include::modules/telemetry-about-telemetry.adoc[leveloffset=+1] .Additional resources ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -* See the xref:../../updating/updating_a_cluster/updating-cluster-web-console.adoc#updating-cluster-web-console[{product-title} update documentation] for more information about updating or upgrading a cluster. +* xref:../../updating/updating_a_cluster/updating-cluster-web-console.adoc#updating-cluster-web-console[{product-title} update documentation] endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] ifdef::openshift-rosa[] -* See the xref:../../upgrading/rosa-upgrading-sts.adoc#rosa-upgrading-sts[{product-title} upgrade documentation] for more information about upgrading a cluster. +* xref:../../upgrading/rosa-upgrading-sts.adoc#rosa-upgrading-sts[{product-title} upgrade documentation] endif::openshift-rosa[] ifdef::openshift-rosa-hcp[] -* See the xref:../../upgrading/rosa-hcp-upgrading.adoc#rosa-hcp-upgrading[{product-title} upgrade documentation] for more information about upgrading a cluster. +* xref:../../upgrading/rosa-hcp-upgrading.adoc#rosa-hcp-upgrading[{product-title} upgrade documentation] endif::openshift-rosa-hcp[] ifdef::openshift-dedicated[] -* See the xref:../../upgrading/osd-upgrades.adoc#osd-upgrades[{product-title} upgrade documentation] for more information about upgrading a cluster. +* xref:../../upgrading/osd-upgrades.adoc#osd-upgrades[{product-title} upgrade documentation] endif::openshift-dedicated[] include::modules/telemetry-what-information-is-collected.adoc[leveloffset=+2] @@ -55,12 +57,11 @@ endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] [role="_additional-resources"] .Additional resources -* See xref:../../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#showing-data-collected-from-the-cluster_showing-data-collected-by-remote-health-monitoring[Showing data collected by Telemetry] for details about how to list the attributes that Telemetry gathers from Prometheus in {product-title}. - -* See the link:https://github.com/openshift/cluster-monitoring-operator/blob/master/manifests/0000_50_cluster-monitoring-operator_04-config.yaml[upstream cluster-monitoring-operator source code] for a list of the attributes that Telemetry gathers from Prometheus. +* xref:../../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#showing-data-collected-from-the-cluster_showing-data-collected-by-remote-health-monitoring[Showing data collected by Telemetry] +* link:https://github.com/openshift/cluster-monitoring-operator/blob/master/manifests/0000_50_cluster-monitoring-operator_04-config.yaml[Upstream cluster-monitoring-operator source code] ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -* Telemetry is installed and enabled by default. If you need to opt out of remote health reporting, see xref:../../support/remote_health_monitoring/remote-health-reporting.adoc#remote-health-reporting[Remote health reporting]. +* xref:../../support/remote_health_monitoring/remote-health-reporting.adoc#remote-health-reporting[Remote health reporting] endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] include::modules/insights-operator-about.adoc[leveloffset=+1] @@ -79,7 +80,7 @@ include::modules/insights-operator-what-information-is-collected.adoc[leveloffse .Additional resources ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -* See xref:../../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#insights-operator-showing-data-collected-from-the-cluster_showing-data-collected-by-remote-health-monitoring[Showing data collected by the {insights-operator}] for details about how to review the data that is collected by the {insights-operator}. +* xref:../../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#insights-operator-showing-data-collected-from-the-cluster_showing-data-collected-by-remote-health-monitoring[Showing data collected by the {insights-operator}] endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] * link:https://access.redhat.com/solutions/7066188[What data is being collected by the {insights-operator} in OpenShift? (Knowledgebase article)] @@ -96,12 +97,12 @@ ifndef::openshift-rosa-hcp[] .Additional resources ifdef::openshift-dedicated,openshift-rosa[] -* See xref:../../observability/monitoring/about-ocp-monitoring/about-ocp-monitoring.adoc#about-ocp-monitoring[About {product-title} monitoring] for more information about the {product-title} monitoring stack. +* xref:../../observability/monitoring/about-ocp-monitoring/about-ocp-monitoring.adoc#about-ocp-monitoring[About {product-title} monitoring] endif::openshift-dedicated,openshift-rosa[] ifndef::openshift-dedicated,openshift-rosa[] -* See link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.20/html/about_monitoring/about-ocp-monitoring[About {product-title} monitoring] for more information about the {product-title} monitoring stack. -* See xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[Configuring your firewall] for details about configuring a firewall and enabling endpoints for Telemetry and {red-hat-lightspeed} +* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/latest/html/about_monitoring/about-ocp-monitoring[About {product-title} monitoring] +* xref:../../installing/install_config/configuring-firewall.adoc#configuring-firewall[Configuring your firewall] endif::openshift-dedicated,openshift-rosa[] endif::openshift-rosa-hcp[] diff --git a/support/remote_health_monitoring/remote-health-reporting-from-restricted-network.adoc b/support/remote_health_monitoring/remote-health-reporting-from-restricted-network.adoc index 60262d700fa..dc842b8758d 100644 --- a/support/remote_health_monitoring/remote-health-reporting-from-restricted-network.adoc +++ b/support/remote_health_monitoring/remote-health-reporting-from-restricted-network.adoc @@ -1,11 +1,13 @@ :_mod-docs-content-type: ASSEMBLY [id="remote-health-reporting-from-restricted-network"] = Using remote health reporting in a restricted network + include::_attributes/common-attributes.adoc[] :context: remote-health-reporting-from-restricted-network toc::[] +[role="_abstract"] You can manually gather and upload {insights-operator} archives to diagnose issues from a restricted network. To use the {insights-operator} in a restricted network, you must complete the following tasks: @@ -30,4 +32,4 @@ include::modules/insights-operator-enable-obfuscation.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* For more information on how to download your {insights-operator} archive, see xref:../../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#insights-operator-showing-data-collected-from-the-cluster_showing-data-collected-by-remote-health-monitoring[Showing data collected by the {insights-operator}]. +* xref:../../support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc#insights-operator-showing-data-collected-from-the-cluster_showing-data-collected-by-remote-health-monitoring[Showing data collected by the {insights-operator}] diff --git a/support/remote_health_monitoring/remote-health-reporting.adoc b/support/remote_health_monitoring/remote-health-reporting.adoc index 142f3a918e4..f348b309c7f 100644 --- a/support/remote_health_monitoring/remote-health-reporting.adoc +++ b/support/remote_health_monitoring/remote-health-reporting.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="remote-health-reporting"] = Remote health reporting + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] @@ -11,6 +12,7 @@ toc::[] ifdef::openshift-enterprise,openshift-origin[] +[role="_abstract"] You can _opt in_, enable, or _opt out_, disable, reporting health and usage data for your cluster. // Enabling remote health reporting diff --git a/support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc b/support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc index fe59cb3f0c6..010e4045bc5 100644 --- a/support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc +++ b/support/remote_health_monitoring/showing-data-collected-by-remote-health-monitoring.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="showing-data-collected-by-remote-health-monitoring"] = Showing data collected by remote health monitoring + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] @@ -9,6 +10,7 @@ endif::[] toc::[] +[role="_abstract"] As an administrator, you can review the metrics collected by Telemetry and the {insights-operator}. include::modules/telemetry-showing-data-collected-from-the-cluster.adoc[leveloffset=+1] diff --git a/support/remote_health_monitoring/using-insights-operator.adoc b/support/remote_health_monitoring/using-insights-operator.adoc index 147b8e0c92c..aa9dc705b9a 100644 --- a/support/remote_health_monitoring/using-insights-operator.adoc +++ b/support/remote_health_monitoring/using-insights-operator.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="using-insights-operator"] -= Using the {insights-operator} += Using the Insights Operator + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] @@ -9,22 +10,23 @@ endif::[] toc::[] +[role="_abstract"] The {insights-operator} periodically gathers configuration and component failure status and, by default, reports that data every two hours to Red{nbsp}Hat. This information enables Red{nbsp}Hat to assess configuration and deeper failure data than is reported through Telemetry. Users of {product-title} can display the report in the {insights-advisor-url} service on {hybrid-console}. [role="_additional-resources"] .Additional resources ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] -* The {insights-operator} is installed and enabled by default. If you need to opt out of remote health reporting, see xref:../../support/remote_health_monitoring/remote-health-reporting.adoc#remote-health-reporting[Remote health reporting]. +* xref:../../support/remote_health_monitoring/remote-health-reporting.adoc#remote-health-reporting[Remote health reporting] endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] - -* For more information on using the {red-hat-lightspeed} advisor service to identify issues with your cluster, see xref:../../support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc#using-insights-to-identify-issues-with-your-cluster[Using {red-hat-lightspeed} to identify issues with your cluster]. +* xref:../../support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc#using-insights-to-identify-issues-with-your-cluster[Using {red-hat-lightspeed} to identify issues with your cluster] ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] include::modules/insights-operator-configuring.adoc[leveloffset=+1] include::modules/insights-operator-configuring-configmap.adoc[leveloffset=+2] +include::modules/insights-operator-insights-config.adoc[leveloffset=+1] endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] include::modules/understanding-insights-operator-alerts.adoc[leveloffset=+1] diff --git a/support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc b/support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc index 0d0d2b2b6d1..afd76ffc4ae 100644 --- a/support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc +++ b/support/remote_health_monitoring/using-insights-to-identify-issues-with-your-cluster.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="using-insights-to-identify-issues-with-your-cluster"] -= Using {red-hat-lightspeed} to identify issues with your cluster += Using Red{nbsp}Hat Lightspeed to identify issues with your cluster + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] diff --git a/support/summarizing-cluster-specifications.adoc b/support/summarizing-cluster-specifications.adoc index b04d244543e..aa0cc7ad05a 100644 --- a/support/summarizing-cluster-specifications.adoc +++ b/support/summarizing-cluster-specifications.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="summarizing-cluster-specifications"] = Summarizing cluster specifications + include::_attributes/common-attributes.adoc[] ifdef::openshift-dedicated[] include::_attributes/attributes-openshift-dedicated.adoc[] @@ -10,7 +11,7 @@ endif::[] toc::[] [role="_abstract"] -You can query the `clusterversion` resource to obtain a summary of your {product-title} cluster specifications to help Red{nbsp}Hat Support troubleshoot issues. +To verify the version, update history, and component status of your {product-title} cluster, query the `clusterversion` resource. // Summarizing cluster specifications through `clusterversion` include::modules/summarizing-cluster-specifications-through-clusterversion.adoc[leveloffset=+1] diff --git a/support/troubleshooting/diagnosing-oc-issues.adoc b/support/troubleshooting/diagnosing-oc-issues.adoc index 526fc23a31c..7f6015b7afc 100644 --- a/support/troubleshooting/diagnosing-oc-issues.adoc +++ b/support/troubleshooting/diagnosing-oc-issues.adoc @@ -1,11 +1,15 @@ :_mod-docs-content-type: ASSEMBLY [id="diagnosing-oc-issues"] = Diagnosing OpenShift CLI (`oc`) issues + include::_attributes/common-attributes.adoc[] :context: diagnosing-oc-issues toc::[] +[role="_abstract"] +You can investigate {oc-first} issues by increasing the log level to get more detailed diagnostic information. + // Understanding OpenShift CLI (`oc`) log levels include::modules/understanding-oc-log-levels.adoc[leveloffset=+1] diff --git a/support/troubleshooting/investigating-monitoring-issues.adoc b/support/troubleshooting/investigating-monitoring-issues.adoc index 000cc7e67ba..09e38243890 100644 --- a/support/troubleshooting/investigating-monitoring-issues.adoc +++ b/support/troubleshooting/investigating-monitoring-issues.adoc @@ -1,11 +1,13 @@ :_mod-docs-content-type: ASSEMBLY [id="investigating-monitoring-issues"] = Investigating monitoring issues + include::_attributes/common-attributes.adoc[] :context: investigating-monitoring-issues toc::[] +[role="_abstract"] {product-title} includes a preconfigured, preinstalled, and self-updating monitoring stack that provides monitoring for core platform components. In {product-title} {product-version}, cluster administrators can optionally enable monitoring for user-defined projects. // Note - please update the following sentence if you add further modules to this assembly. @@ -21,12 +23,12 @@ include::modules/monitoring-investigating-why-user-defined-metrics-are-unavailab // TODO: Add the additional resources for ROSA HCP when the Observability book is added. ifndef::openshift-rosa-hcp[] [role="_additional-resources"] -.Additional resources +== Additional resources ifndef::openshift-rosa,openshift-dedicated[] -* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.20/html/configuring_user_workload_monitoring/preparing-to-configure-the-monitoring-stack-uwm#enabling-monitoring-for-user-defined-projects-uwm_preparing-to-configure-the-monitoring-stack-uwm[Enabling monitoring for user-defined projects] +* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/latest/html/configuring_user_workload_monitoring/preparing-to-configure-the-monitoring-stack-uwm#enabling-monitoring-for-user-defined-projects-uwm_preparing-to-configure-the-monitoring-stack-uwm[Enabling monitoring for user-defined projects] endif::openshift-rosa,openshift-dedicated[] -* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.20/html/configuring_user_workload_monitoring/configuring-metrics-uwm#specifying-how-a-service-is-monitored_configuring-metrics-uwm[Specifying how a service is monitored] -* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.20/html/accessing_metrics/accessing-metrics-as-an-administrator#getting-detailed-information-about-a-target_accessing-metrics-as-an-administrator[Getting detailed information about a metrics target] +* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/latest/html/configuring_user_workload_monitoring/configuring-metrics-uwm#specifying-how-a-service-is-monitored_configuring-metrics-uwm[Specifying how a service is monitored] +* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/latest/html/accessing_metrics/accessing-metrics-as-an-administrator#getting-detailed-information-about-a-target_accessing-metrics-as-an-administrator[Getting detailed information about a metrics target] endif::openshift-rosa-hcp[] // Determining why Prometheus is consuming a lot of disk space @@ -35,8 +37,8 @@ include::modules/monitoring-determining-why-prometheus-is-consuming-disk-space.a // TODO: Add the additional resources for ROSA HCP when the Observability book is added. ifndef::openshift-rosa-hcp[] [role="_additional-resources"] -.Additional resources -* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/4.20/html/configuring_user_workload_monitoring/configuring-performance-and-scalability-uwm#setting-scrape-and-evaluation-intervals-limits-for-user-defined-projects_configuring-performance-and-scalability-uwm[Setting scrape intervals, evaluation intervals, and enforced limits for user-defined projects] +== Additional resources +* link:https://docs.redhat.com/en/documentation/monitoring_stack_for_red_hat_openshift/latest/html/configuring_user_workload_monitoring/configuring-performance-and-scalability-uwm#setting-scrape-and-evaluation-intervals-limits-for-user-defined-projects_configuring-performance-and-scalability-uwm[Setting scrape intervals, evaluation intervals, and enforced limits for user-defined projects] endif::openshift-rosa-hcp[] // Resolving the KubePersistentVolumeFillingUp alert firing for Prometheus diff --git a/support/troubleshooting/investigating-pod-issues.adoc b/support/troubleshooting/investigating-pod-issues.adoc index f768a51a788..4cbfd9e1d36 100644 --- a/support/troubleshooting/investigating-pod-issues.adoc +++ b/support/troubleshooting/investigating-pod-issues.adoc @@ -1,11 +1,13 @@ :_mod-docs-content-type: ASSEMBLY [id="investigating-pod-issues"] = Investigating pod issues + include::_attributes/common-attributes.adoc[] :context: investigating-pod-issues toc::[] +[role="_abstract"] {product-title} leverages the Kubernetes concept of a pod, which is one or more containers deployed together on one host. A pod is the smallest compute unit that can be defined, deployed, and managed on {product-title} {product-version}. After a pod is defined, it is assigned to run on a node until its containers exit, or until it is removed. Depending on policy and exit code, pods are either removed after exiting or retained so that their logs can be accessed. diff --git a/support/troubleshooting/mos-tshoot-cluster-notifications.adoc b/support/troubleshooting/mos-tshoot-cluster-notifications.adoc index b2cceac77a3..10cd7981bcc 100644 --- a/support/troubleshooting/mos-tshoot-cluster-notifications.adoc +++ b/support/troubleshooting/mos-tshoot-cluster-notifications.adoc @@ -1,13 +1,13 @@ :_mod-docs-content-type: ASSEMBLY [id="mos-tshoot-cluster-notifications"] = Review your cluster notifications + include::_attributes/attributes-openshift-dedicated.adoc[] :context: tshoot-cluster-notifications toc::[] -When you are trying to resolve a problem with your cluster, your cluster notifications are a good source of information. - -Cluster notifications are messages about the status, health, or performance of your cluster. They are also the primary way that Red Hat Site Reliability Engineering (SRE) communicates with you about cluster health and resolving problems with your cluster. +[role="_abstract"] +Use cluster notifications to help you resolve cluster problems. Cluster notifications are messages about the status, health, or performance of your cluster. Red Hat Site Reliability Engineering (SRE) uses these notifications to communicate about the health and problem resolution of your clusters. include::modules/managed-cluster-notification-view-in-hcc.adoc[leveloffset=+1] \ No newline at end of file diff --git a/support/troubleshooting/rosa-troubleshooting-deployments.adoc b/support/troubleshooting/rosa-troubleshooting-deployments.adoc index 2be82f73db6..eb54ba7c04a 100644 --- a/support/troubleshooting/rosa-troubleshooting-deployments.adoc +++ b/support/troubleshooting/rosa-troubleshooting-deployments.adoc @@ -1,12 +1,14 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes-openshift-dedicated.adoc[] [id="rosa-troubleshooting-cluster-deployments"] = Troubleshooting {product-title} cluster deployments + +include::_attributes/attributes-openshift-dedicated.adoc[] :context: rosa-troubleshooting-cluster-deployments toc::[] -This document describes how to troubleshoot cluster deployment errors. +[role="_abstract"] +Troubleshoot cluster deployment errors by completing the following instructions. include::modules/rosa-troubleshooting-general-deployment.adoc[leveloffset=+1] include::modules/rosa-troubleshooting-osdccsadmin-deployment.adoc[leveloffset=+1] @@ -21,7 +23,7 @@ include::modules/rosa-troubleshooting-toomanyroute53zones-failure-deployment.ado include::modules/rosa-troubleshooting-awssubnetnotexist-failure-deployment.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +== Additional resources * xref:../../rosa_install_access_delete_clusters/rosa_getting_started_iam/rosa-aws-prereqs.adoc#rosa-vpc_prerequisites[AWS prerequisites for {product-title}] include::modules/rosa-troubleshooting-invalidkmskey-failure-deployment.adoc[leveloffset=+1] @@ -29,13 +31,13 @@ include::modules/rosa-troubleshooting-multipleroute53zonesfound-failure-deployme include::modules/rosa-troubleshooting-invalidinstallconfigsubnet-failure-deployment.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +== Additional resources * xref:../../networking/networking_overview/cidr-range-definitions.adoc#cidr-range-definitions[CIDR range definitions] include::modules/rosa-troubleshooting-awsinsufficientpermission-failure-deployment.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +== Additional resources * xref:../../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-sts-aws-prereqs[Detailed requirements for deploying {product-title} using STS] include::modules/rosa-troubleshooting-deleteiamrole-deployment.adoc[leveloffset=+1] diff --git a/support/troubleshooting/rosa-troubleshooting-expired-tokens.adoc b/support/troubleshooting/rosa-troubleshooting-expired-tokens.adoc index 2154dd78b6e..2cb4e0cbd93 100644 --- a/support/troubleshooting/rosa-troubleshooting-expired-tokens.adoc +++ b/support/troubleshooting/rosa-troubleshooting-expired-tokens.adoc @@ -1,8 +1,12 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes-openshift-dedicated.adoc[] [id="rosa-troubleshooting-expired-tokens"] = Troubleshooting expired tokens + +include::_attributes/attributes-openshift-dedicated.adoc[] :context: rosa-troubleshooting-expired-tokens toc::[] +[role="_abstract"] +Troubleshoot expired offline access tokens that prevent access to your {product-title} cluster. + include::modules/rosa-troubleshooting-expired-token.adoc[leveloffset=+1] diff --git a/support/troubleshooting/rosa-troubleshooting-iam-resources.adoc b/support/troubleshooting/rosa-troubleshooting-iam-resources.adoc index 1e862891138..4dde57fb280 100644 --- a/support/troubleshooting/rosa-troubleshooting-iam-resources.adoc +++ b/support/troubleshooting/rosa-troubleshooting-iam-resources.adoc @@ -1,32 +1,30 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes-openshift-dedicated.adoc[] [id="rosa-troubleshooting-iam-resources"] = Troubleshooting IAM roles + +include::_attributes/attributes-openshift-dedicated.adoc[] :context: rosa-troubleshooting-iam-resources toc::[] +[role="_abstract"] +Troubleshoot IAM role issues that prevent proper access to your {product-title} cluster resources. + include::modules/rosa-sts-ocm-and-user-role-troubleshooting.adoc[leveloffset=+1] -include::modules/rosa-sts-ocm-role-creation.adoc[leveloffset=+2] -[role="_additional-resources"] -[id="additional-resources_ocm-role-creation_{context}"] -.Additional resources -* xref:../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies-creation-methods_rosa-sts-about-iam-resources[Methods of account-wide role creation] +include::modules/rosa-sts-ocm-role-creation.adoc[leveloffset=+1] -include::modules/rosa-sts-user-role-creation.adoc[leveloffset=+2] +include::modules/rosa-sts-user-role-creation.adoc[leveloffset=+1] -[role="_additional-resources"] -[id="additional-resources_user-role-creation_{context}"] -.Additional resources -* xref:../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies-creation-methods_rosa-sts-about-iam-resources[Methods of account-wide role creation] +include::modules/rosa-sts-aws-requirements-creating-association.adoc[leveloffset=+1] -include::modules/rosa-sts-aws-requirements-creating-association.adoc[leveloffset=+2] -include::modules/rosa-sts-aws-requirements-creating-multi-association.adoc[leveloffset=+2] +include::modules/rosa-sts-aws-requirements-creating-multi-association.adoc[leveloffset=+1] // TODO: Add the additional resource to ROSA HCP when the Architecture book is added. ifndef::openshift-rosa-hcp[] [role="_additional-resources"] +[id="additional-resources_aws-requirements_{context}"] == Additional resources -* See xref:../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies[Account-wide IAM role and policy reference] for a list of IAM roles needed for cluster creation. +* xref:../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies-creation-methods_rosa-sts-about-iam-resources[Methods of account-wide role creation] +* xref:../../rosa_architecture/rosa-sts-about-iam-resources.adoc#rosa-sts-account-wide-roles-and-policies[Account-wide IAM role and policy reference] endif::openshift-rosa-hcp[] diff --git a/support/troubleshooting/rosa-troubleshooting-installations-hcp.adoc b/support/troubleshooting/rosa-troubleshooting-installations-hcp.adoc index d46635969fc..49ac6634e20 100644 --- a/support/troubleshooting/rosa-troubleshooting-installations-hcp.adoc +++ b/support/troubleshooting/rosa-troubleshooting-installations-hcp.adoc @@ -1,46 +1,43 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes-openshift-dedicated.adoc[] [id="rosa-troubleshooting-installations-hcp"] = Troubleshooting {product-title} cluster installations + +include::_attributes/attributes-openshift-dedicated.adoc[] :context: rosa-troubleshooting-installations-hcp toc::[] -For help with the installation of {product-title} clusters, see the following sections. +[role="_abstract"] +Troubleshoot the installation of {product-title} clusters by completing the following instructions. include::modules/rosa-troubleshooting-installing.adoc[leveloffset=+1] include::modules/rosa-verify-hcp-install.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources -* For information about the prerequisites for installing {product-title} clusters with {hcp}, see xref:../../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-sts-aws-prereqs[AWS prerequisites for ROSA with STS]. - include::modules/rosa-troubleshoot-hcp-install.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources -// * For information about the required IAM, see xref:../../rosa_planning/rosa-sts-ocm-role.adoc#rosa-sts-ocm-role[ROSA IAM role resources]. -* For information about the AWS STS prerequisites for {product-title} clusters, see xref:../../rosa_architecture/cloud-experts-rosa-hcp-sts-explained.adoc#cloud-experts-rosa-hcp-sts-explained[AWS STS and {product-title} explained]. - include::modules/rosa-hcp-no-console-access.adoc[leveloffset=+1] -[role="_additional-resources"] -.Additional resources -* For more information about the {product-title} OAuth server, see xref:../../authentication/understanding-authentication.adoc#oauth-server-overview[{product-title} OAuth server]. -//Commented out until Networking book has been fully migrated. -//* For more information about the {product-title} ingress operator, xref:../../networking/networking_operators/ingress-operator.adoc#configuring-ingress-controller[Configuring the Ingress Controller]. -* For more information about the web console, see xref:../../web_console/web-console-overview.adoc#web-console-overview[Web Console Overview]. - include::modules/rosa-hcp-ready-no-console-access.adoc[leveloffset=+1] - -[role="_additional-resources"] -.Additional resources -* For more information about the `rosa describe machinepool` command, see xref:../../cli_reference/rosa_cli/rosa-cli-commands.adoc#rosa-describe-machinepool[`rosa describe machinepool`] in the _ROSA CLI command reference_. - include::modules/rosa-hcp-private-ready-no-console-access.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources -* For more information about connecting the cluster VPC to other networks, see https://docs.aws.amazon.com/vpc/latest/userguide/extend-intro.html[AWS VPC Documentation]. +[id="additional-resources_{context}"] +== Additional resources + +* xref:rosa-troubleshooting-installing_{context}[Installation troubleshooting] +* xref:rosa-verify-hcp-install_{context}[Verifying installation of {product-title} clusters] +* xref:rosa-troubleshoot-hcp-install_{context}[Troubleshooting {product-title} installation error codes] +* xref:rosa-hcp-no-console-access_{context}[Troubleshooting access to {hybrid-console}] +* xref:rosa-hcp-ready-no-console-access_{context}[Verifying access to {product-title} web console for {product-title} cluster in ready state] +* xref:rosa-hcp-private-ready-no-console-access_{context}[Verifying access to {hybrid-console} for private {product-title} clusters] +* xref:../../rosa_planning/rosa-sts-aws-prereqs.adoc#rosa-sts-aws-prereqs[AWS prerequisites for {product-title}] +// * For information about the required IAM, see xref:../../rosa_planning/rosa-sts-ocm-role.adoc#rosa-sts-ocm-role[ROSA IAM role resources]. +* xref:../../rosa_architecture/cloud-experts-rosa-hcp-sts-explained.adoc#cloud-experts-rosa-hcp-sts-explained[AWS STS and {product-title} explained] +* xref:../../authentication/understanding-authentication.adoc#oauth-server-overview[{product-title} OAuth server] +//Commented out until Networking book has been fully migrated. +//* For more information about the {product-title} ingress operator, xref:../../networking/networking_operators/ingress-operator.adoc#configuring-ingress-controller[Configuring the Ingress Controller]. +* xref:../../web_console/web-console-overview.adoc#web-console-overview[Web Console Overview] +* xref:../../cli_reference/rosa_cli/rosa-cli-commands.adoc#rosa-describe-machinepool[`rosa describe machinepool`] +* link:https://docs.aws.amazon.com/vpc/latest/userguide/extend-intro.html[AWS Virtual Private Cloud (VPC) Documentation] diff --git a/support/troubleshooting/rosa-troubleshooting-installations.adoc b/support/troubleshooting/rosa-troubleshooting-installations.adoc index 3672c705611..9e71e057b16 100644 --- a/support/troubleshooting/rosa-troubleshooting-installations.adoc +++ b/support/troubleshooting/rosa-troubleshooting-installations.adoc @@ -1,11 +1,15 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes-openshift-dedicated.adoc[] [id="rosa-troubleshooting-installations"] = Troubleshooting {product-title} installations + +include::_attributes/attributes-openshift-dedicated.adoc[] :context: rosa-troubleshooting-installations toc::[] +[role="_abstract"] +Troubleshoot the installation of {product-title} clusters by completing the following instructions. + include::modules/rosa-troubleshooting-installing.adoc[leveloffset=+1] diff --git a/support/troubleshooting/rosa-troubleshooting-networking.adoc b/support/troubleshooting/rosa-troubleshooting-networking.adoc index d8e4049e9a8..0c0c8c0fbf3 100644 --- a/support/troubleshooting/rosa-troubleshooting-networking.adoc +++ b/support/troubleshooting/rosa-troubleshooting-networking.adoc @@ -1,11 +1,13 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/attributes-openshift-dedicated.adoc[] [id="rosa-troubleshooting-networking"] = Troubleshooting networking + +include::_attributes/attributes-openshift-dedicated.adoc[] :context: rosa-troubleshooting-networking toc::[] -This document describes how to troubleshoot networking errors. +[role="_abstract"] +Troubleshoot networking errors by completing the following instructions. include::modules/rosa-troubleshooting-networking-nlb.adoc[leveloffset=+1] \ No newline at end of file diff --git a/support/troubleshooting/sd-managed-resources.adoc b/support/troubleshooting/sd-managed-resources.adoc index fef76818997..5d7c9250fc5 100644 --- a/support/troubleshooting/sd-managed-resources.adoc +++ b/support/troubleshooting/sd-managed-resources.adoc @@ -9,6 +9,7 @@ toc::[] [id="sd-managed-resources-overview_{context}"] == Overview +[role="_abstract"] The following covers all {product-title} resources that are managed or protected by the Service Reliability Engineering Platform (SRE-P) Team. Customers must not modify these resources because doing so can lead to cluster instability. [id="sd-managed-resources-all_{context}"] @@ -17,7 +18,7 @@ ifdef::openshift-rosa,openshift-dedicated[] The following list displays the {product-title} resources managed by OpenShift Hive, the centralized fleet configuration management system. These resources are in addition to the OpenShift Container Platform resources created during installation. OpenShift Hive continually attempts to maintain consistency across all {product-title} clusters. Changes to {product-title} resources should be made through {cluster-manager} so that {cluster-manager} and Hive are synchronized. Contact `ocm-feedback@redhat.com` if {cluster-manager} does not support modifying the resources in question. -.List of Hive managed resources +== List of Hive managed resources endif::openshift-rosa,openshift-dedicated[] ifdef::openshift-rosa-hcp[] == Red{nbsp}Hat managed resources @@ -26,13 +27,10 @@ The following resources are created and managed by the management cluster, which .List of Red{nbsp}Hat managed resources endif::openshift-rosa-hcp[] -[%collapsible] -==== [source,yaml] ---- include::https://raw.githubusercontent.com/openshift/managed-cluster-config/master/resources/managed/all-osd-resources.yaml[] ---- -==== //endif::openshift-rosa,openshift-dedicated[] [id="sd-core-namespaces_{context}"] @@ -164,8 +162,6 @@ data: ==== endif::openshift-rosa[] ifdef::openshift-rosa-hcp[] -[%collapsible] -==== [source,yaml] ---- apiVersion: v1 @@ -258,16 +254,12 @@ data: - name: openshift-service-ca-operator - name: openshift-user-workload-monitoring ---- -==== endif::openshift-rosa-hcp[] ifdef::openshift-dedicated[] -[%collapsible] -==== [source,yaml] ---- include::https://raw.githubusercontent.com/openshift/managed-cluster-config/master/deploy/osd-managed-resources/ocp-namespaces.ConfigMap.yaml[] ---- -==== endif::openshift-dedicated[] ifdef::openshift-rosa,openshift-dedicated[] @@ -277,13 +269,10 @@ ifdef::openshift-rosa,openshift-dedicated[] {product-title} add-ons are services available for installation after cluster installation. These additional services include AWS CloudWatch, {openshift-dev-spaces-productname}, Red{nbsp}Hat OpenShift API Management, and Cluster Logging Operator. Any changes to resources within the following namespaces might be overridden by the add-on during upgrades, which can lead to unsupported configurations for the add-on functionality. .List of add-on managed namespaces -[%collapsible] -==== [source,yaml] ---- include::https://raw.githubusercontent.com/openshift/managed-cluster-config/master/resources/addons-namespaces/main.yaml[] ---- -==== endif::openshift-rosa,openshift-dedicated[] [id="sd-validating-webhooks_{context}"] @@ -292,10 +281,7 @@ endif::openshift-rosa,openshift-dedicated[] {product-title} validating webhooks are a set of dynamic admission controls maintained by the OpenShift SRE team. These HTTP callbacks, also known as webhooks, are called for various types of requests to ensure cluster stability. The webhooks evaluate each request and either accept or reject them. The following list describes the various webhooks with rules containing the registered operations and resources that are controlled. Any attempt to circumvent these validating webhooks could affect the stability and supportability of the cluster. .List of validating webhooks -[%collapsible] -==== [source,json] ---- include::https://raw.githubusercontent.com/openshift/managed-cluster-validating-webhooks/master/docs/webhooks.json[] ----- -==== +---- \ No newline at end of file diff --git a/support/troubleshooting/troubleshooting-crio-issues.adoc b/support/troubleshooting/troubleshooting-crio-issues.adoc index 13cd9a28524..f4bd92e47fa 100644 --- a/support/troubleshooting/troubleshooting-crio-issues.adoc +++ b/support/troubleshooting/troubleshooting-crio-issues.adoc @@ -1,11 +1,15 @@ :_mod-docs-content-type: ASSEMBLY [id="troubleshooting-crio-issues"] = Troubleshooting CRI-O container runtime issues + include::_attributes/common-attributes.adoc[] :context: troubleshooting-crio-issues toc::[] +[role="_abstract"] +Use the following sections to troubleshoot CRI-O container runtime issues. + // About CRI-O container runtime engine include::modules/about-crio.adoc[leveloffset=+1] diff --git a/support/troubleshooting/troubleshooting-installations.adoc b/support/troubleshooting/troubleshooting-installations.adoc index 7f341e4d80b..d37550e8634 100644 --- a/support/troubleshooting/troubleshooting-installations.adoc +++ b/support/troubleshooting/troubleshooting-installations.adoc @@ -1,11 +1,15 @@ :_mod-docs-content-type: ASSEMBLY [id="troubleshooting-installations"] = Troubleshooting installations + include::_attributes/common-attributes.adoc[] :context: troubleshooting-installations toc::[] +[role="_abstract"] +Use the following sections to troubleshoot {product-title} installation issues. + // Determining where installation issues occur include::modules/determining-where-installation-issues-occur.adoc[leveloffset=+1] @@ -49,7 +53,7 @@ ifndef::openshift-rosa,openshift-dedicated[] [role="_additional-resources"] == Additional resources -* See xref:../../architecture/architecture-installation.adoc#installation-process_architecture-installation[Installation process] for more details on {product-title} installation types and process. +* xref:../../architecture/architecture-installation.adoc#installation-process_architecture-installation[Installation process] endif::openshift-rosa,openshift-dedicated[] // TODO: xref to UPI recommendations for respective versions, with ifdefs. diff --git a/support/troubleshooting/troubleshooting-network-issues.adoc b/support/troubleshooting/troubleshooting-network-issues.adoc index bb4f89b2d74..c288f244148 100644 --- a/support/troubleshooting/troubleshooting-network-issues.adoc +++ b/support/troubleshooting/troubleshooting-network-issues.adoc @@ -1,11 +1,15 @@ :_mod-docs-content-type: ASSEMBLY [id="troubleshooting-network-issues"] = Troubleshooting network issues + include::_attributes/common-attributes.adoc[] :context: troubleshooting-network-issues toc::[] +[role="_abstract"] +Use the following sections to troubleshoot network issues. + // How the network interface is selected include::modules/nw-how-nw-iface-selected.adoc[leveloffset=+1] diff --git a/support/troubleshooting/troubleshooting-operating-system-issues.adoc b/support/troubleshooting/troubleshooting-operating-system-issues.adoc index 4535733b9a2..070ec3a1ccc 100644 --- a/support/troubleshooting/troubleshooting-operating-system-issues.adoc +++ b/support/troubleshooting/troubleshooting-operating-system-issues.adoc @@ -1,11 +1,13 @@ :_mod-docs-content-type: ASSEMBLY [id="troubleshooting-operating-system-issues"] = Troubleshooting operating system issues + include::_attributes/common-attributes.adoc[] :context: troubleshooting-operating-system-issues toc::[] +[role="_abstract"] {product-title} runs on {op-system}. You can follow these procedures to troubleshoot problems related to the operating system. // Investigating kernel crashes @@ -18,8 +20,8 @@ include::modules/troubleshooting-enabling-kdump-day-one.adoc[leveloffset=+2] include::modules/troubleshooting-kdump-testing-analyzing.adoc[leveloffset=+2] [role="_additional-resources"] -[id="additional-resources_investigating-kernel-crashes"] -=== Additional resources +.Additional resources + ifdef::openshift-origin[] * link:https://docs.fedoraproject.org/en-US/fedora-coreos/debugging-kernel-crashes/[Fedora CoreOS Docs on debugging kernel crashes] * link:https://fedoraproject.org/wiki/How_to_use_kdump_to_debug_kernel_crashes[Setting up kdump in Fedora] @@ -28,8 +30,8 @@ ifdef::openshift-enterprise[] * link:https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/managing_monitoring_and_updating_the_kernel/configuring-kdump-on-the-command-line_managing-monitoring-and-updating-the-kernel[Setting up kdump in RHEL] endif::[] * link:https://www.kernel.org/doc/html/latest/admin-guide/kdump/kdump.html[Linux kernel documentation for kdump] -* kdump.conf(5) — a manual page for the `/etc/kdump.conf` configuration file containing the full documentation of available options -* kexec(8) — a manual page for the `kexec` package -* link:https://access.redhat.com/site/solutions/6038[Red Hat Knowledgebase article] regarding kexec and kdump +* link:https://www.kernel.org/doc/html/latest/admin-guide/kdump/kdump.html#configuration[kdump.conf(5) manual page] +* link:https://www.kernel.org/doc/html/latest/admin-guide/kdump/kdump.html[kexec(8) manual page] +* link:https://access.redhat.com/site/solutions/6038[Red Hat Knowledgebase article regarding kexec and kdump] include::modules/troubleshooting-debugging-ignition.adoc[leveloffset=+1] diff --git a/support/troubleshooting/troubleshooting-operator-issues.adoc b/support/troubleshooting/troubleshooting-operator-issues.adoc index d969db7a0a4..69a72055d8f 100644 --- a/support/troubleshooting/troubleshooting-operator-issues.adoc +++ b/support/troubleshooting/troubleshooting-operator-issues.adoc @@ -1,6 +1,7 @@ :_mod-docs-content-type: ASSEMBLY [id="troubleshooting-operator-issues"] = Troubleshooting Operator issues + include::_attributes/common-attributes.adoc[] :context: troubleshooting-operator-issues @@ -8,6 +9,9 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] +A cluster administrator can do the following to resolve Operator issues: verify Operator subscription status, check Operator pod health, and gather Operator logs. + Operators are a method of packaging, deploying, and managing an {product-title} application. They act like an extension of the software vendor's engineering team, watching over an {product-title} environment and using its current state to make decisions in real time. Operators are designed to handle upgrades seamlessly, react to failures automatically, and not take shortcuts, such as skipping a software backup process to save time. {product-title} {product-version} includes a default set of Operators that are required for proper functioning of the cluster. These default Operators are managed by the Cluster Version Operator (CVO). @@ -22,7 +26,7 @@ include::modules/olm-status-conditions.adoc[leveloffset=+1] // TODO: Add this xref when the Operators book is added to ROSA HCP. ifndef::openshift-rosa-hcp[] [role="_additional-resources"] -.Additional resources +== Additional resources * xref:../../operators/understanding/olm/olm-understanding-olm.adoc#olm-cs-health_olm-understanding-olm[Catalog health requirements] endif::openshift-rosa-hcp[] @@ -34,7 +38,7 @@ include::modules/olm-status-viewing-cli.adoc[leveloffset=+1] include::modules/olm-cs-status-cli.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +== Additional resources // TODO: Add this xref when the Operators book is added to ROSA HCP. ifndef::openshift-rosa-hcp[] @@ -78,7 +82,7 @@ ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[] include::modules/olm-reinstall.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +== Additional resources * xref:../../operators/admin/olm-deleting-operators-from-cluster.adoc#olm-deleting-operators-from-a-cluster[Deleting Operators from a cluster] * xref:../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[Adding Operators to a cluster] diff --git a/support/troubleshooting/troubleshooting-osd-gcp-cluster-deployment.adoc b/support/troubleshooting/troubleshooting-osd-gcp-cluster-deployment.adoc index 61262c250b0..71448fc3326 100644 --- a/support/troubleshooting/troubleshooting-osd-gcp-cluster-deployment.adoc +++ b/support/troubleshooting/troubleshooting-osd-gcp-cluster-deployment.adoc @@ -1,11 +1,13 @@ :_mod-docs-content-type: ASSEMBLY -include::_attributes/common-attributes.adoc[] [id="troubleshooting-osd-gcp-cluster-deployment"] -= Troubleshooting an {product-title} on {gcp-short} cluster deployment += Troubleshooting an {product-title} on Google Cloud cluster deployment + +include::_attributes/common-attributes.adoc[] :context: troubleshooting-osd-gcp-cluster-deployment toc::[] +[role="_abstract"] {product-title} on {gcp-first} cluster deployment errors can occur for several reasons, including insufficient quota limits and settings, incorrectly inputted data, incompatible configurations, and so on. Learn how to resolve common {product-title} on {gcp-short} cluster installation errors in the following sections. @@ -13,8 +15,8 @@ Learn how to resolve common {product-title} on {gcp-short} cluster installation include::modules/osd-on-gcp-troubleshoot-cluster-install.adoc[leveloffset=+1] [role="_additional-resources"] -.Additional resources +== Additional resources -* For more information about {product-title} on {gcp-short} instance types, see xref:../../osd_architecture/osd_policy/osd-service-definition.adoc#gcp-compute-types_osd-service-definition[{gcp-full} instance types]. +* xref:../../osd_architecture/osd_policy/osd-service-definition.adoc#gcp-compute-types_osd-service-definition[{gcp-full} instance types] diff --git a/support/troubleshooting/troubleshooting-s2i.adoc b/support/troubleshooting/troubleshooting-s2i.adoc index dc1e4bf9abf..e7984999a3a 100644 --- a/support/troubleshooting/troubleshooting-s2i.adoc +++ b/support/troubleshooting/troubleshooting-s2i.adoc @@ -1,11 +1,15 @@ :_mod-docs-content-type: ASSEMBLY [id="troubleshooting-s2i"] = Troubleshooting the Source-to-Image process + include::_attributes/common-attributes.adoc[] :context: troubleshooting-s2i toc::[] +[role="_abstract"] +A cluster administrator can observe the S2I stages to determine where in the S2I process a failure occurred and gather diagnostic data to resolve Source-to-Image issues. + // Strategies for Source-to-Image troubleshooting include::modules/strategies-for-s2i-troubleshooting.adoc[leveloffset=+1] @@ -19,5 +23,5 @@ ifndef::openshift-rosa,openshift-dedicated[] [role="_additional-resources"] == Additional resources -* See xref:../../cicd/builds/build-strategies.adoc#build-strategy-s2i_build-strategies[Source-to-Image (S2I) build] for more details about the S2I build strategy. +* xref:../../cicd/builds/build-strategies.adoc#build-strategy-s2i_build-strategies[Source-to-Image (S2I) build] endif::openshift-rosa,openshift-dedicated[] diff --git a/support/troubleshooting/troubleshooting-storage-issues.adoc b/support/troubleshooting/troubleshooting-storage-issues.adoc index 44505ff0e16..6e39a3fd656 100644 --- a/support/troubleshooting/troubleshooting-storage-issues.adoc +++ b/support/troubleshooting/troubleshooting-storage-issues.adoc @@ -1,10 +1,14 @@ :_mod-docs-content-type: ASSEMBLY [id="troubleshooting-storage-issues"] = Troubleshooting storage issues + include::_attributes/common-attributes.adoc[] :context: troubleshooting-storage-issues toc::[] +[role="_abstract"] +A multi-attach storage error occurs when the mounting volume on a new node is not possible because the failed node cannot unmount the attached volume. A cluster administrator can resolve multi-attach storage issues by enabling multiple attachments using RWX volumes or recovering/deleting the failed node when using an RWO volume. + // Multi-attach error resolution include::modules/storage-multi-attach-error.adoc[leveloffset=+1] diff --git a/support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc b/support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc index 6437cdd9e84..e9eed4bc3be 100644 --- a/support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc +++ b/support/troubleshooting/troubleshooting-windows-container-workload-issues.adoc @@ -1,30 +1,25 @@ :_mod-docs-content-type: ASSEMBLY [id="troubleshooting-windows-container-workload-issues"] = Troubleshooting Windows container workload issues + include::_attributes/common-attributes.adoc[] :context: troubleshooting-windows-container-workload-issues toc::[] -include::modules/wmco-does-not-install.adoc[leveloffset=+1] +[role="_abstract"] +Use the following sections to troubleshoot Windows container workload issues. -For more information, see xref:../../networking/ovn_kubernetes_network_provider/configuring-hybrid-networking.adoc#configuring-hybrid-ovnkubernetes[Configuring hybrid networking]. +include::modules/wmco-does-not-install.adoc[leveloffset=+1] include::modules/investigating-why-windows-machine-compute-node.adoc[leveloffset=+1] -[id="accessing-windows-node"] -== Accessing a Windows node - -Windows nodes cannot be accessed using the `oc debug node` command; the command requires running a privileged pod on the node, which is not yet supported for Windows. Instead, a Windows node can be accessed using a secure shell (SSH) or Remote Desktop Protocol (RDP). An SSH bastion is required for both methods. - +include::modules/accessing-windows-node.adoc[leveloffset=+1] include::modules/accessing-windows-node-using-ssh.adoc[leveloffset=+2] - include::modules/accessing-windows-node-using-rdp.adoc[leveloffset=+2] include::modules/collecting-kube-node-logs-windows.adoc[leveloffset=+1] - include::modules/collecting-windows-application-event-logs.adoc[leveloffset=+1] - include::modules/collecting-containerd-logs-windows.adoc[leveloffset=+1] // Also update windows-containers/windows-containers-troubleshooting.adoc @@ -32,6 +27,7 @@ include::modules/collecting-containerd-logs-windows.adoc[leveloffset=+1] [role="_additional-resources"] == Additional resources +* xref:../../networking/ovn_kubernetes_network_provider/configuring-hybrid-networking.adoc#configuring-hybrid-ovnkubernetes[Configuring hybrid networking] * link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/troubleshooting[Containers on Windows troubleshooting] * link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/update-containers#troubleshoot-host-and-container-image-mismatches[Troubleshoot host and container image mismatches] * link:https://docs.microsoft.com/en-us/virtualization/windowscontainers/kubernetes/common-problems[Common Kubernetes problems with Windows] diff --git a/support/troubleshooting/verifying-node-health.adoc b/support/troubleshooting/verifying-node-health.adoc index 5f458c81840..e80e4539e04 100644 --- a/support/troubleshooting/verifying-node-health.adoc +++ b/support/troubleshooting/verifying-node-health.adoc @@ -1,11 +1,15 @@ :_mod-docs-content-type: ASSEMBLY [id="verifying-node-health"] = Verifying node health + include::_attributes/common-attributes.adoc[] :context: verifying-node-health toc::[] +[role="_abstract"] +You can verify and troubleshoot node-related issues by reviewing the status, resource usage, and configuration of a node. + // Reviewing node status, resource usage, and configuration include::modules/reviewing-node-status-usage-and-configuration.adoc[leveloffset=+1]