FabricSwitchInventory Utillity and related dependencies by AKDRG · Pull Request #271 · CiscoDevNet/ansible-nd

AKDRG · 2026-05-06T09:34:44Z

plugins/module_utils/utils.py

ADDED:
- Import statements:
  - logging
  - EpManageFabricsSwitchesGet from endpoints
  - NDConfigCollection
- SwitchOperationError exception class
  - Custom exception for switch operation failures
- ApiDataChecker class
  - Validates API responses for embedded error codes
  - Detects controller errors in DATA payloads
  - Method: check(data, context, log, fail_callback)
- FabricSwitchInventory class
  - Indexes switch model instances for fast lookup
  - Methods:
    - init(switches)
    - from_fabric(nd, fabric, log, model_class) [classmethod]
    - by_ip() -> Dict[str, Any]
    - by_id() -> Dict[str, Any]
    - query_fabric_switches(nd, fabric, log) [staticmethod]
  - Properties:
    - switches: List of switch models
    - collection: NDConfigCollection instance
plugins/module_utils/endpoints/v1/manage/manage_fabrics_switches.py

Switch inventory endpoint definitions

CLASSES:
- FabricSwitchesGetEndpointParams
  - Query parameters for list switches endpoint
  - Fields: hostname, max, offset, filter
- FabricSwitchesAddEndpointParams
  - Query parameters for add switches endpoint
  - Fields: cluster_name, ticket_id
- _EpManageFabricsSwitchesBase
  - Base class for fabric switches endpoints
  - Provides common functionality
- EpManageFabricsSwitchesGet
  - GET endpoint: /api/v1/manage/fabrics/{fabricName}/switches
  - Lists all switches in a fabric with optional filtering
plugins/module_utils/models/manage_switches/init.py

Package initialization

EXPORTS:
- SwitchDataModel
- Enumerations: SwitchRole, SystemMode, PlatformType, SnmpV3AuthProtocol,
  DiscoveryStatus, ConfigSyncStatus, VpcRole, RemoteCredentialStore,
  AnomalyLevel, AdvisoryLevel
plugins/module_utils/models/manage_switches/switch_data_models.py

Switch inventory data models

CLASSES:
- TelemetryIpCollection (NDNestedModel)
  - Inband and out-of-band telemetry IP addresses
  - Fields: inband_ipv4_address, inband_ipv6_address,
    out_of_band_ipv4_address, out_of_band_ipv6_address
- VpcData (NDNestedModel)
  - vPC pair configuration and operational status
  - Fields: vpc_domain, peer_switch_id, consistent_status,
    intended_peer_name, keep_alive_status, peer_link_status,
    peer_name, vpc_role
- SwitchMetadata (NDNestedModel)
  - Internal database identifiers
  - Fields: switch_db_id, switch_uuid
- AdditionalSwitchData (NDNestedModel)
  - Platform-specific data for NX-OS switches
  - Fields: usage, config_sync_status, discovery_status, domain_name,
    smart_switch, platform_type, system_mode, vendor, username, etc.
- AdditionalAciSwitchData (NDNestedModel)
  - Platform-specific data for ACI switches
  - Fields: usage, admin_status, health_score, node_id, pod_id, etc.
- SwitchDataModel (NDBaseModel) *** MAIN MODEL ***
  - Complete inventory record for a switch
  - Identifier: switch_id (serial number)
  - Key Fields:
    - switch_id (required)
    - serial_number
    - fabric_management_ip
    - hostname
    - model
    - software_version
    - switch_role
    - system_up_time
    - additional_data
    - vpc_configured, vpc_data
    - telemetry_ip_collection
  - Methods:
    - to_payload() -> Dict
    - from_response(response) -> SwitchDataModel [classmethod]
    - to_config_dict() -> Dict
  - Validators:
    - validate_switch_id (requires non-empty serial number)
    - validate_mgmt_ip (validates IP address format)
    - parse_additional_data (routes to correct nested model)
plugins/module_utils/models/manage_switches/enums.py

Enumerations for switch operations

ENUMERATIONS:
- SwitchRole
  - Values: border, borderGateway, leaf, spine, superSpine, tor,
    access, aggregation, coreRouter, edgeRouter, meta, neighbor, etc.
  - Methods: choices(), from_user_input(), normalize()
- SystemMode
  - Values: normal, maintenance, migration, inconsistent, waiting,
    notApplicable
- PlatformType
  - Values: nx-os, other, ios-xe, ios-xr, sonic, apic
- SnmpV3AuthProtocol
  - Values: md5, sha, md5-des, md5-aes, sha-aes, sha-des,
    sha-aes-256, sha-224, sha-256, sha-384, sha-512, etc.
