Skip to content

vm-repair: add read-only guest MANA driver probe helper - #10587

Open
Edwin Bernal Microsoft (EdwinBernal1) wants to merge 2 commits into
Azure:mainfrom
EdwinBernal1:vmrepair/mana-guest-driver-probe
Open

Edwin Bernal Microsoft (EdwinBernal1) wants to merge 2 commits into
Azure:mainfrom
EdwinBernal1:vmrepair/mana-guest-driver-probe

Conversation

@EdwinBernal1

@EdwinBernal1 Edwin Bernal Microsoft (EdwinBernal1) commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

🤖 PR Validation — ️✔️ All clear

Breaking Changes Suppressions
️✔️ None ️✔️ None

Summary

Add a read-only guest probe that reports whether a VM has a MANA or Mellanox accelerated-networking device and whether its operating system has the MANA network driver. This is groundwork for MANA migration diagnostics and builds on the reset-NIC telemetry schema from #10576 (merged). No command calls it yet; command behavior, parameters, and output are unchanged.

Requested by / source

Type

  • Bug fix / internal (patch)
  • Feature (minor)
  • Breaking (major, sign-off attached)
  • Docs

Changes

  • src/vm-repair/azext_vm_repair/scripts/linux-mana-driver-probe.sh (new, POSIX sh): PCI vendor/device 1414:00ba is MANA, vendor 15b3 is Mellanox; the driver is present when mana is loaded, built in, or present as a module file for the running kernel.
  • src/vm-repair/azext_vm_repair/scripts/win-mana-driver-probe.ps1 (new, Windows PowerShell 5.1): present PCI device VEN_1414&DEV_00BA is MANA, VEN_15B3 is Mellanox; on MANA hardware the driver is present when a Microsoft Azure Network Adapter network adapter exists, otherwise missing. Off MANA hardware the driver is unknown.
  • src/vm-repair/azext_vm_repair/repair_utils.py: _parse_mana_probe_output() strictly parses exactly one marker line; _check_guest_mana_driver() runs the OS-appropriate probe through the existing _invoke_run_command and returns {hardware, driver, source}.
  • src/vm-repair/setup.py: package both probe scripts; version 2.5.1.
  • src/vm-repair/HISTORY.rst, src/vm-repair/README.md: changelog entry and internal-probe documentation.
  • src/vm-repair/azext_vm_repair/tests/latest/test_mana_guest_probe.py (new): regression coverage.

Detection logic follows the Microsoft Learn MANA guidance for Windows and Linux.

Design notes

  • unknown is never reported as missing. Any Run Command failure, unready VM agent, validation rejection, malformed response, or unrecognized output returns unknown. The helper never raises.
  • Deviation from the work item: it specifies {present: bool, versionOrDriver, source}. A Boolean cannot represent "not determined," so the helper returns string enums instead, consistent with the unknown convention established in vm-repair: prepare MANA reset-NIC telemetry schema #10576.
  • Not wired into reset-nic, deliberately. Run Command needs a ready VM agent and outbound guest connectivity to return results, cannot be canceled, and can run for up to 90 minutes (Run Command restrictions). reset-nic targets VMs whose guest networking is broken, so a blocking preflight would be least reliable when it matters most. How, and whether, to call it is a separate decision.
  • Security: the probes are fixed, parameterless, read-only scripts packaged with the extension; no user or resource value is interpolated into them. They print one fixed-format line containing only enumerated values, with no guest identifiers.

Version & changelog

