From cc0482a434bd73c68ad4056dc0c66285eade1dd5 Mon Sep 17 00:00:00 2001
From: Shirly Radco <sradco@redhat.com>
Date: Tue, 13 Jan 2026 10:17:19 +0200
Subject: [PATCH] Update UnsupportedHCOModification runbook

Signed-off-by: Shirly Radco <sradco@redhat.com>
---
 docs/runbooks/UnsupportedHCOModification.md | 37 +++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/runbooks/UnsupportedHCOModification.md b/docs/runbooks/UnsupportedHCOModification.md
index a602e4a7..e464a2d0 100644
--- a/docs/runbooks/UnsupportedHCOModification.md
+++ b/docs/runbooks/UnsupportedHCOModification.md
@@ -38,6 +38,27 @@ annotation:
     severity=info
   ```
 
+To locate and review JSON Patch annotations on the `HyperConverged` resource:
+
+  ```bash
+  # Discover the HCO namespace (commonly 'openshift-cnv' or 'kubevirt-hyperconverged')
+  NS=$(kubectl get hyperconverged -A -o jsonpath='{.items[0].metadata.namespace}')
+
+  # Show annotations on the HyperConverged CR
+  kubectl get hyperconverged -n "${NS}" kubevirt-hyperconverged \
+    -o jsonpath='{.metadata.annotations}'; echo
+  ```
+
+When reviewing the annotations:
+- The jsonpatch annotation keys are fixed and live on the `HyperConverged` CR:
+  - `kubevirt.kubevirt.io/jsonpatch`
+  - `containerizeddataimporter.kubevirt.io/jsonpatch`
+  - `networkaddonsconfigs.kubevirt.io/jsonpatch`
+  - `ssp.kubevirt.io/jsonpatch`
+- Annotations such as `kubevirt.io/latest-observed-api-version` and
+  `kubevirt.io/storage-observed-api-version` are normal KubeVirt annotations and are
+  unrelated to jsonpatch.
+
 ## Mitigation
 
 It is best to use the HCO API to change an operand. However, if the change can
@@ -45,6 +66,22 @@ only be done with a JSON Patch annotation, proceed with caution.
 
 Remove JSON Patch annotations before upgrade to avoid potential issues.
 
+To remove a specific JSON Patch annotation from the `HyperConverged` CR:
+
+  ```bash
+  # Example: remove the KubeVirt jsonpatch annotation key
+  kubectl annotate hyperconverged -n "${NS}" kubevirt-hyperconverged \
+    'kubevirt.kubevirt.io/jsonpatch-'
+
+  # Other examples (use if those annotations are present):
+  # Remove CDI jsonpatch
+  # kubectl annotate hyperconverged -n "${NS}" kubevirt-hyperconverged 'containerizeddataimporter.kubevirt.io/jsonpatch-'
+  # Remove CNAO jsonpatch
+  # kubectl annotate hyperconverged -n "${NS}" kubevirt-hyperconverged 'networkaddonsconfigs.kubevirt.io/jsonpatch-'
+  # Remove SSP jsonpatch
+  # kubectl annotate hyperconverged -n "${NS}" kubevirt-hyperconverged 'ssp.kubevirt.io/jsonpatch-'
+  ```
+
 <!--USstart-->
 If the JSON Patch annotation is generic and useful, you can submit an RFE to add
 the modification to the API by filing a [bug](https://bugzilla.redhat.com/).