Cisco ACI Adapter
Relevant source files
The following files were used as context for generating this wiki page:
The Cisco ACI Adapter enables synchronization between a Cisco ACI fabric and Infrahub. It connects to the Cisco Application Policy Infrastructure Controller (APIC) via REST API to extract infrastructure data such as tenants, topology, nodes, and physical interfaces. Within the Sync architecture, this adapter primarily serves as a source to populate Infrahub with live network inventory.
Sources: infrahub_sync/adapters/aci.py:73-75, examples/aci_to_infrahub/config.yml:5-12, README.md:92
Architecture and Components
The adapter architecture comprises three main components: the AciApiClient for low-level HTTP communication, the AciAdapter for DiffSync integration, and the AciModel for data transformation.
Component Relationship
The following diagram illustrates how the ACI components interact during a synchronization run:
Key Classes
| Class | Description |
|---|---|
AciApiClient | Manages authentication, token refreshing, and REST requests to the APIC. |
AciAdapter | Implements the DiffSyncMixin to load ACI objects into the DiffSync store. |
AciModel | Inherits DiffSyncModelMixin and provides ACI-specific Jinja2 filters for transformations. |
Sources: infrahub_sync/adapters/aci.py:27, infrahub_sync/adapters/aci.py:177, infrahub_sync/adapters/aci.py:355
Authentication and API Client
The AciApiClient handles login procedures and maintains session state. It uses the aaaLogin.json endpoint to retrieve authentication cookies and a refresh timeout. The client automatically refreshes the token if the current time exceeds the refreshTimeoutSeconds provided by the APIC.
Sources: infrahub_sync/adapters/aci.py:77-86, infrahub_sync/adapters/aci.py:141-147
Login Sequence
This sequence diagram details the authentication flow used before executing data requests:
Sources: infrahub_sync/adapters/aci.py:77-139
Data Loading Logic
The AciAdapter.model_loader method orchestrates data extraction. It iterates through the schema_mapping defined in the configuration, fetches objects from the APIC using the specified mapping (ACI class), and processes them through filters and transforms.
Sources: infrahub_sync/adapters/aci.py:205-215, dev/knowledge/adapter-anatomy.md:32-34
ID Extraction and Device Mapping
During initialization, the adapter builds a device_mapping by querying fabricNode objects. This mapping allows the adapter to resolve numeric ACI node IDs to human-readable device names during the sync process. The adapter uses _extract_aci_id to handle the nested JSON structure returned by the APIC, specifically looking for id attributes within class-specific keys.
Sources: infrahub_sync/adapters/aci.py:186-188, infrahub_sync/adapters/aci.py:321-344, infrahub_sync/adapters/aci.py:346-352
Configuration and Schema Mapping
The adapter is configured via a YAML file that specifies connection settings and resource mappings.
Connection Settings
| Setting | Environment Variable | Description |
|---|---|---|
url | CISCO_APIC_URL | The base URL of the APIC controller. |
username | CISCO_APIC_USERNAME | The APIC username for login. |
password | CISCO_APIC_PASSWORD | The APIC password for login. |
verify | CISCO_APIC_VERIFY | SSL verification (bool or string "false"/"no"). |
Sources: infrahub_sync/adapters/aci.py:190-196, examples/aci_to_infrahub/config.yml:7-12
Schema Mapping Example
The mapping translates ACI classes (e.g., fvTenant, fabricNode) into Infrahub models.
schema_mapping:
- name: OrganizationCustomer
mapping: "class/fvTenant.json"
identifiers: ["name"]
fields:
- name: name
mapping: "fvTenant.attributes.name"
filters:
- field: "fvTenant.attributes.name"
operation: "not in"
value: ["infra", "mgmt"]
Sources: examples/aci_to_infrahub/config.yml:25-39
Custom Jinja Filters
The AciModel provides the aci_device_name filter, which is available in transforms within the config.yml. This filter uses the adapter's pre-built device mapping to replace ACI node IDs found in Distinguished Names (DNs) with actual device names.
Sources: infrahub_sync/adapters/aci.py:365-377, examples/aci_to_infrahub/config.yml:83
Summary
The Cisco ACI Adapter provides a robust bridge for synchronizing fabric inventory into Infrahub. It manages complex ACI API session handling and provides specialized transformation tools like the aci_device_name filter to ensure data in Infrahub is readable and accurate. By adhering to the DiffSyncMixin contract, it integrates seamlessly into the standard Infrahub Sync workflow of diff and sync.