[Staged configuration audit] vPC Access interface module

[sivakasi-cisco]

Parent Scope

Sub-issue of #453: staged configuration addition and removal audit.

This issue must evaluate both staged additions and staged removals for replaced, overridden, and deleted wherever those states are supported. An unsupported state must be recorded as Not Applicable with a technical reason; it must not be silently skipped.

Applicability Assessment - Required First

Before implementation, first evaluate whether staged configuration addition and removal are technically applicable to this module and its Nexus Dashboard endpoints.

• Identify whether the operation produces deployable switch intent, controller-only inventory or topology state, or an automatically deployed action.
• Identify whether ND provides a separate save or recalculation boundary and a separate deploy boundary.
• Record the applicability result as Applicable, Partially Applicable, or Not Applicable, with technical evidence.
• If staging is not applicable, document the endpoint limitation and obtain agreement in parent issue Support staged removal for all modules  #453; do not force unsupported behavior into the module.

Module Scope

• nd_interface_vpc_access

Module-Specific Problem Statement

vPC Access interface intent affects paired switch ports and access policy. Determine whether changes and removals can be staged consistently across both peers without deployment.

The audit must establish the current behavior for additions, updates, removals, detachments, and deletions that this module supports. Pass or fail must be based on observed controller state, switch synchronization state, and API evidence rather than only the Ansible input flags.

Required State Validation

State	Required validation for this module
replaced	Validate staged additions and updates, plus any setting removal or reset caused by replacement.
overridden	Validate staged additions and removal or detachment of existing resources omitted from the desired configuration.
deleted	Validate whether the module deletes or detaches the selected resource, creates pending intent, performs dependency cleanup, or deploys automatically.

For a state the module does not support, record Not Applicable, the technical reason, and any endpoint or architecture limitation.

Save and Deploy Validation

• If save is supported, test save=false and deploy=false: no save or deploy action should run, and associated switches should remain inSync. Record whether controller data still changes.
• If save is supported, test save=true and deploy=false: intent should be saved without deployment, the first expected switch state is pending, and no deploy endpoint should run.
• Preserve and validate the existing save=true and deploy=true behavior.
• If save is not supported, verify whether controller intent can be added or removed while deployment remains disabled.
• Test a later explicit deployment when staging succeeds.

Module-Specific Scenarios

• Stage creation and replacement and confirm both vPC peers are targeted.
• Remove policy or interface intent through overridden and deleted.
• Confirm no automatic deployment or asymmetric peer state.
• Verify later explicit deployment and idempotency on both peers.

Evidence to Record

• Branch, commit, or PR tested.
• ND version, topology, and resource associations used.
• Results for replaced, overridden, and deleted, where supported.
• Explicit save and deploy values, where supported.
• Controller state before and after each operation.
• Immediate switch state: inSync, pending, or outOfSync.
• Switch state after a compliance or configuration-difference evaluation.
• API trace showing whether save, deploy, detach, undeploy, or delete endpoints ran.
• Result of a later explicit deployment.
• Idempotency result from repeating the staged operation.
• Classification: Supported, Partially Supported, Unsupported, or Not Applicable.
• Required rework, effort estimate, dependencies, and initial-release impact.

Completion Criteria

• Applicability is explicitly decided before implementation.
• Both staged addition and staged removal are tested.
• replaced, overridden, and deleted are tested where supported, with technical reasons for every exception.
• No deployment occurs while deployment is disabled.
• Current behavior is demonstrated with controller, switch-state, and API evidence.
• A later explicit deployment and an idempotent rerun are tested where staging succeeds.
• Required rework and release impact are recorded in parent issue Support staged removal for all modules  #453.

References

• Parent staged-configuration issue: Support staged removal for all modules  #453

[allenrobel]

Applicability assessment (required-first step) — code audit

Per the issue template, applicability must be decided before implementation. Below is the code-side assessment for
nd_interface_vpc_access; the lab evidence matrix (controller state, switch sync states, API traces, later deploy, idempotent rerun) is the
follow-on step and will be posted as a separate comment. Code audited on branch nd_replaced_overridden_field_removals
(PR #422, HEAD 145455c); the staging/deploy architecture described is unchanged from develop.

1. What kind of operation this module performs

Writes are POST/PUT/DELETE against /api/v1/manage/fabrics/{fabric}/interfaces — these record deployable switch intent
on the controller and do not themselves push configuration. Deployment is a separate, explicit bulk
interfaceActions/deploy call whose payload lists exactly the {interfaceName, switchId} pairs the task mutated, so deploy
scope is bounded to resources the task owns per its input.

2. Save and deploy boundaries

ND's interface API has no save/recalculation boundary: the intent write itself creates pending configuration. (The
config_save/config_deploy pair in ConfigActionsMixin belongs to fabric-level modules; nothing analogous exists for
interface intent.) The deploy boundary is interfaceActions/deploy. Accordingly:

