bbricardo/netbox-sync

NetBox-Sync

镜像概述和主要用途

NetBox-Sync 是一款用于将不同来源的数据同步到 NetBox 实例的工具。该工具支持从 VMware vCenter Server 和 check_redfish 清单文件中同步数据，旨在为需要自动化网络状态导入的用户提供中间解决方案，同时保持 NetBox 作为"事实来源"的设计理念。

核心功能和特性

• 多源数据同步：支持从 VMware vCenter 和 check_redfish 等多种来源同步数据
• 对象生命周期管理：为同步对象添加 NetBox-synced 标签，便于识别和管理
• 自动清理机制：能够识别并移除 NetBox 中不再存在于数据源中的陈旧对象
• 配置灵活性：支持通过配置文件（INI/YAML）和环境变量进行配置，环境变量优先级更高
• 多配置文件支持：允许指定多个配置文件，按顺序解析并覆盖相同配置项
• 干运行模式：支持测试运行而不实际修改 NetBox 数据
• 详细日志记录：提供多种日志级别，便于调试和监控
• 数据缓存：利用 NetBox 对象的"last_updated"属性进行缓存，优化性能

使用场景和适用范围

• 需要将 VMware vCenter 虚拟环境数据同步到 NetBox 的场景
• 使用 check_redfish 工具管理硬件设备并需要同步到 NetBox 的环境
• 希望自动化维护 NetBox 中网络设备和虚拟机状态的网络管理团队
• 需要定期更新 NetBox 数据但又不想完全手动维护的环境
• 多数据源环境需要集中管理网络资产信息的场景

详细的使用方法和配置说明

系统要求

软件要求

• python >= 3.6
• packaging
• urllib3==2.2.1
• wheel
• requests==2.31.0
• pyvmomi==8.0.2.0.1
• aiodns==3.0.0
• pyyaml==6.0.1

环境要求

• NetBox >= 2.9

数据源要求

• VMware 数据源：VMware vCenter >= 6.0
• check_redfish 数据源：check_redfish >= 1.2.0

安装步骤

RedHat 系操作系统

shell
# RedHat/CentOS 7
yum install python36-pip

# RedHat/CentOS 8+
yum install python3-pip

Ubuntu 18.04/20.04/22.04

shell
apt-get update && apt-get install python3-venv

克隆仓库并安装依赖

shell
cd /opt
git clone https://github.com/bb-Ricardo/netbox-sync.git
cd netbox-sync
python3 -m venv .venv
. .venv/bin/activate
pip3 install --upgrade pip || pip install --upgrade pip
pip3 install wheel || pip install wheel

# 对于 Python 3.6，请使用 requirements_3.6.txt
pip3 install -r requirements.txt || pip install -r requirements.txt

VMware 标签同步支持（如需要）

shell
# 在激活的虚拟环境中执行
pip install --upgrade git+https://github.com/vmware/vsphere-automation-sdk-python.git

NetBox API 令牌

需要一个具有以下权限的 NetBox API 令牌：

• 所有读/写权限，除了：
  • auth
  • secrets
  • users

运行脚本

基本用法

usage: netbox-sync.py [-h] [-c settings.ini [settings.ini ...]] [-g]
                      [-l {DEBUG3,DEBUG2,DEBUG,INFO,WARNING,ERROR}] [-n] [-p]

Sync objects from various sources to NetBox

Version: 1.8.0 (2025-03-07)
Project URL: https://github.com/bb-Ricardo/netbox-sync

options:
  -h, --help            显示帮助信息并退出
  -c settings.ini [settings.ini ...] 指定配置文件路径
  -g, --generate_config 生成默认配置文件
  -l {DEBUG3,DEBUG2,DEBUG,INFO,WARNING,ERROR} 设置日志级别（覆盖配置）
  -n, --dry_run         模拟运行，不实际修改 NetBox 数据
  -p, --purge           删除所有由该脚本创建的同步对象

测试建议

建议使用 DEBUG2 日志级别和干运行选项 -n 进行测试，以避免直接修改 NetBox 数据：

shell
/opt/netbox-sync/netbox-sync.py -l DEBUG2 -n

配置说明

NetBox-Sync 支持两种配置方式，可以组合使用：

• 配置文件（默认路径为 ./settings.ini）
• 环境变量（优先级高于配置文件）

配置文件

支持的配置文件类型：

• ini
• yaml

可以指定多个配置文件，按顺序解析并覆盖相同配置项：

bash
/opt/netbox-sync/netbox-sync.py -c common.ini all-sources.yaml additional-config.yaml

生成配置文件示例：

bash
# 生成 ini 格式示例配置
/opt/netbox-sync/netbox-sync.py -g -c settings-example.ini

# 生成 yaml 格式示例配置
/opt/netbox-sync/netbox-sync.py -g -c settings-example.yaml 

环境变量

所有配置项都可以通过环境变量设置，前缀为 NBS，格式如下：

NBS_<SECTION_NAME>_<CONFIG_OPTION_KEY>=value

示例：

bash
# 等同于在配置文件中设置 common.log_level = DEBUG2
NBS_COMMON_LOG_LEVEL="DEBUG2"

# 等同于在配置文件中设置 netbox.host_fqdn = netbox-host.example.com
NBS_NETBOX_HOST_FQDN="netbox-host.example.com"

数据源配置需要使用索引：

bash
# 定义一个名为 example-vcenter 的数据源
NBS_SOURCE_1_NAME="example-vcenter"
NBS_SOURCE_1_PASSWORD="super-secret-password"
NBS_SOURCE_1_CUSTOM_DNS_SERVERS="10.0.23.23, 10.0.42.42"

