Плагины NetBox 4.7.5: ставим Topology Views и NetBox DNS в Docker

Зачем нужны плагины и почему в Docker их ставят иначе

Стандартный NetBox — источник истины по оборудованию, стойкам, адресам и префиксам. Двух привычных вещей «из коробки» в нём нет: он не рисует карты связей между устройствами и не ведёт DNS-зоны. Обе задачи закрываются плагинами — обычными Python-пакетами, которые регистрируются в конфигурации NetBox и добавляют свои модели, миграции, разделы меню и статику.

В Docker-развёртывании есть важная особенность: pip install внутри работающего контейнера — тупиковый путь. Изменения живут до первого пересоздания контейнера, а после обновления образа плагины исчезнут вместе со слоем. Правильный способ — собрать собственный образ на базе официального, в котором пакеты плагинов уже установлены, и указать этот образ в compose-файле.

Ниже — последовательность, проверенная на NetBox 4.7.5 (netbox-docker 5.1.1). Я прошёл её целиком на стенде: пустой список плагинов, сборка образа, миграции, статика, наполнение демо-данными и скриншоты интерфейса.

Два самых популярных плагина

Выбор не на глаз: по статистике загрузок с PyPI за последний месяц это две самые скачиваемые надстройки NetBox.

Topology Views 5.0.2 — около 19 тыс. загрузок в месяц и более 1,1 тыс. звёзд на GitHub. Строит карту топологии по кабелям, которые уже заведены в NetBox: фильтры по площадке, роли и тегам, экспорт в PNG и XML для draw.io, сохранение координат узлов.
NetBox DNS 1.7.3 — около 18 тыс. загрузок в месяц и порядка 380 звёзд. Ведёт DNS как ещё один источник истины: виды, зоны, серверы имён, записи, автоматические PTR и SOA, шаблоны зон.

Пара удачна и по механике: первый плагин почти не хранит данных и состоит из интерфейса и статики, второй добавляет полноценные модели и миграции. Если заработали оба, остальные встанут по той же схеме.

Оба пакета объявляют минимальную версию NetBox 4.7.0, то есть для 4.7.5 подходят. Версии обязательно фиксировать: у Topology Views совместимость жёсткая — ветка 4.7.x работает только с 5.0.2, и при обновлении NetBox плагин обновляют вместе с ним.

Шаг 1. Смотрим, что есть сейчас

Все команды выполняются в каталоге развёртывания, в прошлой статье это /opt/netbox/netbox-docker. Проверяем, что стенд жив, а плагинов ещё нет:

cd /opt/netbox/netbox-docker
docker compose ps

Список плагинов в интерфейсе — «Система → Плагины», адрес /core/plugins/. До установки он пуст. Перед работами с образом и миграциями снимаем дамп базы: плагины добавляют таблицы, и откатывать это на живой базе неприятно.

docker compose exec -T postgres sh -c 'pg_dump -U $POSTGRES_USER $POSTGRES_DB' > netbox-$(date +%F).sql

Шаг 2. Список пакетов

В корне каталога создаём файл plugin_requirements.txt. В него попадают только плагины, отдельно от requirements.txt самого NetBox:

cat > plugin_requirements.txt <<'EOF'
netbox-topology-views==5.0.2
netbox-plugin-dns==1.7.3
EOF

Точные версии здесь принципиальны. Без пина сборка через полгода притянет свежий плагин, который уже требует NetBox 4.8, и контейнер перестанет стартовать с ошибкой о несовместимой версии.

Шаг 3. Dockerfile для своего образа

Ключевой момент: в образе netbox-docker 5.x нет pip. Виртуальное окружение собрано через uv, и привычная команда /opt/netbox/venv/bin/pip install падает с «No module named pip». Именно на этом спотыкаются при переносе старых инструкций. Ставим пакеты через uv и сразу запекаем статику плагинов в образ:

cat > Dockerfile-Plugins <<'EOF'
ARG VERSION=v4.7.5-5.1.1
FROM netboxcommunity/netbox:${VERSION}

