Summary

Work with Shirley and Krzystof to ensure that the downstream docs point to the alerts and the alerts in the runbooks have a well-formed description.

If new runbooks are added, make sure to add a link to the runbooks from the docs.

See: Updating runbooks

Background

• KubeVirt runbooks are versionless.
• Alert names change. When alert names change, then the docs team deprecates the old name, we clearly mark it as deprecated, and leave it in the list for reference. If renamed, include a link/reference to the new name so that users can easily find the newly named alert.
• KubeVirt runbooks are published in the kubevirt/monitoring GitHub repo.
• OpenShift Virtualization runbooks are published as upstream Markdown files (openshift/runbooks).
• In the downstream docs, we include a list of the alerts where each alert links to the alert in https://github.com/openshift/runbooks.

Goals

• Add new alerts to the list of alerts in the documentation.
• Edit alert descriptions in the repo to ensure the descriptions are clearly explained.
• As a user, I want to find alert names in the documentation along with links to the source of truth in the openshift/runbooks repo.

Updating the runbooks

Runbooks contain information to help users diagnose and resolve issues that trigger OpenShift Virtualization alerts in the OpenShift Container Platform web console.

The purpose of this Jira is to maintain the list of alerts in the documentation by adding new alerts and/or deprecating old alerts.

• You might need to edit content or review the new alert PRs in the follow repos:
  • https://github.com/kubevirt/monitoring/tree/main/docs/runbooks 
  • https://github.com/openshift/runbooks
• Typically changes are made upstream first and scripts will sync the updates to the downstream repo. The standards are the same for both repos. Not quite docs standards but as close as you can reasonably get.
• The files need to pass the markdown linter (applies to both repos) before merging.
  When opening a PR, try to get two approvals, but one is sometimes all it takes for the downstream repo to auto-merge your PR, so be aware that that might happen.
• The GitHub usernames for the main SMEs you might need to contact for reviews (or who might contact you) are sradco (Shirly) and machadovilaca (Joao).
• Runbooks in the docs contain links to the openshift/monitoring repo on GitHub.
• Do not change the anchor IDs in the document because for now, the actual alerts have links that include those IDs.
• When maintaining the list, you always cherrypick to all supported versions of the docs (currently 4.12+), because the alerts are versionless.
• This is an example PR: https://github.com/openshift/openshift-docs/pull/78394
• When alerts are deprecated, the runbooks are moved to a deprecated folder (in both the kubevirt/monitoring and openshift/runbooks repos).
• When an alert is deprecated, leave the entry in the virt-runbooks.adoc file but mention that it’s deprecated.
• If leaving the link, change the link to the file’s new location in the deprecated folder. For example: https://docs.openshift.com/container-platform/4.15/virt/monitoring/virt-runbooks.html#virt-runbook-KubeVirtComponentExceedsRequestedCPU
• If an alert name is changed, you can follow this example: https://docs.openshift.com/container-platform/4.15/virt/monitoring/virt-runbooks.html#virt-runbook-VirtualMachineCRCErrors. There is no link to the actual deprecated runbook in this case, because it still contained the previous runbook’s text, which might become out-of-date.