Docker 部署方案

构建镜像

shell
docker build -t bbricardo/netbox-sync:latest .

运行容器

shell
docker run --rm -it -v $(pwd)/settings.ini:/app/settings.ini bbricardo/netbox-sync:latest

使用环境变量配置

shell
docker run --rm -it \
  -e NBS_NETBOX_HOST_FQDN="netbox.example.com" \
  -e NBS_NETBOX_API_KEY="your-api-key" \
  -e NBS_SOURCE_1_NAME="vcenter-source" \
  -e NBS_SOURCE_1_TYPE="vmware" \
  -e NBS_SOURCE_1_HOST_FQDN="vcenter.example.com" \
  -e NBS_SOURCE_1_USERNAME="vcenter-readonly" \
  -e NBS_SOURCE_1_PASSWORD="secret" \
  bbricardo/netbox-sync:latest

Docker Compose 配置

yaml
version: '3.8'

services:
  netbox-sync:
    image: bbricardo/netbox-sync:latest
    container_name: netbox-sync
    restart: unless-stopped
    environment:
      - NBS_COMMON_LOG_LEVEL=INFO
      - NBS_NETBOX_HOST_FQDN=netbox.example.com
      - NBS_NETBOX_API_KEY=${NETBOX_API_KEY}
      - NBS_NETBOX_PRUNE_ENABLED=true
      - NBS_SOURCE_1_NAME=vcenter-main
      - NBS_SOURCE_1_TYPE=vmware
      - NBS_SOURCE_1_HOST_FQDN=vcenter.example.com
      - NBS_SOURCE_1_USERNAME=${VCENTER_USERNAME}
      - NBS_SOURCE_1_PASSWORD=${VCENTER_PASSWORD}
    volumes:
      - ./config:/app/config
    command: ["-c", "/app/config/settings.yaml"]

Kubernetes 部署方案

创建配置文件 (settings.yaml)

yaml
netbox:
  host_fqdn: netbox.example.com
  prune_enabled: true

source:
  my-vcenter-example:
    type: vmware
    host_fqdn: vcenter.example.com
    permitted_subnets: 172.16.0.0/12, 10.0.0.0/8, 192.168.0.0/16, fd00::/8

创建密钥文件 (secrets.yaml)

yaml
netbox:
  api_token: XYZXYZXYZXYZXYZXYZXYZXYZ
source:
  my-vcenter-example:
    username: vcenter-readonly
    password: super-secret

创建 Kubernetes 资源

shell
kubectl create configmap netbox-sync-config --from-file=settings.yaml
kubectl create secret generic netbox-sync-secrets --from-file=secrets.yaml

CronJob 配置 (k8s-netbox-sync-cronjob.yaml)

yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: netbox-sync
spec:
  schedule: "23 */2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: netbox-sync
            image: bbricardo/netbox-sync:latest
            volumeMounts:
            - name: config-volume
              mountPath: /app/config
            - name: secret-volume
              mountPath: /app/secrets
              readOnly: true
            command: ["/app/netbox-sync.py", "-c", "/app/config/settings.yaml", "/app/secrets/secrets.yaml"]
          volumes:
          - name: config-volume
            configMap:
              name: netbox-sync-config
          - name: secret-volume
            secret:
              secretName: netbox-sync-secrets
          restartPolicy: OnFailure

部署 CronJob

shell
kubectl apply -f k8s-netbox-sync-cronjob.yaml

定时任务配置

在 Linux 系统中，可以通过 cron 定时运行同步任务：

shell
# 编辑 crontab
crontab -e

# 添加以下行（每2小时的第23分钟运行）
23 */2 * * *  /opt/netbox-sync/.venv/bin/python3 /opt/netbox-sync/netbox-sync.py >/dev/null 2>&1

工作原理

基本流程

1. 解析并验证配置
2. 初始化所有数据源并建立与 NetBox 的连接
3. 从 NetBox 读取当前数据
4. 从所有数据源读取数据并在内存中添加/更新对象
5. 根据数据源数据更新 NetBox
6. 清理陈旧对象

NetBox 连接

• 请求所有当前 NetBox 对象，尽可能使用缓存
• 支持"last_updated"属性的对象类型可利用缓存优化
• 请求超时会重试多次，所有重试失败则程序退出

支持的数据源

• VMware vCenter：同步虚拟机、主机、网络等信息
• check_redfish：同步硬件设备信息

可以配置多个相同类型的数据源，例如多个 vCenter 实例：

ini
[source/vcenter-BLN]
enabled = True
host_fqdn = vcenter1.berlin.example.com

[source/vcenter-NYC]
enabled = True
host_fqdn = vcenter2.new-york.example.com

清理机制

NetBox 中不再存在于任何数据源的对象将被清理：

1. 首先标记为"Orphaned"（孤立）
2. 经过配置的天数后从 NetBox 中删除

支持清理的对象类型：

• 设备 (devices)
• 虚拟机 (VMs)
• 设备接口 (device interfaces)
• 虚拟机接口 (VM interfaces)
• IP 地址 (IP addresses)

其他对象（如 VLAN、集群、制造商）将保留来源标签但不会被删除，因为它们可能被其他 NetBox 对象使用。

许可证

NetBox-Sync 采用 MIT 许可证，详情请参见 https://github.com/bb-Ricardo/netbox-sync/blob/main/LICENSE.txt%E3%80%82