nd_interface_loopback: policy_type discriminated union

[allenrobel]

Formerly stacked on #387 (nd_argument_specs_relocate). #387 has merged, this PR is retargeted to develop and rebased on it, and remote CI now runs (and passes) on this branch.

⚠️ Merge Ordering — hold until #422 merges

Do not merge this PR before #422 (replaced/overridden field-removal detection). Reasoning:

• Detect field removals in replaced/overridden states (one-way subset diff) #422 adds a reverse diff pass to NDBaseModel.get_diff plus per-model reverse_diff_defaults tables (ND echoes template defaults for unset fields, so the reverse pass must strip them or replaced/overridden idempotency breaks). Its entire footprint in the loopback model is one flat table: {"adminState": True, "routeMapTag": "12345"}.
• This PR restructures that same model into nine per-policy_type policy models (3 NX-OS + 6 IOS-XE), which relocates routeMapTag three levels deep into NexusLoopbackPolicyModel and means each policy model needs its own reverse_diff_defaults table sourced from its own OpenAPI template schema. That per-policy-type work belongs here — this PR introduces the new policy types — and the _strip_reverse_diff_defaults recursion in Detect field removals in replaced/overridden states (one-way subset diff) #422 already supports nested per-model tables.
• If this PR merged first, Detect field removals in replaced/overridden states (one-way subset diff) #422 (a collection-wide correctness fix touching all nine interface modules plus prefix-list) would have to grow nine loopback tables — including IOS-XE templates — before it could land. Merging Detect field removals in replaced/overridden states (one-way subset diff) #422 first keeps its loopback table scoped to the single loopback policy type that exists on develop today, and confines the semantic overlap to a well-defined rebase task on this branch.

Rebase checklist for this branch after #422 lands:

• Move the "routeMapTag": "12345" entry into NexusLoopbackPolicyModel.reverse_diff_defaults; keep adminState at the level where it lives post-restructure.
• Add reverse_diff_defaults tables for the eight new policy models (ipfmLoopback, mplsLoopback, and the six IOS-XE templates), each sourced from its policyType's OpenAPI template schema; lab-verify echoes where possible. Any policy model without a table silently loses replaced/overridden removal detection.
• Verify the read-tolerant policy models do not retain unknown server-injected keys — any retained extra key would be counted as a removal by the reverse pass and break replaced/overridden idempotency (the 2026-07-18 XE probe found no ND-injected keys in XE policy reads, but re-check on the rebased code).

Related Issue(s)

Relates to #401 (develop ip=IPv4CIDR handling). The bare-IPv4 normalization on this branch overlaps with open PR #402 — whichever lands second will rebase and drop the duplicate change. No issue is closed by this PR.

The design/plan docs that accompanied the POC phase have been removed from the branch and archived outside the repo.

Proposed Changes

Consolidates the loopback interface behind discriminated unions so a single module handles every ND loopback policy template, across both switch OSes.

policy_type discriminated union (NX-OS):

• Add LoopbackPolicyTypeEnum and a LoopbackPolicyBase; make policy_type required and strict on the write path.
• Add IpfmLoopbackPolicyModel, MplsLoopbackPolicyModel, and SecondaryIpModel; wire the discriminated union on policy_type.
• Extend the loopback argspec with policy_type and the per-template union fields.
• query_all manages loopback, ipfmLoopback, and mplsLoopback via a set filter.
• Read path tolerates ND-injected policy keys (extra="forbid" was aborting reads); the write path stays strict.
• Normalize loopback ip to bare IPv4 (ND 4.2.1 rejects CIDR on the wire).
• Docs for policy_type and the per-template fields.

Required network_os_type discriminator:

