From 84335cc8970c623b1f6cab2475cef64ba410659e Mon Sep 17 00:00:00 2001 From: Gabriel Date: Tue, 27 Oct 2026 09:34:05 -0400 Subject: [PATCH 1/4] Clarify missing firmware in bootflash check --- aci-preupgrade-validation-script.py | 9 +++++++-- docs/docs/validations.md | 2 ++ tests/checks/test_result_details.py | 10 ++++++++-- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/aci-preupgrade-validation-script.py b/aci-preupgrade-validation-script.py index 284e09b..37cc63a 100644 --- a/aci-preupgrade-validation-script.py +++ b/aci-preupgrade-validation-script.py @@ -2352,11 +2352,16 @@ def switch_bootflash_usage_check(sw_cversion, tversion, **kwargs): def missing_images(image_rows): return Result( result=MANUAL, + msg=( + "Bootflash capacity was not evaluated because image size information " + "is unavailable for the listed switch firmware." + ), headers=["Image Role", "Architecture", "Filename", "Status"], data=[row + ["Missing"] for row in image_rows], recommended_action=( - "Make the listed images available in the Firmware Repository, " - "then rerun this check." + "Upload or restore each listed switch image in the APIC Firmware Repository. " + "For ACI 6.0(2)+ targets, both 32-bit and 64-bit (-cs_64) switch images " + "are required. Wait for repository synchronization, then rerun this check." ), doc_url=doc_url, ) diff --git a/docs/docs/validations.md b/docs/docs/validations.md index fbf46d8..ab9cde8 100644 --- a/docs/docs/validations.md +++ b/docs/docs/validations.md @@ -694,6 +694,8 @@ The ACI Pre-Upgrade Validation script uses APIC API data to compare each switch' The calculation generally reserves twice the applicable target image size. This accounts for space used by the downloaded image and additional space needed while the image is extracted. For an upgrade that crosses the 6.0(2) image boundary, the calculation accounts for both the 32-bit and 64-bit target images and the space recovered when the current image is removed. +The calculation requires size information for every listed current or target switch image. For 6.0(2)+ targets, both the 32-bit and 64-bit (`-cs_64`) images must be in the APIC Firmware Repository; see [6.0(2)+ requires 32 and 64 bit switch images](#602-requires-32-and-64-bit-switch-images). If an image is missing, the check requires manual review because `/bootflash` capacity was not evaluated, not because insufficient space was detected. + Switches that have already downloaded the target image are still checked because image extraction and later upgrade stages can require additional space. Because the downloaded image is already reflected in the switch's available-space value, the check evaluates only the remaining space required to complete the upgrade. If a switch does not have enough available space, the check reports an upgrade failure and displays the available and required space. Remove old, unused switch images to recover space, then run the validation again. Contact Cisco TAC if sufficient space cannot be recovered. If the current switch version, target firmware image, or `/bootflash` information is unavailable, the check reports that a manual review is required. diff --git a/tests/checks/test_result_details.py b/tests/checks/test_result_details.py index 828a8c3..610bca0 100644 --- a/tests/checks/test_result_details.py +++ b/tests/checks/test_result_details.py @@ -105,6 +105,8 @@ def communicate(self): IMAGE_32 = 'aci-n9000-dk9.16.0.2h.bin' IMAGE_64 = 'aci-n9000-dk9.16.0.2h-cs_64.bin' +IMAGE_609_32 = 'aci-n9000-dk9.16.0.9e.bin' +IMAGE_609_64 = 'aci-n9000-dk9.16.0.9e-cs_64.bin' OLD_IMAGE = 'aci-n9000-dk9.15.2.8h.bin' @@ -115,6 +117,7 @@ def communicate(self): ('6.0(3a)', '6.0(2h)', [IMAGE_32], [['Target', '64-bit', IMAGE_64, 'Missing']]), ('6.0(3a)', '6.0(2h)', [IMAGE_64], [['Target', '32-bit', IMAGE_32, 'Missing']]), ('5.2(8h)', '6.0(2h)', [IMAGE_32, IMAGE_64], [['Current', '32-bit', OLD_IMAGE, 'Missing']]), + ('5.2(6e)', '6.0(9e)', [IMAGE_609_32], [['Target', '64-bit', IMAGE_609_64, 'Missing']]), ]) def test_missing_images_are_results_with_repository_action(monkeypatch, current, target, available, missing): def icurl(_, query): @@ -131,8 +134,11 @@ def icurl(_, query): name = 'switch_bootflash_usage_check' result = run_check(name, sw_cversion=script.AciVersion(current), tversion=script.AciVersion(target)) assert result.result == script.MANUAL - assert result.msg == '' + assert result.msg == ( + 'Bootflash capacity was not evaluated because image size information ' + 'is unavailable for the listed switch firmware.' + ) assert result.headers == ['Image Role', 'Architecture', 'Filename', 'Status'] assert result.data == missing - assert result.recommended_action + assert 'Upload or restore each listed switch image' in result.recommended_action assert_outputs(monkeypatch, name, result, missing[0][2]) From 782d6be883af064104e80b60a97b4c5241495775 Mon Sep 17 00:00:00 2001 From: Gabriel Date: Tue, 27 Oct 2026 09:43:06 -0400 Subject: [PATCH 2/4] Limit tests to data logic and results --- AGENTS.md | 8 ++++++++ tests/checks/test_result_details.py | 12 +----------- 2 files changed, 9 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f30b597..827c143 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,3 +12,11 @@ cx-skills install ACI-PUV-Developers/aci-integration-tests --dir Date: Tue, 27 Oct 2026 09:45:07 -0400 Subject: [PATCH 3/4] Require reference-style documentation links --- AGENTS.md | 6 ++++++ docs/docs/validations.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 827c143..aafd167 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,3 +20,9 @@ update tests for user-facing wording, messages, recommended actions, documentation prose, punctuation, capitalization, or other presentation text. For wording-only changes, run the existing relevant tests without creating or modifying test coverage for the wording. + +## Documentation links + +Never put link destinations directly in documentation prose. Use the +document's existing numbered reference-link system, adding the next appropriate +reference definition when a new destination is needed. diff --git a/docs/docs/validations.md b/docs/docs/validations.md index ab9cde8..749851e 100644 --- a/docs/docs/validations.md +++ b/docs/docs/validations.md @@ -694,7 +694,7 @@ The ACI Pre-Upgrade Validation script uses APIC API data to compare each switch' The calculation generally reserves twice the applicable target image size. This accounts for space used by the downloaded image and additional space needed while the image is extracted. For an upgrade that crosses the 6.0(2) image boundary, the calculation accounts for both the 32-bit and 64-bit target images and the space recovered when the current image is removed. -The calculation requires size information for every listed current or target switch image. For 6.0(2)+ targets, both the 32-bit and 64-bit (`-cs_64`) images must be in the APIC Firmware Repository; see [6.0(2)+ requires 32 and 64 bit switch images](#602-requires-32-and-64-bit-switch-images). If an image is missing, the check requires manual review because `/bootflash` capacity was not evaluated, not because insufficient space was detected. +The calculation requires size information for every listed current or target switch image. For 6.0(2)+ targets, both the 32-bit and 64-bit (`-cs_64`) images must be in the APIC Firmware Repository; see [6.0(2)+ requires 32 and 64 bit switch images][g16]. If an image is missing, the check requires manual review because `/bootflash` capacity was not evaluated, not because insufficient space was detected. Switches that have already downloaded the target image are still checked because image extraction and later upgrade stages can require additional space. Because the downloaded image is already reflected in the switch's available-space value, the check evaluates only the remaining space required to complete the upgrade. From 51f2e4456601ee38ba1f9e5c85811b5f357eb730 Mon Sep 17 00:00:00 2001 From: Gabriel Date: Tue, 27 Oct 2026 12:59:53 -0400 Subject: [PATCH 4/4] Define manual result messaging contract --- AGENTS.md | 7 +++++++ aci-preupgrade-validation-script.py | 6 ++---- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index aafd167..87f8046 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,13 @@ documentation prose, punctuation, capitalization, or other presentation text. For wording-only changes, run the existing relevant tests without creating or modifying test coverage for the wording. +## Manual result messaging + +For a `MANUAL` result, populate `msg` only as a short heads-up when neither +`data` nor `recommended_action` is provided. When a result includes data or +needs explanation or remediation guidance, leave `msg` empty and put the full +explanation and action in `recommended_action`. + ## Documentation links Never put link destinations directly in documentation prose. Use the diff --git a/aci-preupgrade-validation-script.py b/aci-preupgrade-validation-script.py index 37cc63a..4a83a2b 100644 --- a/aci-preupgrade-validation-script.py +++ b/aci-preupgrade-validation-script.py @@ -2352,13 +2352,11 @@ def switch_bootflash_usage_check(sw_cversion, tversion, **kwargs): def missing_images(image_rows): return Result( result=MANUAL, - msg=( - "Bootflash capacity was not evaluated because image size information " - "is unavailable for the listed switch firmware." - ), headers=["Image Role", "Architecture", "Filename", "Status"], data=[row + ["Missing"] for row in image_rows], recommended_action=( + "Bootflash capacity was not evaluated because image size information " + "is unavailable for the listed switch firmware. " "Upload or restore each listed switch image in the APIC Firmware Repository. " "For ACI 6.0(2)+ targets, both 32-bit and 64-bit (-cs_64) switch images " "are required. Wait for repository synchronization, then rerun this check."