- DiscoveryStatus
  - Values: ok, discovering, rediscovering, unreachable,
    discoveryTimeout, retrying, sshSessionError, etc.
- ConfigSyncStatus
  - Values: deployed, deploymentInProgress, failed, inProgress,
    inSync, outOfSync, pending, success, etc.
- VpcRole
  - Values: primary, secondary, operationalPrimary,
    operationalSecondary, noneEstablished
- RemoteCredentialStore
  - Values: local, cyberark
- AnomalyLevel
  - Values: critical, major, minor, warning, healthy,
    notApplicable, unknown
- AdvisoryLevel
  - Values: critical, major, minor, warning, healthy,
    none, notApplicable
plugins/module_utils/models/manage_switches/validators.py

NEW FILE - Field validation utilities

CLASS: SwitchValidators

VALIDATION METHODS (nullable):
- validate_ip_address(v) -> Optional[str]
  - Validates IPv4 or IPv6 address format
- validate_cidr(v) -> Optional[str]
  - Validates CIDR notation (IP/mask)
- validate_serial_number(v) -> Optional[str]
  - Validates alphanumeric serial number with optional hyphens
- validate_hostname(v) -> Optional[str]
  - Validates RFC 1123 hostname format
- validate_mac_address(v) -> Optional[str]
  - Validates MAC address format (colon or hyphen separated)
- validate_vpc_domain(v) -> Optional[int]
  - Validates VPC domain ID (1-1000)
REQUIRED FIELD HELPERS:
- require_serial_number(v, field_name) -> str
  - Ensures non-empty serial number
- require_hostname(v) -> str
  - Ensures non-empty hostname
- require_ip_address(v) -> str
  - Ensures non-empty IP address
- validate_cidr_optional(v) -> Optional[str]
  - Validates optional CIDR string
- check_discovery_credentials_pair(username, password) -> None
  - Enforces mutual presence of username and password

================================================================================
USAGE EXAMPLE

from ansible_collections.cisco.nd.plugins.module_utils.utils import (
FabricSwitchInventory,
ApiDataChecker,
SwitchOperationError,
)
from ansible_collections.cisco.nd.plugins.module_utils.models.manage_switches import (
SwitchDataModel,
)

Fetch and index all switches in a fabric

inventory = FabricSwitchInventory.from_fabric(
nd=nd_module,
fabric="MyFabric",
log=logger,
model_class=SwitchDataModel
)

Lookup by IP address

switch = inventory.by_ip().get("192.168.1.1")
if switch:
print(f"Found switch: {switch.hostname}")

Lookup by serial number (switch ID)

switch = inventory.by_id().get("FDO12345ABC")
if switch:
print(f"Switch IP: {switch.fabric_management_ip}")

Access all switches

all_switches = list(inventory.collection)
for switch in all_switches:
print(f"{switch.hostname} - {switch.fabric_management_ip}")

Access the NDConfigCollection directly

collection = inventory.collection
existing_switch = collection.get("FDO12345ABC")

================================================================================
DEPENDENCIES

REQUIRED (already exist in ND_Changes):

plugins/module_utils/nd_config_collection.py
- NDConfigCollection class with from_api_response() method
plugins/module_utils/models/base.py
- NDBaseModel class
plugins/module_utils/models/nested.py
- NDNestedModel class
plugins/module_utils/common/pydantic_compat.py
- Field, field_validator from Pydantic
plugins/module_utils/enums.py
- HttpVerbEnum
plugins/module_utils/endpoints/base.py
- NDEndpointBaseModel
plugins/module_utils/endpoints/mixins.py
- FabricNameMixin, FilterMixin, MaxMixin, OffsetMixin, etc.
plugins/module_utils/endpoints/query_params.py
- EndpointQueryParams
plugins/module_utils/endpoints/v1/manage/base_path.py
- BasePath class

================================================================================
KEY FEATURES

Fast Lookup
- O(1) lookup by IP address using by_ip() dictionary
- O(1) lookup by serial number using by_id() dictionary
API Response Validation
- ApiDataChecker detects embedded error codes in responses
- Prevents silent failures from controller errors
Flexible Model Support
- Works with any Pydantic model class
- SwitchDataModel provided for standard switch inventory
Comprehensive Switch Data
- Complete switch inventory information
- vPC configuration and status
- Telemetry IP addresses
- Platform-specific additional data
- ACI and NX-OS switch support
Field Validation
- IP address validation (IPv4/IPv6)
- Serial number format validation
- Hostname RFC 1123 compliance
- Enumeration normalization
Integration Ready
- Compatible with NDConfigCollection
- Works with existing ND module infrastructure
- No breaking changes to existing code

Co-authored-by: Copilot <copilot@github.com>

akinross · 2026-05-07T08:12:53Z