• Per discussion with Mike and Matt, the platform/OS selector is a mandatory, user-supplied parameter — network_os_type (mirrors the ND API's required networkOSType discriminator) — so all interface parameters validate before any controller call. A future enhancement makes it optional with a per-switch FabricContext.get_platform_type() fallback (FabricContext: expose platform_type, retain switch records, fail closed (#399, #400) #404).

IOS-XE loopback surface (choices: [nx-os, ios-xe]):

• config_data.network_os is an outer discriminated union (NexusLoopbackNetworkOSModel | XeLoopbackNetworkOSModel), each OS branch carrying its own policy_type union: NX-OS keeps loopback/ipfmLoopback/mplsLoopback; IOS-XE adds iosXeLoopback, iosXeLoopbackShutNoshut, iosXeUnderlayLoopback, iosXeInternalLoopback, csrLoopback, csr1kvLoopback (all six real XE templates; userDefined stays excluded on both OSes). Cross-OS mismatches (nx-os + iosXeLoopback) fail structurally in Pydantic — no hand-written cross-check.
• LoopbackPolicyStrictBase split: extra="forbid" + read-tolerant validator + admin_state shared by all nine branches; NX common fields stay on LoopbackPolicyBase.
• Six IOS-XE branch models with exact per-template fields (schema-verified); new flat options secondary_ip, enable_pim.
• query_all filter is the union of the NX and XE policy-type enums (XeLoopbackPolicyTypeEnum).
• Lab probe (2026-07-18, IOS-XE device in fabric ISN) proved the OpenAPI READ schema's csrIntLoopback never appears on the wire — ND echoes the create-side csrLoopback — so the model uses the single wire-verified name (drift recorded in the team bug-tracker vault: csr-loopback-read-schema-name-drift); the same probe found no ND-injected keys in XE policy reads.
• DOCUMENTATION/EXAMPLES cover all four states for ios-xe plus a csrLoopback example.
• XE integration tasks gated on nd_test_xe_switch_ip (skipped unless supplied), including a fabric-equality-guarded mixed NX+XE overridden variant.

Lab-surfaced bug fixes:

• create_bulk now groups one POST per (switch, policyType) — ND rejects mixed-policyType bulk creates (207 with a failed item, nothing created) — and both create paths validate 207 results[] per item instead of trusting the HTTP code (stopgap until Detect Multi-status per-item failures in NdV1Strategy (#295) #398's NdV1Strategy 207 support; both carry TODO(4.2.1) markers referencing vault notes: bulk-interface-create-rejects-mixed-policy-types and multi-status-207-status-field-inconsistent).
• Integration loopback IDs renumbered 1xx→2xx: the lab's new multisite topology auto-provisions loopback100 (ND's default multisite loopback ID) on border gateways, colliding with the old reserved range.

Test Notes

• Integration: nd_interface_loopback integration tests are green against these changes (merged/replaced/overridden/query, including the added policy_type: loopback tasks).
• Unit: all unit tests green — models (test_loopback_interface.py), orchestrator, and nd_argument_specs suites.
• 2026-07-16 (network_os_type commits): integration tests re-run green against a live ND 4.2.1 lab with the now-required network_os_type: nx-os in every network_os block; full unit suite (3195 tests) green; validate-modules sanity clean on nd_interface_loopback.py.
• 2026-07-18 (IOS-XE commits): full unit suite (3208 tests) green; validate-modules clean; black/isort/pylint/mypy clean on changed files; ansible-lint clean on the integration target. Live-lab raw-REST probe verified XE create/read/delete behavior on a real IOS-XE device (intent-only). XE integration run against the live lab: all tests pass (all four states + idempotency on the IOS-XE device, iosXeLoopback and csrLoopback), which also verifies the csr single-name decision on the full deploy path — the deployed read echoes csrLoopback, not the read-schema's csrIntLoopback. The first run surfaced two real module bugs (mixed-policyType bulk-create rejection masked by unchecked 207s) — fixed with TDD unit coverage, then the re-run went green. (No CI on stacked PRs — local verification per team convention.)

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

[Copilot]

Pull request overview

This PR expands nd_interface_loopback from a single NX-OS loopback template into a discriminated-union driven implementation that supports multiple NX-OS loopback policy templates and a full IOS-XE loopback surface, while hardening create/bulk-create behavior against ND’s per-item 207 Multi-Status failure reporting and policyType-mixing limitations.

Changes:

• Introduces required discriminators network_os_type (outer union) and policy_type (policy union) and adds per-template models/argspec/docs to support NX-OS + IOS-XE loopback templates in one module.
• Normalizes loopback IPv4 ip input to a bare host address for ND 4.2.1 wire compatibility (accepts CIDR input, sends bare IPv4).
• Updates the orchestrator to (a) validate per-item DATA.results[] statuses for create/create_bulk and (b) group bulk creates by (switch_id, policy_type).

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/module_utils/orchestrators/test_loopback_interface.py	Updates orchestrator unit tests for new model types, adds coverage for per-item 207 failures and bulk-create grouping by policy type, and expands query_all filtering expectations.
tests/unit/module_utils/models/test_loopback_interface.py	Adds extensive unit coverage for the new discriminated unions (NX + XE) and for IPv4 host normalization + strict/read-tolerant policy validation.
tests/unit/module_utils/fixtures/fixture_data/test_loopback_interface.json	Extends fixtures to cover new query_all filtering cases and the new 207-results failure shapes used in create/create_bulk tests.
tests/integration/targets/nd_interface_loopback/vars/main.yaml	Updates reserved loopback ID ranges, makes network_os_type/policy_type explicit, and adds IOS-XE test variables gated by nd_test_xe_switch_ip.
tests/integration/targets/nd_interface_loopback/tasks/main.yaml	Conditionally includes IOS-XE integration tasks when nd_test_xe_switch_ip is provided.
tests/integration/targets/nd_interface_loopback/tasks/setup.yaml	Renumbers reserved loopback IDs used for integration setup cleanup.
tests/integration/targets/nd_interface_loopback/tasks/merged.yaml	Updates merged-state integration coverage to include required discriminators and new ID ranges.
tests/integration/targets/nd_interface_loopback/tasks/replaced.yaml	Updates replaced-state tasks for required discriminators and renumbered IDs.
tests/integration/targets/nd_interface_loopback/tasks/overridden.yaml	Updates overridden-state tasks for required discriminators, renumbered IDs, and system-loopback filtering assumptions.
tests/integration/targets/nd_interface_loopback/tasks/deleted.yaml	Updates deleted-state tasks for renumbered IDs and the revised vars structure.
tests/integration/targets/nd_interface_loopback/tasks/xe.yaml	Adds IOS-XE integration coverage across all states plus idempotency, including mixed NX+XE overridden coverage when fabrics match.
plugins/modules/nd_interface_loopback.py	Updates module docs/examples to expose and describe the new discriminators and per-template policy fields across NX-OS and IOS-XE.
plugins/module_utils/orchestrators/loopback_interface.py	Hardens create/create_bulk against per-item failures and changes bulk-create grouping to (switch_id, policy_type); expands query_all filtering to NX + XE managed policy types.
plugins/module_utils/models/types.py	Adds IPv4Host type to normalize IPv4 to bare host form while accepting CIDR input.
plugins/module_utils/models/interfaces/loopback_interface.py	Reworks loopback models into nested discriminated unions (network OS + policy type), adds strict/read-tolerant behavior for policy objects, and exposes required discriminators via argspec.
plugins/module_utils/models/interfaces/enums.py	Adds managed loopback policy-type enums for NX-OS and IOS-XE used by orchestrator filtering and documentation.

---

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