COPY ./plugin_requirements.txt /opt/netbox/
RUN /usr/local/bin/uv pip install -r /opt/netbox/plugin_requirements.txt

# каталог статики для картинок карты топологии
RUN mkdir -p /opt/netbox/netbox/static/netbox_topology_views/img

# список плагинов нужен уже на этапе сборки, чтобы collectstatic увидел их файлы
COPY configuration/plugins.py /etc/netbox/config/plugins.py
RUN DEBUG="true" SECRET_KEY="dummydummydummydummydummydummydummydummydummydummy" \
    /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py collectstatic --no-input
EOF

Строка с mkdir нужна именно Topology Views: плагин складывает изображения узлов в static/netbox_topology_views/img, без каталога часть функций отваливается. Требование есть в README плагина, но легко пропускается.

Сборка статики на этапе образа удобнее, чем в работающем контейнере: файлы остаются в образе и не пропадают при пересоздании. Ключ SECRET_KEY здесь фиктивный — он нужен только для запуска collectstatic и в готовый контейнер не попадает.

Шаг 4. Включаем плагины в конфигурации

Установленный пакет — ещё не включённый плагин. NetBox читает список приложений из PLUGINS. В netbox-docker конфигурация разложена по файлам каталога configuration, который монтируется в /etc/netbox/config. Правим configuration/plugins.py:

PLUGINS = [
    "netbox_topology_views",
    "netbox_dns",
]

Здесь важна разница между именем пакета и именем приложения. В plugin_requirements.txt пакет называется netbox-plugin-dns, через дефисы, а в PLUGINS указывается netbox_dns, через подчёркивания — так называется Python-модуль. Перепутаете — получите «Unable to import plugin».

Если каталога configuration в развёртывании нет (например, compose-файл писался вручную), файлы конфигурации нужно сначала достать из образа. Монтирование пустого каталога перекроет configuration.py с настройками базы, и NetBox не запустится:

mkdir -p configuration
docker compose cp netbox:/etc/netbox/config/. configuration/
# затем добавляем PLUGINS в configuration/plugins.py

Дополнительные параметры, если они нужны, задаются в PLUGINS_CONFIG в том же файле: у Topology Views это, например, static_image_directory и allow_coordinates_saving. Обоим нашим плагинам настроек по умолчанию достаточно.

Шаг 5. Подменяем образ в compose

Создаём docker-compose.override.yml: сервисы должны собираться из нашего Dockerfile и использовать получившийся образ. Переопределяем и воркер — иначе он останется на старом образе и не увидит задачи плагинов.

services:
  netbox:
    image: netbox:4.7.5-plugins
    pull_policy: never
    build:
      context: .
      dockerfile: Dockerfile-Plugins
  netbox-worker:
    image: netbox:4.7.5-plugins
    pull_policy: never

В официальном compose-файле воркер наследует тома и настройки NetBox через YAML-якорь, поэтому отдельно монтировать конфигурацию ему не нужно. Если compose-файл писался с нуля, том ./configuration:/etc/netbox/config:z,ro указывают обоим сервисам.

pull_policy: never нужен, чтобы compose не пытался скачать локальный образ из реестра.

Шаг 6. Сборка и запуск

docker compose build
docker compose up -d

Если базовый образ уже скачан, сборка занимает секунды: uv ставит три пакета — оба плагина и зависимость dnspython — и выполняет collectstatic. Когда что-то не сходится, сборку смотрят без свёрнутого вывода:

docker compose --progress plain build

После up -d контейнеры пересоздаются, и это правильно: docker restart не перечитывает ни конфигурацию, ни переменные окружения.

Шаг 7. Миграции

Плагину с моделями нужны таблицы. Entrypoint netbox-docker применяет миграции при старте, но лучше выполнить их явно и увидеть результат:

docker compose exec netbox /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py migrate

Для наших двух плагинов это 50 миграций: 35 у NetBox DNS и 15 у Topology Views. Повторный запуск должен ответить «No migrations to apply».

