Getting Started with the Cisco ACI Integration for NetBox

Customer Preview

The Cisco ACI integration is currently in customer preview. Contact support@netboxlabs.com if you have not already been onboarded.

This guide walks you through setting up the Cisco ACI Integration for NetBox.

• Prerequisites
• Host Requirements
  • System
  • Network
• NetBox Setup
  • Generate Diode Client Credentials
• Agent Setup and Configuration
  • Step 1: Authenticate to the NetBox Labs Image Registry
  • Step 2: Configure the Agent
  • Bootstrap Mode (First-Time Setup)
  • Optional - Dry Run Mode
  • Step 3: Run the Agent
    • Method 1: Set Environment Variables Manually
    • Method 2: Use a .env File (Recommended)
• Expected Output
• View and Apply Discovered Data in NetBox Assurance
  • Accessing NetBox Assurance
  • Explore Deviation Types
  • View Active Deviations
  • Apply Deviations
• View the Cisco ACI Data in NetBox
• Additional Resources
  • Related Documentation
  • Support

---

Prerequisites

Before you begin, ensure you have the following:

• NetBox Cloud or NetBox Enterprise with NetBox Assurance
• Orb Agent Pro credentials (required to download the integration agent image)
• Cisco APIC with REST API access and a user account that can read fabric inventory
• Host system with Docker support
• Network connectivity between your host and both your NetBox instance and the APIC

Host Requirements

System

• Operating System: Linux, macOS, or Windows with Docker support
• Memory: Minimum 2 GB RAM (4 GB recommended)
• Storage: 1 GB free disk space
• Docker: Version 20.10 or later

Network

• Outbound gRPC/gRPCS access to Diode on your NetBox instance (typically port 443 for gRPCS)
• Outbound HTTPS access to your Cisco APIC (typically port 443)
• DNS resolution for both NetBox and APIC hostnames
• Firewall rules configured to allow the above connections from your agent host

---

NetBox Setup

Generate Diode Client Credentials

1. Log in to your NetBox instance.
2. Navigate to Diode → Client Credentials.
3. Click + Add a Credential.
4. Enter a descriptive name (for example, "Cisco ACI Integration").
5. Click Create.

6. Important: Copy and securely store the Client ID and Client Secret - you will need them in the agent configuration.

7. Navigate to Diode → Settings.
8. Copy the Diode target value - you will use this in the agent configuration file.

---

Agent Setup and Configuration

Step 1: Authenticate to the NetBox Labs Image Registry

From your host machine, authenticate to the NetBox Labs registry using the CUSTOMER-IDENTIFIER and token provided by the NetBox Labs team:

docker login -u<CUSTOMER-IDENTIFIER> netboxlabs.jfrog.io

Example session:

% docker login -u<customer-abc123> netboxlabs.jfrog.io
Password:
Login Succeeded

Step 2: Configure the Agent

1. Create the configuration file:

touch agent.yaml

2. Edit the configuration file and add the following. Replace grpcs://your-instance.netboxcloud.com/diode with the value from Diode → Settings → Diode target in the NetBox UI:

orb:
  config_manager:
    active: local
  backends:
    worker:
    common:
      diode:
        target: grpcs://your-instance.netboxcloud.com/diode  # Get this value from Diode > Settings > Diode target
        client_id: ${DIODE_CLIENT_ID}
        client_secret: ${DIODE_CLIENT_SECRET}
        agent_name: cisco_aci_01  # Use a meaningful name to identify this agent
  policies:
    worker:
      cisco_aci_worker:
        config:
          package: nbl-cisco-aci
          schedule: "0 */6 * * *"  # Every 6 hours. Set your desired schedule (see examples below)
          timeout: 5
          APIC_URL: ${APIC_URL}          # APIC controller URL, e.g. https://apic.example.com
          APIC_USERNAME: ${APIC_USERNAME}
          APIC_PASSWORD: ${APIC_PASSWORD}
          SITE_NAME: "ACI Fabric"        # NetBox site name for this fabric (default: "ACI Fabric")
          BOOTSTRAP: false               # Set to true for initial setup only
          # SKIP_SSL: false              # Set to true to disable SSL certificate verification
        scope:                           # Required — leave empty to ingest all tenants and pods
        # scope:                         # Or restrict ingestion to specific tenants or pods:
        #   tenants:
        #     - Production
        #   pods:
        #     - "1"

Schedule Examples

The schedule field uses cron syntax. Common examples:

• "*/30 * * * *" - Every 30 minutes
• "0 * * * *" - Every hour
• "0 */6 * * *" - Every 6 hours
• "0 2 * * *" - Daily at 02:00

Bootstrap Mode (First-Time Setup)

Bootstrap mode creates the custom fields and static entities in NetBox that the integration requires before the first full fabric sync. Run it once on initial setup, then disable it for all subsequent runs.

What bootstrap mode creates:

• ACI-specific custom fields on Device, Interface, VRF, Prefix, and IPAddress objects
• A "Cisco" manufacturer entry
• Device roles: APIC Controller, Spine Switch, Leaf Switch

Configuration:

config:
  BOOTSTRAP: true  # Set to true for initial setup, false for regular operation

First-time run process:

1. Set BOOTSTRAP: true in your configuration.
2. Run the agent and monitor the output for executed successfully.
3. Stop the agent by pressing Ctrl+C once you see executed successfully.
4. Apply the deviations in NetBox Assurance (see Apply Deviations below).
5. Set BOOTSTRAP: false for all future runs.

Optional - Dry Run Mode

The agent can run in dry run mode, which writes discovered data to a JSON file instead of sending it to NetBox. This is useful for troubleshooting or sharing data with the NetBox Labs support team.