Testing

  • Rebased onto main after vm-repair: prepare MANA reset-NIC telemetry schema #10576 merged; the PR now contains a single commit.
  • New regression tests fail before the implementation (35 failures) and pass after it: 10 tests, 57 subtests. They cover parsing of every value, rejection of malformed or duplicated output, OS-specific script selection with no parameters, every failure type mapping to unknown, packaging, and static read-only/no-input checks on both scripts.
  • Real script execution, no Azure resources:
    • Windows probe under Windows PowerShell 5.1 (the Run Command host): exits 0 and emits a valid marker.
    • Linux probe syntax-checked and run under dash and bash (WSL Ubuntu); its driver=missing result on that kernel was independently confirmed.
    • Linux probe run unmodified against simulated sysfs and module trees in isolated mount namespaces, 8/8 cases passing: MANA with built-in driver, MANA with a compressed module, MANA without a driver, MANA with only mana_ib, Mellanox with and without the MANA module, no virtual function, and a non-MANA Microsoft PCI device.
  • On Azure CLI 2.90.0, after the rebase: azdev style PASS; azdev linter PASS; azdev test vm-repair 304 passed, 37 skipped, in local/recorded mode with no live mode. At medium severity, the linter reports only the pre-existing --preview placeholder-URL finding, untouched here.
  • azdev secret scan: no secrets in any of the 7 changed files. The repository's pre-commit and pre-push hooks exited early locally (no Python environment found), so their checks were run manually as listed above.
  • Not performed: execution on real MANA or Mellanox Azure VMs.

Cross-repo impact (repair-script-library)

  • None. These probes ship inside the extension and are not catalog run IDs.

Backward compatibility

  • No public command, parameter, default, output, or telemetry change. The helper is not invoked by any command.

Follow-up (outside this PR)

  • Decide how the probe may be used, given the Run Command constraints above: for example, an advisory step outside reset-nic's critical path, or after connectivity is restored, rather than a blocking preflight.
  • Validate on real MANA and Mellanox VMs before any command depends on the result.
  • Map probe results onto the sourceVfVendor and guestManaPresent telemetry fields once a command calls it.

@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

@microsoft-github-policy-service microsoft-github-policy-service Bot added the Auto-Assign Auto assign by bot label Nov 12, 2026
@a0x1ab

Copy link
Copy Markdown
Member

/azp run

@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 2 pipeline(s).

Ship packaged, parameterless Linux and Windows probe scripts and an internal _check_guest_mana_driver helper that runs the OS-appropriate probe through Run Command. It reports the accelerated-networking device (mana, mellanox, none, unknown) and MANA driver availability (present, missing, unknown). Any run or parse failure returns unknown, never missing. No command calls the helper yet. Bump version to 2.5.1.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@EdwinBernal1
Edwin Bernal Microsoft (EdwinBernal1) marked this pull request as ready for review November 17, 2026 17:52
Copilot AI balanced review requested due to automatic review settings November 17, 2026 17:52

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unhandled launcher and response-shape errors violate the helper’s unknown-on-failure contract, while probe read and search failures can incorrectly report hardware or drivers as absent.

3 open issues
What changed in this PR

Adds an internal, read-only MANA guest probe to vm-repair, building on the reset-NIC telemetry groundwork. No command invokes the helper yet, so public command behavior remains unchanged.

Changes:

  • Adds Linux and Windows scripts to detect MANA/Mellanox hardware and report MANA driver status.
  • Adds marker parsing, an OS-specific Run Command helper, and regression coverage.
  • Packages both scripts, documents their limitations, and bumps the extension to 2.5.1.
File Description
src/​vm-repair/​setup.py Packages both probes and updates the version.
src/​vm-repair/​README.md Documents probe results, constraints, and command isolation.
src/​vm-repair/​HISTORY.rst Adds the 2.5.1 release entry.
src/​vm-repair/​azext_vm_repair/​tests/​latest/​test_mana_guest_probe.py Tests parsing, helper behavior, packaging, and script restrictions.
src/​vm-repair/​azext_vm_repair/​scripts/​win-mana-driver-probe.ps1 Adds Windows PCI and network-adapter detection.
src/​vm-repair/​azext_vm_repair/​scripts/​linux-mana-driver-probe.sh Adds Linux PCI and kernel-module detection.
src/​vm-repair/​azext_vm_repair/​repair_utils.py Adds the marker parser and guest-probe helper.

Review effort: Balanced

Address review feedback. The helper now also maps launcher failures (OSError) and unexpected run-command response shapes (AttributeError, non-string output) to unknown instead of raising. The Linux probe reports hardware=none only after reading every PCI entry, and driver=missing only when both the built-in list and the module tree were read without error; otherwise it reports unknown.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@a0x1ab

Copy link
Copy Markdown
Member

/azp run

@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 2 pipeline(s).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Auto-Assign Auto assign by bot

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants