RedHatQE · hmeir · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -218,6 +218,51 @@ When reviewing quarantine PRs, verify the **quarantine mechanism matches the fai
 - **Use identity for None** - `if x is None:` NOT `if x == None:`
 - **NEVER compare to True/False** - `if flag:` NOT `if flag == True:`
 
+### HCO v1 API Usage (MANDATORY)
+
+All HCO spec patches and reads MUST use the v1 grouped API structure. Use `HCOv1Spec` builders from `utilities.constants.hco` to construct patches.
+
+**Available builders:**
+- `HCOv1Spec.virtualization(field=value)` — virtualization fields (live migration, CPU, etc.)
+- `HCOv1Spec.security(field=value)` — security fields (TLS profiles, etc.)
+- `HCOv1Spec.storage(field=value)` — storage fields
+- `HCOv1Spec.deployment(field=value)` — deployment fields
+- `HCOv1Spec.workload_sources(field=value)` — workload source fields
+- `HCOv1Spec.networking(field=value)` — networking fields
+- `HCOv1Spec.node_placements(infra=..., workload=...)` — node placement
+- `HCOv1Spec.vm_options(field=value)` — virtualMachineOptions
+- `HCOv1Spec.aaq_config(field=value)` — applicationAwareConfig
+
+**Rules:**
+
+1. **HCO spec patches MUST use v1 grouped structure** — use `HCOv1Spec` builders, NEVER construct raw nested dicts manually
+2. **Feature gates MUST use v1 list format** — use `HCOv1Spec.feature_gates(name=True/False)`, NEVER dict format `{"featureGates": {"name": true}}`
+3. **NEVER use v1beta1 flat spec paths** — `spec.liveMigrationConfig` is wrong, `spec.virtualization.liveMigrationConfig` is correct. See `HCOv1Spec` group builders in `utilities/constants/hco.py` for the complete mapping
+4. **FG state reads MUST use `HCOv1Spec.is_fg_enabled()`** with the `hco_fg_phases` fixture, not direct list searching. For deprecated FGs, read the dedicated spec field instead
+5. **`spec.workloads` is renamed to `workload` (singular)** in v1 under `spec.deployment.nodePlacements.workload`
+
+**Before (v1beta1 -- WRONG):**
+```python
+# Flat spec path -- WRONG
+patch = {"spec": {"liveMigrationConfig": {"parallelOutboundMigrationsPerNode": 5}}}
+hco_resource.update(resource_dict=patch)
+
+# Dict feature gate -- WRONG
+fg_patch = {"spec": {"featureGates": {"withHostPassthroughCPU": True}}}
+```
+
+**After (v1 -- CORRECT):**
+```python
+from utilities.constants.hco import HCOv1Spec
+
+# Grouped spec path
+patch = HCOv1Spec.virtualization(liveMigrationConfig={"parallelOutboundMigrationsPerNode": 5})
+hco_resource.update(resource_dict=patch)
+
+# List feature gate
+fg_patch = HCOv1Spec.feature_gates(withHostPassthroughCPU=True)
+```
+
 ### Tests Directory Organization
 
 - **Feature subdirectories REQUIRED** - each feature MUST have its own subdirectory under component (e.g., `tests/network/ipv6/`)

diff --git a/pyproject.toml b/pyproject.toml
@@ -118,7 +118,7 @@ dependencies = [
   "xmltodict>=0.14.2",
   "python-simple-logger>=2.0.13",
   "pytest-html>=4.1.1",
-  "openshift-python-wrapper>=11.0.132",
+  "openshift-python-wrapper>=11.0.139",
   "cachetools>=6.2.2",
   "dacite>=1.9.2",
   "python-dotenv>=1.2.1",

diff --git a/tests/conftest.py b/tests/conftest.py
@@ -110,6 +110,7 @@
     HCO_SUBSCRIPTION,
     HOTFIX_STR,
     SSP_CR_COMMON_TEMPLATES_LIST_KEY_NAME,
+    HCOv1Spec,
     UpgradeStreams,
 )
 from utilities.constants.images import OS_FLAVOR_RHEL