Add the following to the diode section of your configuration:

      diode:
        dry_run: true
        dry_run_output_dir: /opt/orb/  # Output file is written to this directory

Step 3: Run the Agent

Run the agent to synchronize ACI fabric data into NetBox.

Method 1: Set Environment Variables Manually

1. Export Diode credentials:

export DIODE_CLIENT_ID="your-client-id"
export DIODE_CLIENT_SECRET="your-client-secret"

2. Export APIC credentials:

export APIC_URL="https://apic.example.com"
export APIC_USERNAME="your-apic-username"
export APIC_PASSWORD="your-apic-password"

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  -e DIODE_CLIENT_SECRET \
  -e DIODE_CLIENT_ID \
  -e APIC_URL \
  -e APIC_USERNAME \
  -e APIC_PASSWORD \
  netboxlabs.jfrog.io/obs-orb-agent-pro/orb-agent-pro \
  run -c /opt/orb/agent.yaml

Method 2: Use a .env File (Recommended)

1. Create a .env file:

touch .env

2. Edit the .env file and add the following:

## NetBox Diode credentials
DIODE_CLIENT_ID=your-client-id
DIODE_CLIENT_SECRET=your-client-secret

## Cisco APIC credentials
APIC_URL=https://apic.example.com
APIC_USERNAME=your-apic-username
APIC_PASSWORD=your-apic-password

Important

Replace the placeholder values with your actual credentials:

• your-client-id and your-client-secret from the NetBox Diode setup
• https://apic.example.com with your APIC hostname or IP address
• your-apic-username and your-apic-password with your APIC credentials

3. Run the agent:

docker run \
  -v $PWD:/opt/orb/ \
  --env-file .env \
  netboxlabs.jfrog.io/obs-orb-agent-pro/orb-agent-pro \
  run -c /opt/orb/agent.yaml

Security Best Practice

Add .env to your .gitignore file to avoid committing credentials to version control:

echo ".env" >> .gitignore

Expected Output

After starting the agent, you will see log output as the integration queries the APIC and sends data to NetBox:

{"time":"2025-07-20T15:15:01.123456789Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_aci.aci_diode:Processing leaf node: leaf-101"}
{"time":"2025-07-20T15:15:02.234567890Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_aci.aci_diode:Processing interface: eth1/1 on device leaf-101"}
{"time":"2025-07-20T15:15:03.345678901Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_aci.aci_diode:Processing VRF: Tenant1:ProdVRF"}
{"time":"2025-07-20T15:15:04.456789012Z","level":"INFO","msg":"worker stderr","log":"INFO:nbl_cisco_aci.aci_diode:Processing prefix: 10.0.1.0/24 from bridge domain: BD-Prod"}
{"time":"2025-07-20T15:15:05.567890123Z","level":"INFO","msg":"worker stderr","log":"INFO:worker.policy.runner:Policy cisco_aci_worker: Successful ingestion"}
{"time":"2025-07-20T15:15:05.678901234Z","level":"INFO","msg":"worker stderr","log":"INFO:apscheduler.executors.default:Job \"PolicyRunner.run\" executed successfully"}

Monitoring and Testing

Success indicator: Look for Successful ingestion in the output to confirm data was sent to NetBox via Diode.

Testing: Run the agent once and press Ctrl+C to stop it after seeing executed successfully. This lets you verify configuration before setting up continuous scheduled operation.

Continuous operation: The agent runs according to your cron schedule until the container is stopped.

View and Apply Discovered Data in NetBox Assurance

After the agent runs, work with the discovered ACI data in NetBox Assurance.

NetBox Assurance identifies deviations between data already in NetBox and the actual operational state discovered by the integration.

Understanding Deviations

Deviations are the delta between what is currently in NetBox and what the integration discovered from the ACI fabric. On the initial run, all discovered objects may appear as deviations if they did not previously exist in NetBox. After the initial sync and deviation application, subsequent runs produce deviations only for changed or new objects.

Accessing NetBox Assurance

1. Navigate to your NetBox instance UI.
2. Click on Assurance in the main navigation menu.

Explore Deviation Types

1. Click on Deviation Types to view the categories of deviations discovered.
2. Click the Name of a deviation type to view deviations of that type.

3. Click the Name of an individual deviation to view its details.

View Active Deviations

1. Click on Active Deviations to view all deviations that have not yet been applied or ignored.
2. Click the Name of a deviation to view its details.

Apply Deviations

1. Select the deviations you want to apply. For large result sets, set Per Page to 500 first.

2. Select the first deviation, hold SHIFT, select the last one, then click Apply Selected.

3. Click Apply X Deviations to write the data to NetBox.

Apply Deviations to a Branch

Instead of writing deviations to the Main NetBox database branch, select another branch from the drop-down menu to apply deviations to that branch first.

Assurance Docs

For detailed information on working with NetBox Assurance, see the documentation.

View the Cisco ACI Data in NetBox

After running the integration and applying discovered data, you can navigate the ACI inventory in NetBox:

1. Click on Devices in the main navigation menu to view discovered APIC controllers, spine switches, and leaf switches.

2. Click on a device to see its interfaces, IP addresses, and ACI-specific custom field values (pod, node ID, fabric).

3. Click on Interfaces on a device to see physical interfaces, LAG/vPC aggregates, SVIs, and management interfaces.

4. Click on IPAM → VRFs to view tenant VRF contexts discovered from the fabric.

5. Click on IPAM → Prefixes to view bridge domain subnets and L3Out external subnets.

6. Click on IPAM → VLANs to view VLANs discovered from static bindings and L2/L3Out attachments.

---

Additional Resources

Related Documentation

• NetBox Assurance Documentation
• Orb Agent Documentation
• Cisco ACI Integration - Technical Information

Support

Email support@netboxlabs.com for support.