Pair-scoped vPC interface identity: support same vPC id on two pairs

[allenrobel]

Merge Ordering — #422 merged 2026-08-28; rebased and lab-verified

#422 merged into develop on 2026-08-28 and this branch is rebased on it (clean replay, no conflicts). The replaced/overridden re-run it called for is done — see the 2026-08-28 entry under Test Notes. Original reasoning kept for the record:

Prefer merging #422 (replaced/overridden field-removal detection) before this PR. Not a textual concern — the two
branches touch different regions of the vPC model files (identifier block here vs. policy-model defaults tables there)
and auto-merge cleanly. The coupling is semantic:

• Review of Detect field removals in replaced/overridden states (one-way subset diff) #422 surfaced a vPC-specific replaced/overridden idempotency bug in its reverse diff pass: ND echoes the
  orchestrator-injected peerSwitchId inside the policy block, which the proposed config can never express, so the
  reverse pass reports a removal on every run (permanent changed=true + re-PUT). The fix lands in Detect field removals in replaced/overridden states (one-way subset diff) #422 and will touch
  the same vPC model files this PR modifies.
• This PR changes vPC identity and query_all dedup — exactly the machinery that produces the before[] set Detect field removals in replaced/overridden states (one-way subset diff) #422's
  reverse pass classifies against.

After #422 merges: rebase this branch and re-run the vPC replaced/overridden integration scenarios (including
the new multi_pair.yaml) against the live lab before merging, to confirm idempotency holds with the reverse pass
active on the rebased code.

Related Issue(s)

Fixes #356

Added NaC-CapSet1 since Issue #356 also contains this label.

Proposed Changes

• Restore the composite (switch_ip, interface_name) identifier on both vPC interface models
  (accessVpcHost, trunkVpcHost), matching every other interface module. Two vPC pairs in one fabric
  can now legally own the same vPC id (e.g. vpc100 on two pairs) in a single task config — previously
  this collided at parse time ("Item with identifier vpc100 already exists").
• Move the vpc-interface-dual-peer-duplicate workaround from the model identity into
  VpcInterfaceBaseOrchestrator.query_all: dedup is now keyed on interfaceName + the unordered
  {switchId, peerSwitchId} pair set, so one pair's two peer echoes collapse while same-name interfaces
  on different pairs stay distinct (fixes the state: overridden silent-collapse gap).
• Add a preflight() guard that fails fast when one config lists the same interface_name under both
  peers of the same vPC pair (two items targeting one ND resource). Pair resolution only runs for
  duplicated names, so runs with unique names issue zero extra requests.
• Document the pair-scoped identity and the same-pair-duplicate rejection in both modules' notes:.
• Integration: new multi_pair.yaml scenario in both vPC targets (same name + id created on both lab
  pairs in one task, idempotency, fail-fast guard, overridden reconciliation, cleanup), plus a
  backward-compatible nd_test_manage_vpc_pairs gate (default true) so test runs can treat hand-built
  lab vPC pairs as substrate instead of creating/unpairing them. The multi-pair scenario deliberately
  runs after deleted.yaml: its state: overridden step is fabric-wide, so running it earlier would
  delete the vpc201/vpc101 artifacts the deleted-state tests assert against.

Design/spec: docs/superpowers/specs/2026-07-20-vpc-multi-pair-identity-design.md. Lab premise directly
confirmed on ND 4.2.1: the vpcId resource pool is devicePair-scoped, and creating the same-name/same-id
vPC interface intent on two pairs succeeds (findings recorded in the team bug-tracker vault note
vpc-interface-dual-peer-duplicate).

Test Notes

