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 (from one bulk GET /fabrics/{f}/switches) 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; entries whose status is failed, failure, or error (case-insensitive) surface as a RuntimeError naming the offending switches by IP. Other tokens (success, missing, empty, pending, warning) are tolerated.

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()). DOCUMENTATION includes a notes paragraph and a play-level module_defaults example covering the ansible_command_timeout / persistent_command_timeout interaction with blocking deploys.
• plugins/module_utils/orchestrators/maintenance_mode.py — MaintenanceModeOrchestrator inheriting NDBaseInterfaceOrchestrator for FabricContext plumbing. query_all() issues one bulk EpManageSwitchesListGet and caches both the IP→intendedSystemMode map and the IP→switchId map on the instance; update() reuses both, so each module run does one fabric-summary GET, one switches GET, and (when changes are needed) one POST.
• 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. Path is URL-encoded; query string omits deploy and blocking when the user did not opt into them.
• plugins/module_utils/endpoints/v1/manage/manage_switches.py — added EpManageSwitchesGet (generic per-switch GET, retained as collection infrastructure though nd_maintenance_mode itself reads via the bulk EpManageSwitchesListGet). URL encoding on both new paths hardened to match the existing EpManageSwitchActionsDeploy convention.
• Unit tests: endpoint (9), model (15), orchestrator (29 collected). Total suite: 554/554 pass.
• 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/ — 554/554 pass, 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.78/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). Full target green; lab state verified back to intendedSystemMode=normal for all test switches after the run. Re-verified green after the follow-up commits below.
• 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.

Refinements since PR opened

Six follow-up commits land behavior/perf refinements on top of the initial implementation:

1. e65143d — Cache the query_all() snapshot on the orchestrator and skip the redundant re-query in update(). Avoids a second per-run snapshot pass when NDStateMachine already populated one during init.
2. d9d09fa — Replace the per-switch GET fan-out in query_all() with one bulk EpManageSwitchesListGet call (verified on ND 4.2.1 lab: the list response carries additionalData.intendedSystemMode and discoveredSystemMode per row). Per-run controller round-trips drop from 2 + N to 2 + 1; on a 32-switch fabric that is 64 GETs eliminated per task.
3. 3dde916 — URL-encode fabric_name (and switch_id) in EpManageSwitchesGet.path and EpManageFabricsSwitchActionsChangeSystemModePost.path. Matches the existing quote(safe="") convention used by sibling endpoints; protects against future fabric names containing reserved URL characters.
4. 8374b4b — Only push truthy deploy / blocking onto the endpoint's query params. Previously the bool defaults (False) were assigned unconditionally and serialized as ?deploy=false&blocking=false on every request. Functionally harmless on ND today but inconsistent with the endpoint's own to_query_string design.
5. f77bd42 — 207 parser uses an explicit failure denylist (failed / failure / error, case-insensitive) rather than treating anything not success as a failure. ND's switchAction APIs occasionally return rows with missing status or progress tokens like pending/warning; the old code would surface those as spurious task failures.
6. 0efba32 — Document the blocking=true deploy interaction with persistent_command_timeout. New notes paragraph and a play-level module_defaults example showing the recommended timeout: 1800 + inventory ansible_command_timeout pattern.

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

---

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds cisco.nd.nd_maintenance_mode, a new Ansible module for setting switch system mode to normal or maintenance through the Nexus Dashboard manage API.

Changes:

• Adds the maintenance mode module, singleton model, orchestrator, and new endpoint definitions.
• Adds per-switch query/idempotency handling and 207 per-item failure parsing.
• Adds unit and integration tests for endpoint/model/orchestrator behavior and merged-state scenarios.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
plugins/modules/nd_maintenance_mode.py	Adds the module entry point, documentation, examples, argspec wiring, and state-machine integration.
plugins/module_utils/orchestrators/maintenance_mode.py	Adds orchestration for querying switch modes and posting changeSystemMode actions.
plugins/module_utils/models/maintenance_mode/maintenance_mode.py	Adds singleton maintenance mode models and argument spec.
plugins/module_utils/models/maintenance_mode/__init__.py	Adds package initialization for maintenance mode models.
plugins/module_utils/endpoints/v1/manage/manage_fabrics_switch_actions.py	Adds the changeSystemMode switch action endpoint model and query params.
plugins/module_utils/endpoints/v1/manage/manage_switches.py	Adds a per-switch GET endpoint used for maintenance mode snapshots.
tests/unit/module_utils/endpoints/test_endpoints_api_v1_manage_fabrics_switch_actions.py	Adds unit tests for the new switch action endpoint.
tests/unit/module_utils/models/test_maintenance_mode_model.py	Adds model/unit tests for singleton behavior, payloads, diffing, and argspec shape.
tests/unit/module_utils/orchestrators/test_maintenance_mode.py	Adds orchestrator unit tests for query, update, failure handling, and delegation paths.
tests/unit/module_utils/fixtures/fixture_data/test_maintenance_mode.json	Adds fixtures for maintenance mode orchestrator tests.
tests/integration/targets/nd_maintenance_mode/vars/main.yaml	Adds integration test variables for fabric and switch IPs.
tests/integration/targets/nd_maintenance_mode/tasks/main.yaml	Adds integration test entry point and setup/teardown orchestration.
tests/integration/targets/nd_maintenance_mode/tasks/setup.yaml	Adds setup task to normalize switch mode before tests.
tests/integration/targets/nd_maintenance_mode/tasks/merged.yaml	Adds merged-state integration scenarios, idempotency checks, negatives, and check mode tests.
tests/integration/targets/nd_maintenance_mode/tasks/teardown.yaml	Adds teardown task to restore test switches to normal intent.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.