[ND 4.2+] Add Interface Groups Module

[nikhilsrikrishna]

Related Issue(s)

Closes #326

Proposed Changes

Adds the cisco.nd.nd_manage_interface_group module for managing Interface Groups in Cisco Nexus Dashboard fabrics.

Module capabilities

• Supports merged, replaced, overridden, deleted, and gathered states.
• Supports all Interface Group types: any, ethernetCustom, ethernetWithPolicy, ethernetWithoutPolicy, portChannel, and vpc.
• Supports network associations and switch-interface membership.
• Supports predictive check mode and standard NDOutput, including verbosity-based request diagnostics.
• Supports resource-level interface deployment, switch-level deployment, and staging changes with deploy: false.
• Clears network and interface associations before deleting associated groups.
• Supports paginated gathered queries with local filtering for nested networks, switch interfaces, normalized group types, and custom-template configuration.
• Extends the shared state machine with an optional pre-reconciliation mutation hook for controller operations that require ordered prerequisite changes.

State behavior

• merged is additive for networks, switch interfaces, Ethernet attributes, and custom-template inputs. Existing values omitted from the task are preserved.
• replaced authoritatively manages explicitly supplied fields while preserving omitted network and interface collections. Explicit empty lists clear those collections.
• overridden applies the requested authoritative configuration and removes Interface Groups omitted from the task.
• Interface moves under replaced and overridden are validated before mutation and performed in the required remove-then-add order.
• An any group can contain Ethernet, port-channel, and vPC members. Member additions are submitted in homogeneous batches where required by the controller.

The additive nested-list handling is implemented specifically for Interface Groups so that state=merged does not remove existing networks or members omitted from the task.

Shared state-machine extension

This PR adds an optional prepare_mutations() hook to the shared orchestrator state machine.

The existing state-machine flow performs validation and then proceeds directly to normal create/update reconciliation. Interface Groups require an additional ordered step when moving an interface between groups:

1. Validate the complete requested configuration and move.
2. Remove the interface from its current Interface Group.
3. Add the interface to the target Interface Group.
4. Deploy the affected interfaces or switches when requested.

Adding the interface to the target first can fail because the controller still considers it owned by the source group. Performing the removal during normal target reconciliation is also too late.

The new hook runs after all preflight validation succeeds but before create/update reconciliation begins. This ensures that no prerequisite mutation is attempted until the complete task has passed validation.

The base NDBaseOrchestrator implementation is a no-op, so existing modules retain their current behavior. Interface Groups override the hook to perform the required source-group detachment.

In check mode, the hook does not call the controller. It updates only the in-memory state so that the predicted after, changed, and subsequent reconciliation results represent the complete move.

The hook can also support future modules that require ordered prerequisite mutations before their normal resource updates, without requiring those modules to replace or duplicate the shared reconciliation flow.

Validation and error handling

• Uses Pydantic models for argument specification, normalization, and state-specific validation.
• Rejects duplicate group names and duplicate member ownership within the same task.
• Validates member-name kinds against the selected Interface Group type.
• Verifies that newly referenced networks exist before making changes.
• Validates custom Ethernet templates as user-defined Ethernet policy templates eligible for shared-interface editing.
• Validates custom-template keys, required values, basic types, and enumerated values against the referenced template.
• Handles per-item results from bulk create, delete, and deployment responses. A successful HTTP response is not treated as successful when an individual item reports failure.
• Recognizes HTTP 207 in the legacy ND response helper so the response body reaches the resource-specific per-item validator.
• Preserves actionable controller and validation error messages with changed: false when no mutation occurred.

Deployment behavior

• Resource-level deployment deploys only affected interfaces.
• Switch-level deployment deploys pending configuration for the affected switches and can therefore include changes outside the current task.
• Resource-level deployment does not deploy referenced networks. The module returns a warning directing users to cisco.nd.nd_manage_networks when network deployment must be handled separately.
• deploy: false stages the Interface Group intent without issuing a deployment request.

Integration-test harness

The Interface Groups integration suite follows the check-mode, apply, idempotency, and read-only controller-validation pattern proposed in #337.

Because #337 is still in flight, this PR includes a lightweight interim version of the harness containing the functionality required by the Interface Groups suite. It will be aligned with the final shared implementation if #337 changes before merging.

For negative scenarios, this suite provides a lightweight task-level equivalent of the proposed per-phase message validation by asserting that the returned failure message contains the expected text. The reusable msg_contains harness option and non-GET call-count expectation proposed on #337 are not introduced as shared harness features in this PR.

Test Notes

Unit-test coverage includes:

• Interface Group endpoint construction and payloads
• Pydantic input and response models
• Type-specific member validation
• Additive merge and authoritative replacement behavior
• Custom-template eligibility and input validation
• Network-reference validation
• Member moves and ordered prerequisite mutations
• Per-item multi-status failure handling
• Resource-level and switch-level deployment selection
• Standard module output and verbosity handling
• Integration validation action plugins

The integration-test target includes:

• Testbed preflight, fixture creation, and cleanup
• Every Interface Group type
• Ethernet, port-channel, mixed any, and optional vPC membership
• Custom Ethernet templates
• Network associations
• Resource-level and switch-level deployment
• deploy: false
• merged, replaced, overridden, deleted, and gathered
• Check mode and idempotency
• Gathered filtering and pagination behavior
• Cross-group member moves
• Negative validation and actionable error-message checks
• Delete cleanup and delete idempotency

Environment-dependent vPC and custom-template cases can be enabled through the integration configuration when the required fixtures are available.

Related ND API Resource Category

• analyze
• infa
• 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