+    def parse_additional_data(cls, v: Any) -> Any:
+        """Route additionalData to the correct nested model.
+
+        The NDFC API may omit the ``usage`` field for non-ACI switches.


do we still refer to NDFC?

No, good catch we need to make sure we only use ND

akinross · 2026-05-07T08:20:23Z

+        if v is None:
+            return None
+        v = str(v).strip()
+        if not v:
+            return None


this block is repeated over multiple validation functions? should we create a helper function for this?

akinross · 2026-05-07T08:29:00Z

+from typing import Optional
+
+
+class SwitchValidators:


how do we test the behaviour of these validators?

Added Unit Tests for validators.

akinross · 2026-05-07T08:35:11Z

+        v = str(v).strip()
+        if not v:
+            return None
+        if "/" not in v:


Did you consider normalising a single IP to a /32?

akinross · 2026-05-07T08:37:41Z

+        if not v:
+            return None
+        # Serial numbers are typically alphanumeric with optional hyphens
+        if not re.match(r"^[A-Za-z0-9_-]+$", v):


Is there a place in the repository/collection to define re-usable regex statements? I see regex statements defined throughout various PRs, where re-use might be possible for thing like serial numbers, hostnames.

akinross · 2026-05-07T08:41:23Z

+        if not re.match(r"^[a-zA-Z0-9][a-zA-Z0-9._-]*$", v):
+            raise ValueError(f"Invalid hostname format. Must start with alphanumeric and " f"contain only alphanumeric, dots, hyphens, underscores: {v}")
+        if v.startswith(".") or v.endswith(".") or ".." in v:
+            raise ValueError(f"Invalid hostname format (dots): {v}")


these could be combined, is there a reason to separate? also the v.startswith(".") check is redundant because the first regex (^[a-zA-Z0-9]) makes a leading . impossible.

is there a reason for " f" in the first ValueError?

akinross · 2026-05-07T08:46:33Z

+        if not v:
+            return None
+        # Accept colon or hyphen separated MAC addresses
+        mac_pattern = r"^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$"


is this the only mac address pattern we accept? aabb.ccdd.eeff or bare-hex should also classify as valid mac addresses in my opinion.

we could leverage something like netaddr dependency or extend the regex

The validators was originally designed to pick in the data, and hence the MAC only from the ND. It has now been extended to include the suggested patterns as well. Thanks!

akinross · 2026-05-07T08:49:44Z

+from typing import Optional
+
+
+class SwitchValidators:


if only static methods why define the class? can't you simply import the function that you require?

if we want to have re-usable validators (ip, mac, hostname, serial, etc ) should we consider these to be designed with re-use throughout modules?

You're right. Fixed.

…fabric_inventory.py

Co-authored-by: Copilot <copilot@github.com>

Code changes for FabricSwitchInventory and related dependencies

5428dca

Co-authored-by: Copilot <copilot@github.com>

AKDRG requested review from akinross, allenrobel, anvitha-jain, gmicol, lhercot, mikewiebe, mtarking, sajagana, samiib and shrsr as code owners May 6, 2026 09:34

AKDRG added 2 commits May 6, 2026 15:30

Black Formatting

a6d7e7b

Sanity Fix

e861771

AKDRG force-pushed the fabric_inventory branch from e08073e to e861771 Compare May 6, 2026 10:36

akinross reviewed May 7, 2026

View reviewed changes

jeetugangwar11 and others added 8 commits May 8, 2026 12:30

[Jeet] Refactored the utils.py and moved inventory call out of it to …

844c201

…fabric_inventory.py

Update fabric_inventory.py

8e61349

[Jeet] Sanity fixes

50cb755

[Jeet] Added missing NodeNameMixin in mixin for sanity issue fix.

2938ab1

[Jeet] Remove content from _init_.py file for sanity fix

da3fa42

Validators Fix

3e54ec1

Co-authored-by: Copilot <copilot@github.com>

Fix Sanity

7d6501b

Fix Annotations and Types

920e7b4

Co-authored-by: Copilot <copilot@github.com>

Conversation

AKDRG commented May 6, 2026

plugins/module_utils/utils.py

plugins/module_utils/endpoints/v1/manage/manage_fabrics_switches.py

plugins/module_utils/models/manage_switches/init.py

plugins/module_utils/models/manage_switches/switch_data_models.py

plugins/module_utils/models/manage_switches/enums.py

plugins/module_utils/models/manage_switches/validators.py

================================================================================ USAGE EXAMPLE

Fetch and index all switches in a fabric

Lookup by IP address

Lookup by serial number (switch ID)

Access all switches

Access the NDConfigCollection directly

================================================================================ DEPENDENCIES

================================================================================ KEY FEATURES

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

================================================================================
USAGE EXAMPLE

================================================================================
DEPENDENCIES

================================================================================
KEY FEATURES