• save → Not Applicable for this module. The template's save=false/true matrix rows collapse to the deploy-only cases.
• deploy → applicable and already implemented, as config_actions.deploy.

3. Deploy control as implemented today

• Parameter shape: config_actions.deploy (bool, default true). config_actions: {deploy: false} parses and is honored.
• Execution order per run: state processing (intent mutations) → remove_pending() (delete-side flush; not gated by the
  deploy flag) → deploy_pending() (returns without any API call when deploy is disabled or nothing is queued). Both flushes
  are skipped entirely in check mode.
• merged/replaced/overridden additions and updates are plain intent writes and stage cleanly with deploy disabled.

4. Removal/deletion semantics

vPC interfaces cannot use the bulk remove endpoint. Known ND 4.2.1 deviation (workaround marker TODO(4.2.1) vpc-interface-bulk-delete-silent-fail, lab-verified): bulk interfaceActions/remove returns {"status":"Failed","message":"Invalid Interface"} inside an HTTP 207 for vPC interfaces. The module therefore deletes via the per-interface DELETE /interfaces/{name} (HTTP 204), executed immediately during state processing, then queues a deploy that is gated by the deploy flag. Consequences for this audit:

• With deploy disabled, controller intent deletion happens immediately (it is not queued), and the push to both peers — including member-interface reversion to fabric defaults — is deferred. Staged removal therefore means "intent already gone controller-side, switches untouched until deploy"; the lab pass must record the per-peer sync states while in that window.
• There is no mode in which state: deleted leaves controller intent untouched — the intent operation is the staging mechanism. The checklist item "record whether controller data still changes" will be answered yes, by design for every state.

5. Module-specific notes

• Peer symmetry: a vPC interface is a single controller object spanning both peers, and both the intent writes and the deploy target that one object, so module-side asymmetry is not expected. Switch-side symmetry while intent is staged-but-undeployed is a lab observation to record on both peers.

6. Expected gap: no later-deploy path for staged intent

