Ansible ND 4.X | ND Manage Switches Module + Pydantic Models + Smart Endpoints

[AKDRG]

This PR introduces the initial implementation of ND Manage switch lifecycle support in the cisco.nd collection.
It adds a new switch management resource layer, endpoint wrappers, Pydantic model hierarchy, utility helpers.

What’s Included

1. New switch lifecycle resource implementation

Added a full resource engine in plugins/module_utils/manage_switches/nd_switch_resources.py
Implements state handling for:

• gathered
• merged
• replaced
• overridden
• deleted
• POAP flows (bootstrap, pre-provision, serial swap)
• RMA flow

Adds structured operation sequencing:

• discovery
• add/remove
• role updates
• credentials save
• wait-for-manageability
• save/deploy finalize

2. ND Manage endpoint layer

Added endpoint models under plugins/module_utils/endpoints/v1/:

• manage_credentials_switches.py
• manage_fabrics_actions.py
• manage_fabrics_bootstrap.py
• manage_fabrics_inventory.py
• manage_fabrics_switchactions.py
• manage_fabrics_switches.py
• manage_fabrics.py

4. Pydantic model framework and nd_manage_switches models

• Added nd_manage_switches model package and exports:
• bootstrap, config, discovery, preprovision, rma, switch_actions, switch_data, enums, validators
• package-level init re-exports for consistent imports

5. Utilities for lifecycle orchestration
   Added helpers in plugins/module_utils/manage_switches:

• utils.py

6. Unit Tests for the Endpoints and Integration Tests for the States supported by the Module.

These utilities centralize grouping, payload shaping, wait/retry logic, and fabric operations.

[mikewiebe]

There is some overlap here with the fabric module endpoints so we should discuss consolidation and moving things like config-save and config-deploy to a more common location instead of under nd_manage_switches

[mikewiebe]

@AKDRG Couple of testing notes:

• We should support state: overridden with an empty config list which would result in the removal of all switches from the fabric.

    - name: Manage Fabric Switches
      cisco.nd.nd_manage_switches:
        fabric: mike_test
        state: overridden
        deploy: false
        config: []

Currently I see the following:

"msg": "'config' is required for 'overridden' state."

• If we add switches using deploy: false and then in a subsequent run change the flag to deploy: true this should result in the switches getting deployed if they are not already deployed.

• After I add switches to the fabric and then re-run the playbook it runs very fast since the switches are added but the change flag still reflects true even though nothing has changed

• I added switches using state: overridden and then tried to add a preprovision switch but got the following error messaged indicating I have to use state: merged for pre-provision. Is this by design? This also seems to impact state: deleted so that we cannot delete pre-provisioned devices so looks like this needs to be fixed.

"msg": "Configuration validation failed for config index 13: [{'type': 'value_error', 'loc': (), 'msg': \"Value error, POAP/Pre-provision operations require 'merged' state, got 'overridden' (switch: 192.168.10.1)\", 'input': {'seed_ip': '192.168.10.1', 'username': 'admin', 'password': '********', 'preprovision': {'serial_number': 'SAL1234ABCD', 'model': 'N9K-C93180YC-EX', 'version': '10.3(1)', 'hostname': 'leaf-preprov', 'config_data': {'models': ['N9K-C93180YC-EX'], 'gateway': '192.168.10.1/24'}, 'discovery_username': None, 'discovery_password': None, 'image_policy': None}, 'auth_proto': 'MD5', 'role': 'leaf', 'preserve_config': False, 'poap': None, 'rma': None}, 'ctx': {'error': ValueError(\"POAP/Pre-provision operations require 'merged' state, got 'overridden' (switch: 192.168.10.1)\")}, 'url': 'https://errors.pydantic.dev/2.12/v/value_error'}]"
}

• Item to discuss: We should consider a query IF the user provides pre-provisioned and or poap devices in the playbook and fail fast if the boostrap settings don't support these workflows

[mikewiebe]

I was not able to add more then one switch to the fabric until I added the following line

diff --git a/plugins/module_utils/nd_config_collection.py b/plugins/module_utils/nd_config_collection.py
index 832cc13..7610d05 100644
--- a/plugins/module_utils/nd_config_collection.py
+++ b/plugins/module_utils/nd_config_collection.py
@@ -56,7 +56,7 @@ class NDConfigCollection:
 
         key = self._extract_key(item)
 
-        if key in self._index:
+        if key is not None and key in self._index:
             raise ValueError(f"Item with identifier {key} already exists. Use replace() to update")
 
         position = len(self._items)

This is just a workaround but I am wondering if merge function from NDConfigCollection should be used instead?