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; TODO(4.2.1) marker referencing vault note bulk-interface-create-rejects-mixed-policy-types). Per-item 207 results[] failures on both create paths are detected centrally by NdV1Strategy.is_success (Detect Multi-status per-item failures in NdV1Strategy (#295) #398, merged 2026-08-11) — the orchestrator-level stopgap this branch originally carried was removed in commit "Drop the orchestrator-level 207 results[] stopgap superseded by Detect Multi-status per-item failures in NdV1Strategy (#295) #398" once Detect Multi-status per-item failures in NdV1Strategy (#295) #398 landed on develop.
• 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.

[mikewiebe]

I’m holding approval on this PR for three reasons:

1. The 207-response handling regressed. The previous loopback-specific check accepted only an explicit status: success. The shared handler now treats missing, warning, notexecuted, and unknown statuses as successful. This can make the module report success and queue deployment for an interface that ND did not accept. Issue #397 explicitly says these allowlist checks must remain until the shared handler supports equivalent behavior.

   Please restore the loopback-specific check or add shared exact-success handling, with tests for missing and non-success status values.

2. overridden can target fabric-created MPLS loopbacks for deletion. The module includes mplsLoopback in its owned-resource set. Consequently, an MPLS loopback returned by ND but omitted from the desired overridden configuration is queued for removal and deployment.

   MPLS loopbacks are fabric-created and historically update-only. They are also absent from the reviewed OpenAPI create discriminator. Please treat them as update-only: allow updates to known MPLS loopbacks, reject explicit creation/deletion, and exclude them from overridden deletion scope. Add a regression test proving an omitted MPLS loopback is preserved. Issue #452 is related, but does not currently define this ownership protection.

3. The declared Detect field removals in replaced/overridden states (one-way subset diff) #422 dependency is incomplete. The PR says it must wait for PR #422, which is still open. Combining the current branch heads also produces a conflict in loopback_interface.py.

   Please merge Detect field removals in replaced/overridden states (one-way subset diff) #422, rebase this PR, resolve the conflict, rerun the tests, and request another review.

Once these items are addressed, I can re-review promptly. The other tracked follow-up work and low-severity RETURN documentation issue are not blocking approval.