• 2026-08-28 (post-Detect field removals in replaced/overridden states (one-way subset diff) #422 rebase): rebased onto develop @ bb985d74; full unit suite 4146 passed; CI green. Live integration against the rebuilt ND 4.2.1.10 lab (SITE1, pair S1_LE1/S1_LE2, nd_test_manage_vpc_pairs=false): the setup → merged → replaced → overridden → deleted scenarios of both nd_interface_vpc_trunk_host and nd_interface_vpc_access are green (each ok=30 changed=8 failed=0), and every REPLACED IDEMPOTENT / OVERRIDDEN IDEMPOTENT re-apply reports no change — confirming replaced/overridden idempotency holds with Detect field removals in replaced/overridden states (one-way subset diff) #422's reverse pass (peerSwitchId exclusion) active on this branch's pair-scoped identity and dedup. Then, after rebuilding the second lab pair (S1_LE3/S1_LE4, domain 2, physical peer link — the rebuilt lab had left them unpaired), multi_pair.yaml re-run green on both targets (each ok=20 changed=4 failed=0): same-name/same-id create on both pairs, idempotent re-apply, the same-pair fail-fast guard, cross-pair overridden reconciliation plus its idempotent re-apply, and cleanup. Post-run raw-API check: no vPC interfaces left on any of the four leafs, both pairs intact.
• Unit: full suite green via ndpytest tests/unit/ (3184 passed), including new multi-pair dedup,
  missing-peerSwitchId fallback, and preflight-guard tests (TDD; fixtures modeled on captured live wire
  data from both lab pairs).
• Sanity: ndtest — all checks relevant to the changed files pass; 2 pre-existing failures on develop
  (action-plugin-docs, pylint on manage_fabric_base.py) are in files untouched by this branch.
• Live integration (ND 4.2.1, SITE1, two vPC pairs — S1_LE1/S1_LE2 domain 1, S1_LE3/S1_LE4 domain 2, both
  physical peer link): ansible-test network-integration for nd_interface_vpc_trunk_host and
  nd_interface_vpc_access, run with nd_test_manage_vpc_pairs=false. Both targets green end-to-end
  (each ok=49 changed=12 failed=0), including the new multi-pair blocks; post-run raw-API check
  confirmed no leftover vpcId pool entries and both lab pairs intact.
• validate-modules pass for both modules.

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

https://claude.ai/code/session_01BHGFDqqU37PRqNHhKw1FCQ

[Copilot]

Pull request overview

Updates vPC interface handling to support the NX-OS/ND reality that the same vPC ID (e.g. vpc100) can exist on multiple vPC pairs within the same fabric, by restoring composite identity at the model layer and moving “dual-peer echo” handling into orchestrator-side dedup and validation.

Changes:

• Restore composite identifier (switch_ip, interface_name) for accessVpcHost and trunkVpcHost models, aligning with other interface modules.
• Rework VpcInterfaceBaseOrchestrator.query_all() dedup to key on (interfaceName, {switchId, peerSwitchId}) and add a preflight() guard for same-pair duplicates.
• Add/extend unit + integration coverage, plus design/spec documentation for issue #356.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
plugins/module_utils/orchestrators/vpc_interface_base.py	Adds pair-keyed dedup in query_all() and a preflight guard against same-pair duplicate config.
plugins/module_utils/models/interfaces/vpc_access_interface.py	Switches vPC access interface model identity back to composite (switch_ip, interface_name).
plugins/module_utils/models/interfaces/vpc_trunk_host_interface.py	Switches vPC trunk-host interface model identity back to composite (switch_ip, interface_name).
plugins/modules/nd_interface_vpc_access.py	Documents the pair-scoped identity expectations and same-pair duplicate rejection behavior.
plugins/modules/nd_interface_vpc_trunk_host.py	Documents the pair-scoped identity expectations and same-pair duplicate rejection behavior.
tests/unit/module_utils/orchestrators/test_vpc_interface_base.py	Adds unit tests covering multi-pair dedup, missing peerSwitchId fallback, and preflight guard behavior.
tests/unit/module_utils/models/test_vpc_access_interface.py	Updates identifier behavior test for composite identity.
tests/unit/module_utils/models/test_vpc_trunk_host_interface.py	Updates identifier behavior test for composite identity.
tests/unit/module_utils/fixtures/fixture_data/test_vpc_interface_base.json	Updates fixtures with peerSwitchId and adds new multi-pair + preflight fixtures.
tests/integration/targets/nd_interface_vpc_access/vars/main.yaml	Adds second-pair variables and multi-pair scenario inputs; introduces nd_test_manage_vpc_pairs gate.
tests/integration/targets/nd_interface_vpc_access/tasks/setup.yaml	Gates vPC pair creation/teardown steps behind test_manage_vpc_pairs.
tests/integration/targets/nd_interface_vpc_access/tasks/main.yaml	Wires in the new multi-pair integration scenario.
tests/integration/targets/nd_interface_vpc_access/tasks/multi_pair.yaml	New integration scenario validating same-name-on-two-pairs behavior + guard + overridden reconciliation.
tests/integration/targets/nd_interface_vpc_trunk_host/vars/main.yaml	Adds second-pair variables and multi-pair scenario inputs; introduces nd_test_manage_vpc_pairs gate.
tests/integration/targets/nd_interface_vpc_trunk_host/tasks/setup.yaml	Gates vPC pair creation/teardown steps behind test_manage_vpc_pairs.
tests/integration/targets/nd_interface_vpc_trunk_host/tasks/main.yaml	Wires in the new multi-pair integration scenario.
tests/integration/targets/nd_interface_vpc_trunk_host/tasks/multi_pair.yaml	New integration scenario validating same-name-on-two-pairs behavior + guard + overridden reconciliation.
docs/superpowers/specs/2026-07-20-vpc-multi-pair-identity-design.md	Design/spec writeup for the chosen approach and lab findings.
docs/superpowers/plans/2026-07-20-vpc-multi-pair-identity.md	Detailed implementation plan and verification checklist for the change set.

---

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

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated no new comments.

[mikewiebe]

Approved.