nd_maintenance_mode

[allenrobel]

Related Issue(s)

Proposed Changes

Add cisco.nd.nd_maintenance_mode, a new Ansible module that sets the system mode (normal or maintenance) of switches in a fabric via POST /api/v1/manage/fabrics/{fabric_name}/switchActions/changeSystemMode.

The endpoint is action-shaped — one POST mutates a batch of switches with a single mode. The module adapts that to NDStateMachine's CRUD-shaped driver via an identifier_strategy="singleton" model and a config-dict-to-list wrap in main(). Idempotency reads additionalData.intendedSystemMode per switch and only POSTs switches whose intent differs from the request. Any switch currently in migration mode triggers a hard-fail with a remediation message asking the operator to run 'Recalculate and Deploy' in the ND UI before retrying. The 207 response body is inspected per-item; any failed entry surfaces as a RuntimeError naming the offending switches by IP.

State support is merged only for now. The collection-wide query state is retired; gathered will be added once the underlying NDStateMachine/NDOutput framework support lands (the orchestrator's query_all already produces the per-switch snapshot it will need).

Two TODO(4.2.1) workaround markers flag observed ND wire/schema divergences:

• GET /fabrics/{f}/switches/{sid} nests systemMode under additionalData, not at the top level the OpenAPI schema documents.
• The aggregator additionalData.systemMode returns "inconsistent" (a value not in the OpenAPI enum) between an intent change and a deploy, so idempotency must compare against intendedSystemMode, not systemMode.

New / modified files:

• plugins/modules/nd_maintenance_mode.py — module entry point (DOCUMENTATION / EXAMPLES / argspec / main()).
• plugins/module_utils/orchestrators/maintenance_mode.py — MaintenanceModeOrchestrator inheriting NDBaseInterfaceOrchestrator for FabricContext plumbing.
• plugins/module_utils/models/maintenance_mode/{__init__.py, maintenance_mode.py} — singleton model + per-switch get_diff.
• plugins/module_utils/endpoints/v1/manage/manage_fabrics_switch_actions.py — new endpoint module for changeSystemMode.
• plugins/module_utils/endpoints/v1/manage/manage_switches.py — added EpManageSwitchesGet for the per-switch GET used by the query_all fan-out.
• Unit tests: endpoint (8), model (15), orchestrator (20).
• Integration target nd_maintenance_mode with YAML-anchored single-switch, multi-switch, partial-mismatch, negative, and check_mode scenarios.

Test Notes

• Unit tests: source env && python -m pytest tests/unit/module_utils/ — 485/485 pass (442 prior + 43 new, zero regressions). Coverage: orchestrator 93%, model 97%, endpoint 97%.
• Lint: black, isort, pylint, mypy all clean against pyproject.toml. pylint 9.97/10 on tests, 9.75/10 on production. yamllint clean on integration target.
• Integration: Verified live on ND 4.2.1.10 @ 192.168.7.7 / SITE1 against switches S1_BG1 (192.168.12.131) and S1_SP1 (192.168.12.141). All 40 tasks in the target passed (ok=40 changed=13 failed=0 ignored=2, where the two ignored are the expected-failure negative tests). Lab state verified back to intendedSystemMode=normal for all test switches after the run.
• Smoke test: Eight standalone scenarios (baseline, set maintenance, idempotent, restore, idempotent, negative switch_ip, negative fabric, check_mode) all green prior to writing the integration target.
• The radius auth domain on this lab is effectively read-only on SITE1/SITE2; live tests use -e ansible_httpapi_login_domain=local. Documented in the integration target's main.yaml.

Cisco Nexus Dashboard Version

4.2.1

Related ND API Resource Category

• analyze
• infra
• manage
• onemanage
• other

Checklist

• Latest commit is rebased from develop with merge conflicts resolved
• New or updates to documentation has been made accordingly
• Assigned the proper reviewers

---

Note: stacked PR — base is nd_interface_loopback (per .stack.maintenance_mode.json: develop -> nd_interface_loopback -> nd_maintenance_mode).

🤖 Generated with Claude Code