Не запускайте migrate одновременно со стартом контейнера. Я поймал именно эту ошибку: entrypoint ещё применял миграции, вторая команда пошла параллельно, и транзакция упала с «duplicate key value violates unique constraint netbox_dns_view_name_key» на служебном виде _default_. Лечится ожиданием: дождитесь статуса healthy и только потом запускайте migrate.

Шаг 8. Проверяем результат

Самый быстрый способ убедиться, что плагины загружены, — страница «Система → Плагины» (/core/plugins/): видны имя, автор, флаги «Локальный» и «Активный», установленная версия.

Список установленных плагинов NetBox с версиями — Оба плагина активны: NetBox DNS 1.7.3 и Topology Views 5.0.2

В левом меню появились два новых раздела — Topology Views и DNS. Значит, конфигурация подхватилась и приложения зарегистрировались в системе.

Первый плагин рисует карту по кабелям. На стенде семь устройств соединены семью кабелями, координаты узлов сохранены через «Device Coordinates» — поэтому карта открывается сразу, без перетаскивания мышью:

Карта топологии сети, построенная плагином Topology Views — Карта топологии: узлы — устройства, линии — кабели, заведённые в NetBox

Второй плагин добавляет собственные сущности. Проверяем на двух зонах — example.com и lab.example.com, по шесть записей в основной зоне:

Список DNS-зон в плагине NetBox DNS — Зоны DNS: данные хранятся в таблицах плагина, отдельно от стандартных моделей

Записи DNS-зоны example.com: A, CNAME, MX и TXT — Записи зоны example.com: A, CNAME, MX и TXT — типы проверяются при вводе

Обратите внимание: записи лежат не в стандартных моделях NetBox, а в собственных таблицах плагина. Поэтому при удалении плагина они не исчезнут, а при повторной установке подхватятся.

Шаг 9. Обновление и удаление

Обновление — это всегда пересборка образа, никаких действий внутри контейнера:

# правим версию в plugin_requirements.txt, затем
docker compose build
docker compose up -d
docker compose exec netbox /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py migrate

При обновлении самого NetBox порядок другой: сначала проверяем, поддерживает ли плагин новую версию, затем меняем VERSION в окружении, и только потом трогаем плагины. Если плагин отстал, его временно убирают из PLUGINS и plugin_requirements.txt, иначе контейнер не стартует.

Удаление — обратный порядок: убрать приложение из PLUGINS, убрать пакет из plugin_requirements.txt, пересобрать образ и пересоздать контейнеры. Таблицы плагина в базе останутся: их удаляют вручную, только если данные точно не нужны.

Типичные проблемы

«Unable to import plugin … Module not found» — в PLUGINS указано имя пакета вместо модуля (netbox-plugin-dns вместо netbox_dns) либо образ собран без пакета. Проверять по странице «Плагины».
«No module named pip» при сборке — в образе 5.x нет pip, установка выполняется через uv.
Плагин в списке есть, разделов в меню нет — контейнер не пересоздан после правки PLUGINS или каталог configuration не смонтирован в /etc/netbox/config.
Пустая карта топологии или нет иконок — не выполнен collectstatic либо не создан каталог static/netbox_topology_views/img.
IntegrityError duplicate key при migrate — миграции запущены параллельно со стартом контейнера; дождаться healthy и повторить.
Ошибка про минимальную версию NetBox — версия плагина не совпадает с версией NetBox; сверять по таблице совместимости в README плагина.
После обновления статики видны старые стили — кэш браузера, помогает жёсткая перезагрузка.

Итог

Установка любого плагина в Docker-развёрнутом NetBox сводится к четырём движениям: пакет с пином версии в plugin_requirements.txt, установка через uv в своём Dockerfile, включение приложения в PLUGINS и пересборка образа с последующими migrate. Всё, что добавляет плагин, дальше живёт по правилам самого NetBox — права, теги, журнал изменений, API.

Если NetBox ещё не развёрнут, начните с пошагового руководства «Как развернуть NetBox 4.7.5 на чистом сервере Linux в Docker»: в нём подготовка сервера, установка Docker, настройка окружения, первый вход, резервное копирование и HTTPS. Плагины ставятся уже поверх готового стенда.