The template requires testing "a later explicit deployment when staging succeeds." Code inspection says this will fail as
the collection stands: deploys are queued only by create/update/delete mutations, so a follow-up run with deploy enabled and
an unchanged config computes an empty diff, queues nothing, and pushes nothing. No deploy-only module exists in the
collection (the module docs' suggestion to "use a separate deploy module" points at a module we have not built). Staged
intent is currently pushed only by (a) a subsequent run that happens to re-mutate the same interfaces, or (b) out-of-band
deploy (GUI/API). I will confirm this in the lab pass and propose the disposition in #453 — likely a deploy-only companion
module or an explicit deploy-pending mode.

7. Proposed classification (pending lab evidence)

Aspect	Proposed result
Staged additions/updates (merged/replaced/overridden)	Applicable — intent writes stage; deploy deferred by the flag
Staged removals (overridden/deleted)	Applicable, with caveat — per-interface DELETE removes intent immediately; only the peer push is deferred
save boundary	Not Applicable — no save/recalc step exists for interface intent
Later explicit deployment of staged intent	Gap expected — no in-collection deploy-only path (see §6)

If the lab evidence contradicts any of the code-derived expectations above, the classification will be revised in this issue
before being rolled up to #453.

[allenrobel]

Lab evidence — staged-configuration matrix (follow-up to the applicability assessment)

Environment: ND 4.2.1, fabric SITE1 (greenfield rebuild, 2026-08-07), switch S1_LE1 (9R0TGMEVTM0) + S1_LE2 (vPC pair); branch nd_replaced_overridden_field_removals @ 5a2dd95 (PR #422). Module inputs mirror the integration-target baseline; deploy control via config_actions.deploy. Controller state, per-switch pendingConfig, and configSyncStatus captured after every step; deploys only ever issued via explicit out-of-band interfaceActions/deploy calls, so any pending-line growth with deploy disabled is staged intent by construction.

Step results

Step	changed	switch sync	pending lines (switch total)	What it shows
merged_stage	True	outOfSync	17	staged create (merged, deploy disabled)
merged_idem	False	outOfSync	17	idempotency rerun of the staged create
replaced_stage	True	outOfSync	17	staged update (replaced, deploy disabled; description marker changed)
replaced_idem	False	outOfSync	17	idempotency rerun of the staged update
deploy_true_noop	False	outOfSync	17	deploy-enabled rerun with UNCHANGED config (later-deploy test); pending 17→17 (nothing pushed)
oob_flush	—	inSync	0	out-of-band interfaceActions/deploy for the staged interface (HTTP 207)
deleted_stage	True	pending	12	staged removal (deleted, deploy disabled)
final_flush	—	inSync	0	out-of-band interfaceActions/deploy to apply the staged removal (HTTP 207)

Checklist outcomes

• save: Not Applicable — confirmed no save boundary exists for interface intent; the intent write itself creates the staged state.
• deploy=false staging: confirmed — controller intent changes, switch transitions inSync → outOfSync/pending, staged CLI appears in pendingConfig, and no deploy endpoint runs (pending persists across module runs until the explicit flush).
• deploy=true preserved behavior: confirmed for mutations (deploys are queued and flushed by the module when the flag is enabled and a mutation occurs).
• Later explicit deployment (the §6 gap): confirmed as a gap — a deploy-enabled rerun with unchanged config computed an empty diff and pushed nothing (pending count unchanged). Staged intent was only applied via the out-of-band interfaceActions/deploy call. Disposition proposed in Support staged removal for all modules  #453.
• Idempotency: staged merged rerun and staged replaced rerun both reported changed=false.
• API evidence: create/update are intent POST/PUTs; removal path per family (see below); interfaceActions/deploy appears only in the explicit flush steps (HTTP 207 per-item success bodies captured in the evidence JSON).

Module-specific findings

• Same two-phase deleted behavior as the vPC trunk-host representative ([Staged configuration audit] vPC Trunk Host interface module #474): intent DELETE immediate, switch sync pending with staged removal CLI (~12 lines), explicit deploy applied it and returned inSync.
• Both peers were targeted through the single vPC object; no asymmetric state observed.

Classification

Aspect	Result
Staged additions/updates (merged/replaced/overridden)	Supported
Staged removals (overridden/deleted)	Supported, with caveat — controller intent deletion is immediate (per-interface DELETE); the switch-side removal stages until an explicit deploy
save boundary	Not Applicable — no save/recalc step exists for interface intent
Later explicit deployment of staged intent	Gap — no in-collection deploy-only path (lab-confirmed); needs disposition in #453

Raw step-by-step evidence (full captures, per-item API responses) is archived and available on request. Rolled up to #453 together with the other nine module audits.

[allenrobel]

Template-format summary per the audit request. Full detail is in the two comments above (applicability assessment, 2026-08-07; lab evidence matrix, 2026-08-08).

Result: Already Supported (with one delete-path caveat, below)

States tested: merged, replaced, overridden, deleted — each with config_actions.deploy: false, on SITE1 (ND 4.2.1.10), PR #422 branch; both vPC peers targeted through the single vPC object.

Current behaviour:

• Controller intent changes in every state by design — the intent write is the staging mechanism.
• No save/recalculation boundary exists for interface intent; the save matrix rows are Not Applicable.
• With deploy disabled, no interfaceActions/deploy call is issued; both peers go outOfSync with the staged CLI in pendingConfig (17 lines through merged/replaced; staged deletion shows sync state pending with 12 lines of removal CLI). No peer asymmetry observed.
• Caveat (same as [Staged configuration audit] vPC Trunk Host interface module #474): vPC interfaces cannot use bulk interfaceActions/remove on ND 4.2.1 (TODO(4.2.1) vpc-interface-bulk-delete-silent-fail), so the module deletes via per-interface DELETE /interfaces/{name} — controller intent is removed immediately, switches remain untouched until a deploy. The staging boundary holds, but the intent removal itself is not deferrable.
• A later fabric-level configDeploy flushes staged interface intent (lab-verified; see the 2026-08-08 clarification on Support staged removal for all modules  #453). A deploy-enabled rerun with unchanged config pushes nothing — deploys queue only on mutation; disposition of this cross-cutting gap is tracked in Support staged removal for all modules  #453.
• Repeated runs are idempotent (changed=false).

Evidence: per-step pendingConfig line counts, configSyncStatus, and API traces in the lab matrix comment above (two-phase delete identical to #474).

Required changes: None at module level; the delete caveat is an ND 4.2.1 API limitation, documented via the workaround marker above. Collection-level rework is tracked in #453.

Estimated effort and dependencies: No module changes required. replaced/overridden idempotency evidence was gathered on the PR #422 branch; results apply to develop once #422 merges.