Skip to main content

Cisco ACI adapter

What is Cisco ACI?

The Cisco ACI is a software-defined networking (SDN) solution that provides a policy-based, application-centric approach to managing and orchestrating network infrastructure. It is commonly used in data centers for scalable, policy-driven networking.

Sync direction

Cisco ACI → Infrahub

note

Currently, the Cisco ACI adapter supports only one-way synchronization from ACI to Infrahub. Syncing data back into ACI is not yet supported.

Configuration

The adapter reads connection settings from the synchronization configuration and can be overridden by environment variables. Credentials should be provided via a secret manager or environment variables in production.

Configuration parameters

---
name: from-cisco-aci
source:
name: aci
settings:
url: "https://<APIC_CONTROLLER>"
username: "<USER>"
password: "<PASSWORD>"
api_endpoint: "api" # optional, default: api
verify: true # boolean or string ("false","0") accepted

Environment variables

  • CISCO_APIC_URL: overrides settings.url
  • CISCO_APIC_USERNAME: overrides settings.username
  • CISCO_APIC_PASSWORD: overrides settings.password
  • CISCO_APIC_VERIFY: overrides settings.verify; accepts true/false/0/1 (strings are normalized)

Notes:

  • Credentials must come from environment variables or a secret manager in production. Never commit secrets.
  • The adapter normalizes verify to a boolean (strings like false, 0, no are treated as False).
  • The adapter records login timestamps in UTC to avoid timezone related issues and ensure correct token refresh behavior.

Schema mapping examples

Basic device mapping

- name: DcimPhysicalDevice
mapping: "class/fabricNode.json"
identifiers: ["name"]
fields:
- name: name
mapping: "fabricNode.attributes.name"
- name: serial
mapping: "fabricNode.attributes.serial"
- name: role
mapping: "fabricNode.attributes.role"
filters:
- field: "fabricNode.attributes.fabricSt"
operation: "=="
value: "active"

Interface mapping with ACI Jinja filter

- name: DcimPhysicalInterface
mapping: "class/l1PhysIf.json"
identifiers: ["device", "name"]
fields:
- name: name
mapping: "l1PhysIf.attributes.id"
- name: device
mapping: "l1PhysIf.attributes.dn"
reference: DcimPhysicalDevice
- name: description
mapping: "l1PhysIf.attributes.descr"
transforms:
- field: device
expression: "{{ l1PhysIf.attributes.dn.split('/')[2].replace('node-', '') | aci_device_name }}"
- field: status
expression: "{{ 'active' if l1PhysIf.attributes.adminSt == 'up' else 'free' }}"
filters:
- field: "l1PhysIf.attributes.id"
operation: "contains"
value: "eth"

ACI-specific Jinja filters

The ACI adapter provides custom Jinja filters for data transformation:

aci_device_name filter

The aci_device_name filter resolves ACI node IDs to device names automatically. This is particularly useful when mapping physical interfaces to their parent devices.

Usage:

{{ node_id | aci_device_name }}

Example:

  • Input: "102" (ACI node ID)
  • Output: "spine-102" (actual device name from ACI)

Common use case in transforms:

transforms:
- field: device
expression: "{{ l1PhysIf.attributes.dn.split('/')[2].replace('node-', '') | aci_device_name }}"

This transform:

  1. Extracts the node ID from the ACI Distinguished Name (DN)
  2. Removes the "node-" prefix (for example: "node-102""102")
  3. Uses the aci_device_name filter to resolve the node ID to the actual device name

How it works:

  • The adapter automatically queries the ACI fabricNode class during initialization
  • Builds a mapping of node IDs to device names
  • The filter performs a lookup with a fallback to the original node ID if not found

Generating the models

Use the generate command to produce models from the schema mapping and examples:

poetry run infrahub-sync generate --name from-cisco-aci --directory examples/

Common issues and troubleshooting

Authentication and connectivity

  • If you see token refresh errors, ensure the APIC response includes refreshTimeoutSeconds; the adapter forces re-login when refresh data is unavailable.
  • For TLS verification problems, set CISCO_APIC_VERIFY to false in a secure environment (use with caution).

Device reference resolution

  • Interface-device relationship errors: If you see "Unable to locate the node device" errors, ensure:
    • The DcimPhysicalDevice mapping runs before DcimPhysicalInterface in the order configuration
    • The device transform uses the aci_device_name filter correctly: {{ node_id | aci_device_name }}
    • The ACI fabric node query succeeds (check logs for "Built ACI device mapping" messages)

Jinja filter issues

  • aci_device_name filter not found: Ensure you're using the ACI adapter and the filter is correctly spelled

  • Filter returns node ID instead of device name: Check that the fabric node query succeeded during adapter initialization

  • Transform expression errors: Verify the DN parsing logic extracts the correct node ID:

    expression: "{{ l1PhysIf.attributes.dn.split('/')[2].replace('node-', '') | aci_device_name }}"

General debugging

  • Enable DEBUG logging for the adapter to see raw fetched objects and mapping decisions. Logs will not include secrets.
  • Check the device mapping build process in logs: look for "Built ACI device mapping with X entries"