@@ -1235,6 +1236,11 @@ def hyperconverged_resource_scope_session(admin_client, hco_namespace, installin
         return get_hyperconverged_resource(client=admin_client, hco_ns_name=hco_namespace.name)
 
 
+@pytest.fixture(scope="session")
+def hco_fg_phases(admin_client):
+    return utilities.hco.parse_hco_fg_phases(admin_client=admin_client)
+
+
 @pytest.fixture()
 def kubevirt_hyperconverged_spec_scope_function(admin_client, hco_namespace, installing_cnv):
     if not installing_cnv:
@@ -1304,8 +1310,10 @@ def hyperconverged_with_node_placement(request, admin_client, hco_namespace, hyp
     workloads_placement = request.param["workloads"]
 
     LOGGER.info("Fetching HCO to save its initial node placement configuration ")
-    initial_infra = hyperconverged_resource_scope_class.instance.to_dict()["spec"].get("infra", {})
-    initial_workloads = hyperconverged_resource_scope_class.instance.to_dict()["spec"].get("workloads", {})
+    spec = hyperconverged_resource_scope_class.instance.to_dict()["spec"]
+    node_placements = HCOv1Spec.node_placements.read(spec=spec, default={})
+    initial_infra = node_placements.get("infra", {})
+    initial_workloads = node_placements.get("workload", {})
     yield utilities.hco.apply_np_changes(
         admin_client=admin_client,
         hco=hyperconverged_resource_scope_class,

diff --git a/tests/infrastructure/golden_images/update_boot_source/conftest.py b/tests/infrastructure/golden_images/update_boot_source/conftest.py
@@ -17,6 +17,7 @@
     get_all_release_versions_from_docs,
 )
 from utilities.constants import Images
+from utilities.constants.hco import HCOv1Spec
 from utilities.constants.images import DEFAULT_FEDORA_REGISTRY_URL
 from utilities.constants.storage import BIND_IMMEDIATE_ANNOTATION
 from utilities.constants.timeouts import (
@@ -82,7 +83,9 @@ def updated_hco_with_custom_data_import_cron_scope_function(
     with ResourceEditorValidateHCOReconcile(
         admin_client=admin_client,
         patches={
-            hyperconverged_resource_scope_function: {"spec": {"dataImportCronTemplates": [data_import_cron_dict]}}
+            hyperconverged_resource_scope_function: HCOv1Spec.workload_sources(
+                dataImportCronTemplates=[data_import_cron_dict]
+            )
         },
         list_resource_reconcile=[SSP, CDI],
     ):
@@ -170,9 +173,9 @@ def updated_data_import_cron(
     )
     with ResourceEditor(
         patches={
-            hyperconverged_resource_scope_function: {
-                "spec": {"dataImportCronTemplates": [updated_hco_with_custom_data_import_cron_scope_function]}
-            }
+            hyperconverged_resource_scope_function: HCOv1Spec.workload_sources(
+                dataImportCronTemplates=[updated_hco_with_custom_data_import_cron_scope_function],
+            )
         }
     ):
         yield

diff --git a/tests/infrastructure/vhostmd/test_downwardmetrics_virtio.py b/tests/infrastructure/vhostmd/test_downwardmetrics_virtio.py
@@ -19,6 +19,7 @@
 )
 from pyhelper_utils.shell import run_ssh_commands
 
+from utilities.constants.hco import HCOv1Spec
 from utilities.constants.images import OS_FLAVOR_RHEL
 from utilities.hco import ResourceEditorValidateHCOReconcile
 from utilities.virt import VirtualMachineForTests, wait_for_running_vm
@@ -98,7 +99,7 @@ def enabled_feature_gate_for_downward_metrics_scope_function(
 ):
     with ResourceEditorValidateHCOReconcile(
         admin_client=admin_client,
-        patches={hyperconverged_resource_scope_function: {"spec": {"featureGates": {"downwardMetrics": True}}}},
+        patches={hyperconverged_resource_scope_function: HCOv1Spec.feature_gates(downwardMetrics=True)},
         list_resource_reconcile=[KubeVirt],
         wait_for_reconcile_post_update=True,
     ):

diff --git a/tests/infrastructure/vhostmd/test_vhostmd.py b/tests/infrastructure/vhostmd/test_vhostmd.py
@@ -14,6 +14,7 @@
 from tests.os_params import RHEL_LATEST_LABELS
 from utilities.artifactory import get_artifactory_header
 from utilities.constants.architecture import S390X
+from utilities.constants.hco import HCOv1Spec
 from utilities.constants.timeouts import (
     TIMEOUT_3MIN,
     TIMEOUT_5SEC,
@@ -57,7 +58,7 @@ def download_and_install_vm_dump_metrics(vm, rpm_file_name):
 def enabled_downward_metrics_hco_featuregate(admin_client, hyperconverged_resource_scope_module):
     with ResourceEditorValidateHCOReconcile(
         admin_client=admin_client,
-        patches={hyperconverged_resource_scope_module: {"spec": {"featureGates": {"downwardMetrics": True}}}},
+        patches={hyperconverged_resource_scope_module: HCOv1Spec.feature_gates(downwardMetrics=True)},
         list_resource_reconcile=[KubeVirt],
         wait_for_reconcile_post_update=True,
     ):

diff --git a/tests/install_upgrade_operators/conftest.py b/tests/install_upgrade_operators/conftest.py
@@ -13,10 +13,7 @@
 from pytest_testconfig import py_config
 
 from tests.install_upgrade_operators.constants import (
-    ENABLE_MULTI_ARCH_BOOT_IMAGE_IMPORT,
     EXPECTED_KUBEVIRT_HARDCODED_FEATUREGATES,
-    FG_ENABLED,
-    HCO_DEFAULT_FEATUREGATES,
     RESOURCE_NAME_STR,
     RESOURCE_NAMESPACE_STR,
     RESOURCE_TYPE_STR,
@@ -27,7 +24,6 @@
     get_resource_by_name,
     get_resource_from_module_name,
 )
-from utilities.constants.architecture import MULTIARCH
 from utilities.constants.components import (
     HCO_OPERATOR,
     HOSTPATH_PROVISIONER_CSI,
@@ -305,9 +301,6 @@ def expected_value(request, is_s390x_cluster):
     expected = request.param.copy()
     if expected == EXPECTED_KUBEVIRT_HARDCODED_FEATUREGATES and is_s390x_cluster:
         expected |= S390X_SPECIFIC_KUBEVIRT_FEATUREGATES
-    if expected == HCO_DEFAULT_FEATUREGATES:
-        if py_config["cluster_type"] == MULTIARCH:
-            expected[ENABLE_MULTI_ARCH_BOOT_IMAGE_IMPORT] = FG_ENABLED
     return expected
 
 

diff --git a/tests/install_upgrade_operators/constants.py b/tests/install_upgrade_operators/constants.py
@@ -12,10 +12,6 @@
 DEVELOPER_CONFIGURATION = "developerConfiguration"
 MEDIATED_DEVICES_CONFIGURATION = "mediatedDevicesConfiguration"
 # featuregates:
-DEPLOY_KUBE_SECONDARY_DNS = "deployKubeSecondaryDNS"
-ENABLE_MULTI_ARCH_BOOT_IMAGE_IMPORT = "enableMultiArchBootImageImport"
-PERSISTENT_RESERVATION = "persistentReservation"
-FG_DISABLED = False
 FG_ENABLED = True
 
 FEATUREGATES = "featureGates"
@@ -38,18 +34,6 @@
     "HonorWaitForFirstConsumer",
     "WebhookPvcRendering",
 }
-HCO_DEFAULT_FEATUREGATES = {
-    DEPLOY_KUBE_SECONDARY_DNS: FG_DISABLED,
-    PERSISTENT_RESERVATION: FG_DISABLED,
-    "alignCPUs": FG_DISABLED,
-    "downwardMetrics": FG_DISABLED,
-    ENABLE_MULTI_ARCH_BOOT_IMAGE_IMPORT: FG_DISABLED,
-    "decentralizedLiveMigration": FG_ENABLED,
-    "declarativeHotplugVolumes": FG_ENABLED,
-    "objectGraph": FG_DISABLED,
-    "incrementalBackup": FG_DISABLED,
-    "containerPathVolumes": FG_DISABLED,
-}
 CUSTOM_DATASOURCE_NAME = "custom-datasource"
 WORKLOAD_UPDATE_STRATEGY_KEY_NAME = "workloadUpdateStrategy"
 KUBEMACPOOL_SERVICE = "kubemacpool-service"

diff --git a/tests/install_upgrade_operators/crypto_policy/test_crypto_policy_default.py b/tests/install_upgrade_operators/crypto_policy/test_crypto_policy_default.py
@@ -11,6 +11,7 @@
 
 from tests.install_upgrade_operators.constants import (
     KEY_NAME_STR,
+    KEY_PATH_SEPARATOR,
     RESOURCE_NAME_STR,
     RESOURCE_NAMESPACE_STR,
     RESOURCE_TYPE_STR,
@@ -54,7 +55,7 @@
                 RESOURCE_TYPE_STR: HyperConverged,
                 RESOURCE_NAME_STR: py_config["hco_cr_name"],
                 RESOURCE_NAMESPACE_STR: py_config["hco_namespace"],
-                KEY_NAME_STR: TLS_SECURITY_PROFILE,
+                KEY_NAME_STR: f"security{KEY_PATH_SEPARATOR}{TLS_SECURITY_PROFILE}",
             },
             HyperConverged,
             marks=(pytest.mark.polarion("CNV-9464")),

diff --git a/tests/install_upgrade_operators/crypto_policy/test_hco_crypto_policy_propagation.py b/tests/install_upgrade_operators/crypto_policy/test_hco_crypto_policy_propagation.py
@@ -12,7 +12,7 @@
     assert_crypto_policy_propagated_to_components,
     set_hco_crypto_policy,
 )
-from utilities.constants.hco import TLS_SECURITY_PROFILE
+from utilities.constants.hco import TLS_SECURITY_PROFILE, HCOv1Spec
 
 LOGGER = logging.getLogger(__name__)
 pytestmark = [pytest.mark.post_upgrade, pytest.mark.sno, pytest.mark.s390x]
@@ -22,13 +22,13 @@
 def hco_crypto_policy(
     hyperconverged_resource_scope_function, updated_hco_crypto_policy, cnv_crypto_policy_matrix__function__
 ):
-    tls_profile = hyperconverged_resource_scope_function.instance.spec.get(TLS_SECURITY_PROFILE)
+    spec = hyperconverged_resource_scope_function.instance.to_dict()["spec"]
+    tls_profile = HCOv1Spec.security.read(spec=spec, default={}).get(TLS_SECURITY_PROFILE)
     if not tls_profile:
         return None
-    tls_dict = tls_profile.to_dict()
     # OCP 4.22+ API adds empty profile-type keys (e.g. old: {}, custom: {}) as CRD defaults
     expected = CRYPTO_POLICY_SPEC_DICT[cnv_crypto_policy_matrix__function__]
-    return {policy_key: policy_value for policy_key, policy_value in tls_dict.items() if policy_key in expected}
+    return {policy_key: policy_value for policy_key, policy_value in tls_profile.items() if policy_key in expected}
 
 
 @pytest.fixture()

diff --git a/tests/install_upgrade_operators/crypto_policy/test_hco_custom_profile_negative.py b/tests/install_upgrade_operators/crypto_policy/test_hco_custom_profile_negative.py
@@ -10,7 +10,7 @@
 )
 from utilities.constants.hco import (
     TLS_CUSTOM_POLICY,
-    TLS_SECURITY_PROFILE,
+    HCOv1Spec,
 )
 from utilities.hco import ResourceEditorValidateHCOReconcile
 
@@ -33,7 +33,7 @@ def test_set_hco_crypto_failed_without_required_cipher(
         "ECDHE-ECDSA-AES256-GCM-SHA384",
         "ECDHE-RSA-AES256-GCM-SHA384",
     ]
-    tls_spec = {"spec": {TLS_SECURITY_PROFILE: tls_custom_profile}}
+    tls_spec = HCOv1Spec.security(tlsSecurityProfile=tls_custom_profile)
     with pytest.raises(ForbiddenError, match=r"missing an HTTP/2-required"):
         with ResourceEditorValidateHCOReconcile(
             admin_client=admin_client,
@@ -54,7 +54,7 @@ def test_set_ciphers_for_tlsv13(admin_client, hyperconverged_resource_scope_func
     with pytest.raises(ForbiddenError, match=error_string):
         with ResourceEditorValidateHCOReconcile(
             admin_client=admin_client,
-            patches={hyperconverged_resource_scope_function: {"spec": {TLS_SECURITY_PROFILE: tls_custom_profile}}},
+            patches={hyperconverged_resource_scope_function: HCOv1Spec.security(tlsSecurityProfile=tls_custom_profile)},
         ):
             LOGGER.error(
                 "Setting HCO with custom tlsSecurityProfile with TLS Version 1.3 "

diff --git a/tests/install_upgrade_operators/crypto_policy/utils.py b/tests/install_upgrade_operators/crypto_policy/utils.py
@@ -31,7 +31,7 @@
     get_resource_key_value,
 )
 from utilities.constants.components import CLUSTER
-from utilities.constants.hco import TLS_SECURITY_PROFILE
+from utilities.constants.hco import TLS_SECURITY_PROFILE, HCOv1Spec
 from utilities.constants.timeouts import (
     TIMEOUT_2MIN,
     TIMEOUT_60MIN,
@@ -266,7 +266,7 @@ def assert_tls_ciphers_blocked(utility_pods, node, services, tls_version, allowe
 def set_hco_crypto_policy(admin_client, hco_resource, tls_spec):
     with ResourceEditorValidateHCOReconcile(
         admin_client=admin_client,
-        patches={hco_resource: {"spec": {TLS_SECURITY_PROFILE: tls_spec}}},
+        patches={hco_resource: HCOv1Spec.security(tlsSecurityProfile=tls_spec)},
         wait_for_reconcile_post_update=True,
         list_resource_reconcile=MANAGED_CRS_LIST,
     ):

diff --git a/tests/install_upgrade_operators/csv/test_hco_api_version.py b/tests/install_upgrade_operators/csv/test_hco_api_version.py
@@ -7,6 +7,6 @@
 @pytest.mark.polarion("CNV-5832")
 def test_hyperconverged_cr_api_version(hyperconverged_resource_scope_function):
     """
-    This test will check the Hyperconverged CR's api_version for v1beta1
+    This test will check the Hyperconverged CR's api_version for v1
     """
-    assert Resource.ApiVersion.V1BETA1 in hyperconverged_resource_scope_function.instance.apiVersion
+    assert hyperconverged_resource_scope_function.instance.apiVersion.endswith(f"/{Resource.ApiVersion.V1}")
diff --git a/tests/install_upgrade_operators/feature_gates/test_update_featuregate_hco.py b/tests/install_upgrade_operators/feature_gates/test_update_featuregate_hco.py
@@ -6,7 +6,7 @@
     FG_ENABLED,
     MEDIATED_DEVICES_CONFIGURATION,
 )
-from utilities.constants.hco import DISABLE_MDEV_CONFIGURATION
+from utilities.constants.hco import DISABLE_MDEV_CONFIGURATION, HCOv1Spec
 from utilities.hco import ResourceEditorValidateHCOReconcile
 
 pytestmark = [pytest.mark.s390x, pytest.mark.skip_must_gather_collection]
@@ -20,7 +20,7 @@ def updated_fg_hco(
 ):
     with ResourceEditorValidateHCOReconcile(
         admin_client=admin_client,
-        patches={hyperconverged_resource_scope_function: {"spec": {FEATUREGATES: request.param["featuregate"]}}},
+        patches={hyperconverged_resource_scope_function: request.param["patch"]},
         list_resource_reconcile=[KubeVirt],
         wait_for_reconcile_post_update=True,
     ):
@@ -31,7 +31,7 @@ def updated_fg_hco(
     "updated_fg_hco",
     [
         pytest.param(
-            {"featuregate": {DISABLE_MDEV_CONFIGURATION: FG_ENABLED}},
+            {"patch": HCOv1Spec.feature_gates(disableMDevConfiguration=FG_ENABLED)},
             marks=pytest.mark.polarion("CNV-10091"),
             id="test_enable_fg_disable_mdev_config_hco",
         ),
@@ -41,10 +41,12 @@ def updated_fg_hco(
 def test_enable_fg_hco(
     updated_fg_hco,
     hco_spec,
+    hco_fg_phases,
     kubevirt_resource,
 ):
-    assert hco_spec[FEATUREGATES][DISABLE_MDEV_CONFIGURATION] is True, (
-        f"HCO featureGates.{DISABLE_MDEV_CONFIGURATION} is not True: {hco_spec[FEATUREGATES]}"
+    fg_list = hco_spec[FEATUREGATES]
+    assert HCOv1Spec.is_fg_enabled(feature_gates=fg_list, name=DISABLE_MDEV_CONFIGURATION, fg_phases=hco_fg_phases), (
+        f"HCO featureGates.{DISABLE_MDEV_CONFIGURATION} is not enabled: {fg_list}"
     )
 
     kubevirt_mdev_enabled = kubevirt_resource.instance.spec["configuration"][MEDIATED_DEVICES_CONFIGURATION]["enabled"]

diff --git a/...ade_operators/hco_enablement_golden_image_updates/test_enable_common_boot_image_import.py b/...ade_operators/hco_enablement_golden_image_updates/test_enable_common_boot_image_import.py
@@ -6,6 +6,7 @@
     COMMON_TEMPLATES_KEY_NAME,
     ENABLE_COMMON_BOOT_IMAGE_IMPORT,
     SSP_CR_COMMON_TEMPLATES_LIST_KEY_NAME,
+    HCOv1Spec,
 )
 from utilities.hco import wait_for_auto_boot_config_stabilization
 
@@ -33,6 +34,7 @@ def test_enable_and_delete_spec_enable_common_boot_image_import_hco_cr(
     hyperconverged_resource_scope_function,
 ):
     wait_for_auto_boot_config_stabilization(admin_client=admin_client, hco_namespace=hco_namespace)
-    assert not hyperconverged_resource_scope_function.instance.spec[ENABLE_COMMON_BOOT_IMAGE_IMPORT], (
+    spec = hyperconverged_resource_scope_function.instance.to_dict()["spec"]
+    assert not HCOv1Spec.workload_sources.read(spec=spec, default={}).get(ENABLE_COMMON_BOOT_IMAGE_IMPORT, True), (
         f"Spec {ENABLE_COMMON_BOOT_IMAGE_IMPORT} was not disabled in HCO."
     )
diff --git a/tests/install_upgrade_operators/launcher_updates/constants.py b/tests/install_upgrade_operators/launcher_updates/constants.py
@@ -45,4 +45,4 @@
 MOD_CUST_DEFAULT_WORKLOAD_UPDATE_METHOD[WORKLOADUPDATEMETHODS] = DEFAULT_WORKLOAD_UPDATE_METHODS
 
 CUSTOM_STRATEGY = {WORKLOAD_UPDATE_STRATEGY_KEY_NAME: CUSTOM_WORKLOAD_UPDATE_STRATEGY}
-CUSTOM_WORKLOAD_STRATEGY_SPEC = {"spec": CUSTOM_STRATEGY}
+CUSTOM_WORKLOAD_STRATEGY_SPEC = {"spec": {"virtualization": CUSTOM_STRATEGY}}
diff --git a/tests/install_upgrade_operators/launcher_updates/test_negative_kubevirt_update.py b/tests/install_upgrade_operators/launcher_updates/test_negative_kubevirt_update.py
@@ -76,7 +76,7 @@ def test_hyperconverged_reset_custom_workload_update_strategy(
         wait_for_spec_change(
             expected=CUSTOM_WORKLOAD_UPDATE_STRATEGY,
             get_spec_func=lambda: get_hco_spec(admin_client=admin_client, hco_namespace=hco_namespace),
-            base_path=[WORKLOAD_UPDATE_STRATEGY_KEY_NAME],
+            base_path=["virtualization", WORKLOAD_UPDATE_STRATEGY_KEY_NAME],
         )
         wait_for_spec_change(
             expected=CUSTOM_WORKLOAD_UPDATE_STRATEGY,