feat: Add pre-upgrade warning for APIC 6.2.1 that downgrade is not supported to pre-6.2.1 version. (#289)

* feat: Add pre-upgrade warning for APIC 6.2.1 that downgrade is not supported to pre-6.2.1 version.

---------

Co-authored-by: Saket <saketk@cisco.com>
Co-authored-by: tkishida <tkishida@cisco.com>

Author: 3 people

aci-preupgrade-validation-script.py

@@ -6007,6 +6007,25 @@ def apic_vmm_inventory_sync_faults_check(**kwargs):
         recommended_action=recommended_action,
         doc_url=doc_url)
 
+
+@check_wrapper(check_title='APIC downgrade compatibility when crossing 6.2 release')
+def apic_downgrade_compat_warning_check(cversion, tversion, **kwargs):
+    result = NA
+    headers = ["Current version", "Target Version", "Warning"]
+    data = []
+    recommended_action = 'No action required. Just be aware of the downgrade limitation after the upgrade.'
+    doc_url = 'https://datacenter.github.io/ACI-Pre-Upgrade-Validation-Script/validations/#apic-downgrade-compatibility-when-crossing-62-release'
+
+    if not tversion or not cversion:
+        return Result(result=MANUAL, msg=TVER_MISSING)
+    if cversion.older_than("6.2(1a)") \
+       and (tversion.same_as("6.2(1a)") or tversion.newer_than("6.2(1a)")):
+        result = MANUAL
+        data.append([cversion, tversion, "Downgrading APIC from 6.2(1)+ to pre-6.2(1) will not be supported."])
+
+    return Result(result=result, headers=headers, data=data, recommended_action=recommended_action, doc_url=doc_url)
+
+
 # ---- Script Execution ----
 
 
@@ -6094,6 +6113,7 @@ class CheckManager:
         post_upgrade_cb_check,
         validate_32_64_bit_image_check,
         fabric_link_redundancy_check,
+        apic_downgrade_compat_warning_check,
 
         # Faults
         apic_disk_space_faults_check,

docs/docs/validations.md

@@ -36,6 +36,7 @@ Items                                                        | This Script
 [6.0(2)+ requires 32 and 64 bit switch images][g16]          | :white_check_mark: | :no_entry_sign:
 [Fabric Link Redundancy][g17]                                | :white_check_mark: | :no_entry_sign:
 [APIC Database Size][g18]                                    | :white_check_mark: | :no_entry_sign:
+[APIC downgrade compatibility when crossing 6.2 release][g19]| :white_check_mark: | :no_entry_sign:
 
 [g1]: #compatibility-target-aci-version
 [g2]: #compatibility-cimc-version
@@ -55,6 +56,7 @@ Items                                                        | This Script
 [g16]: #602-requires-32-and-64-bit-switch-images
 [g17]: #fabric-link-redundancy
 [g18]: #apic-database-size
+[g19]: #apic-downgrade-compatibility-when-crossing-62-release
 
 ### Fault Checks
 Items                                         | Faults         | This Script       | APIC built-in
@@ -495,6 +497,38 @@ For current version is 6.1(3f):
 In either scenario, contact TAC to collect a database dump of the flagged DME(s) and shard(s) for further analysis.
 
 
+### APIC downgrade compatibility when crossing 6.2 release
+
+APIC 6.2(1) release introduces significant optimizations to the APIC upgrade process, including shorter upgrade time and an orchestrated workflow across the cluster with fewer failure points. This release includes an architecture change on APIC, so APIC running 6.2(1) or newer (e.g., 6.2(1a)) cannot be downgraded to any pre-6.2(1) version (e.g., 6.1(4h)).
+
+Upgrading from pre-6.2(1) to 6.2(1)+ is supported; however, rollback (downgrade) after such an upgrade is not possible.
+
+This check alerts you if you are crossing the 6.2 boundary, beyond which downgrade compatibility is lost. No additional user action is required.
+
+!!! note
+    Switch upgrade architecture hasn't been changed in 6.2(1)/16.2(1). The limitation of downgrade compatibility between pre-/post-6.2(1) versions is only for APIC.
+
+!!! example
+    These are examples for upgrade/downgrade paths to show which downgrade compatibility is lost.
+
+    Upgrade:
+
+    * 6.1(4) -> **6.2(1)**: Supported
+    * **6.2(1)** -> 6.2(2): Supported
+
+    Downgrade:
+
+    * **6.2(1)** -> 6.1(4): Not Supported !!! - The API request gets rejected on APIC.
+    * 6.2(2) -> **6.2(1)**: Supported
+
+    Note that this is just one example. See [APIC Upgrade/Downgrade Matrix][2] for the full list of supported version combinations.
+
+!!! tip
+    Make sure to collect the latest configuration backup before you upgrade your APICs from pre-6.2(1) to 6.2(1)+ so that Cisco TAC can perform the fabric recovery process in the case of emergency where you need to downgrade your APICs to the previous version (i.e. 6.2(1)+ -> pre-6.2(1)).
+
+    If it's for a lab environment, you can initialize the fabric and perform a fresh ISO installation of pre-6.2(1) on APICs.
+
+
 ## Fault Check Details
 
 ### APIC Disk Space Usage

tests/checks/apic_downgrade_compat_warning_check/test_apic_downgrade_compat_warning_check.py

@@ -0,0 +1,32 @@
+import importlib
+import logging
+import os
+import pytest
+
+script = importlib.import_module("aci-preupgrade-validation-script")
+
+log = logging.getLogger(__name__)
+dir = os.path.dirname(os.path.abspath(__file__))
+
+test_function = "apic_downgrade_compat_warning_check"
+
+
+@pytest.mark.parametrize(
+    "cversion, tversion, expected_result",
+    [
+        (None, None, script.MANUAL),
+        ("4.2(1b)", None, script.MANUAL),
+        (None, "5.2(2a)", script.MANUAL),
+        ("5.2(2a)", "6.1(4a)", script.NA),
+        ("6.1(3a)", "6.1(4c)", script.NA),
+        ("6.1(3a)", "6.2(1a)", script.MANUAL),
+        ("6.1(3a)", "6.2(2a)", script.MANUAL),
+        ("6.2(1a)", "6.2(2c)", script.NA),
+    ],
+)
+def test_logic(run_check, mock_icurl, cversion, tversion, expected_result):
+    result = run_check(
+        cversion=script.AciVersion(cversion) if cversion else None,
+        tversion=script.AciVersion(tversion) if tversion else None,
+    )
+    assert result.result == expected_result