Добавил порты в Device Type NetBox: почему они не появились у уже созданных устройств

Добавили интерфейсы или консольные порты в Device Type, а у существующих устройств NetBox их как не было, так и нет? Это ожидаемое поведение: шаблон применяется к устройству только в момент его создания. Ниже — почему так сделано, как быстро добить компоненты пачкой и как я это чиню в проектах.

Почему изменения Device Type не долетают до уже созданных устройств

Классическая ситуация при внедрении NetBox: завели Device Type для стоечного коммутатора, вписали 24 интерфейса, создали по нему полсотни устройств — и только потом заметили, что забыли консольный порт и порт питания. Добавляете их в Device Type, открываете любое из полусотни уже созданных устройств — а там как было 24 интерфейса, так и осталось. Ни консоли, ни power port. Первая мысль — что-то не сохранилось или нужно обновить страницу. Нет, сохранилось всё правильно.

Документация NetBox описывает это прямо: устройство наследует компоненты своего Device Type в момент создания, а последующие изменения самого Device Type к уже существующим экземплярам задним числом не применяются. DeviceType — это шаблон компонентов (интерфейсов, консольных портов, силовых портов, модульных отсеков и т.д.), по которому NetBox генерирует конкретные объекты для конкретного Device ровно один раз, при его создании. После этого связь чисто справочная: устройство помнит, по какому типу оно создано, но не подписано на его будущие изменения.

Это осознанное архитектурное решение, а не недоработка. В обсуждении #8189 на GitHub автор запроса сам перечислял подводные камни автосинхронизации: что делать, если интерфейс удалили из шаблона, и что делать, если такой же компонент уже вручную добавлен на устройство. Ведущий разработчик NetBox Джереми Стретч ответил там же: чтобы добавить интерфейсы существующим устройствам, достаточно отфильтровать их по типу, выделить и выполнить Add components — так вы получаете нужный результат «без неприятных сюрпризов». Логика понятна: синхронизация, которая умеет не только добавлять, но и удалять или переименовывать, рано или поздно снесёт ручные правки на конкретном устройстве — например, нестандартный интерфейс, добавленный при апгрейде железа. Я проверял release notes NetBox вплоть до актуальной 4.7.1 (15 сентября 2026) — функции автосинхронизации компонентов устройства с шаблоном там как не было, так и нет.

• Компоненты создаются у Device один раз — в момент создания по Device Type.
• Правки Device Type после этого момента не переносятся на уже существующие устройства.
• Это намеренное поведение: против случайного удаления ручных правок на устройстве.
• В NetBox 4.7.1 автосинхронизации компонентов всё ещё нет — недостающее добавляют вручную или скриптом.

Как отличить «шаблон не применился» от других причин пустых портов

Прежде чем чинить, я исключаю соседние причины — иначе легко потратить час на скрипт, который решает не ту проблему. Первое, что проверяю: действительно ли устройство создано именно по этому Device Type, а не по похожему с другим именем модели. В крупных инсталляциях с десятками производителей это встречается регулярно — завели «Cisco Catalyst 2960X-24TS-L» и «Cisco Catalyst 2960X-24TD-L» как отдельные типы, поправили не тот.

Второе — права доступа. Если интерфейсы не видны конкретному пользователю, но видны администратору, дело не в шаблоне, а в permissions constraints NetBox: у роли может быть ограничение на объекты dcim.interface по сайту или тенанту, и часть портов просто не проходит фильтр. Это лечится в разделе прав, а не пересозданием компонентов. У «ПерсоналДвор», например, инженеру второго офиса изначально выдали роль с constraint по своему сайту — и когда он смотрел устройство из первого офиса, видел его карточку, но список интерфейсов был пуст. Не имеет отношения к Device Type вообще, просто не тот доступ.

Третье — я смотрю не на страницу устройства в UI, а прямо в API: GET /api/dcim/devices/<id>/ и отдельно GET /api/dcim/interfaces/?device_id=<id>. Если в API компонентов действительно меньше, чем в шаблоне Device Type — значит, дело в том самом «не применилось задним числом», и дальше работаю по плану ниже. Если в API всё есть, а в UI не видно — ищу проблему в правах или в фильтрах страницы.

Ещё один источник путаницы — модульные устройства. Если Device Type использует module bays, а не плоский список интерфейсов, то часть портов приходит не из interface-templates самого Device Type, а из отдельного Device Type для модуля, вставленного в этот bay. Правка «родительского» Device Type в этом случае вообще не должна добавлять порты модуля — их нужно добавлять правкой Device Type самого модуля, и это отдельная, более редкая причина «порты не появились», которую я тоже сначала исключаю.

Похожая по духу ловушка «старое значение пережило обновление» встречается и в других системах, не только в NetBox — например, разбирал случай, когда image volume в Kubernetes продолжал показывать старые данные после перезаписи тега с той же самой сутью: закешированное состояние не подписано на изменения источника и не обновляется само.

• Проверить, что устройство действительно создано по исправленному Device Type, а не по соседнему похожему типу.
• Проверить permissions constraints роли — не режут ли доступ к dcim.interface по сайту/тенанту.
• Сверить состав компонентов через API (`/api/dcim/interfaces/?device_id=`), а не только через UI.
• Для модульных устройств проверить, не относятся ли недостающие порты к Device Type самого модуля, а не родителя.

Быстрый способ: массовое добавление компонентов через веб-интерфейс

Для разовой правки на десятках устройств NetBox предлагает встроенный путь без скриптов. Мейнтейнеры в обсуждении #8189 на GitHub описали его коротко: отфильтровать список устройств по нужному типу, выделить их и выполнить массовое действие Add components → Interfaces (аналогично есть Console Ports, Power Ports, Console Server Ports, Power Outlets, Device Bays, Module Bays). Это официально рекомендованный способ добить компоненты, которых не хватает у уже созданных устройств, — я использую его в первую очередь для простых случаев.

Порядок действий такой: захожу в Devices, в фильтре Device Type выбираю нужную модель, добавляю к фильтру нужный сайт или роль, если правлю не весь парк сразу, отмечаю галками нужные устройства (или все через шапку таблицы), в выпадающем меню действий выбираю Add Components → Interfaces. Дальше открывается форма, в которой можно задать имя, тип интерфейса, задать сразу диапазон имён через буквенно-цифровые диапазоны в квадратных скобках (например, GigabitEthernet1/0/[25-28]) — тот же синтаксис, что в обычной форме создания компонентов, только применённый сразу к выделенным устройствам.

У этого способа есть ограничение, о котором я всегда предупреждаю клиента: форма bulk-добавления не сверяется с текущим содержимым Device Type построчно, она просто создаёт компоненты по введённым вами параметрам. Дублей с одинаковым именем она не наплодит — в NetBox имя компонента уникально в пределах устройства (ограничение на пару device + name), и на устройствах, где такое имя уже есть, форма вернёт ошибку валидации. Но разбираться потом, где компонент создан, а где форма споткнулась, на сотне устройств неудобно, а опечатка в имени («Gi1/0/25» вместо «GigabitEthernet1/0/25») как раз создаст «почти дубль», который уникальность не ловит. Поэтому для повторяемых операций и больших парков я перехожу на скрипт, который сравнивает шаблон с фактом и добавляет только то, чего не хватает.

Ещё один нюанс bulk-формы — диапазоны. Если у Device Type интерфейсы называются GigabitEthernet1/0/1 … GigabitEthernet1/0/24, форма Add Components принимает запись GigabitEthernet1/0/[1-24] и создаёт весь диапазон одной операцией. Но если хотя бы часть выделенных устройств уже имеет один-два интерфейса с такими именами (частичное совпадение — типичная ситуация, если кто-то раньше добавлял их вручную по одному), на этих устройствах вы получите ошибку уникальности имени, и результат операции придётся перепроверять по каждому устройству. В таких смешанных случаях я либо сужаю выделение до устройств без совпадений, либо сразу иду в скрипт из следующего раздела.

• Devices → фильтр по Device Type (и, если нужно, по сайту/роли).
• Выделить нужные устройства (или все через шапку таблицы).
• Меню массовых действий → Add Components → Interfaces / Console Ports / Power Ports.
• Заполнить параметры (имя, тип, нумерация) и подтвердить.

Идемпотентный способ: добавить только недостающее через API

Когда правка Device Type происходит не один раз, а становится регулярной практикой (у нас так на крупных парках — раз в квартал добавляются недостающие типы портов по мере обнаружения пробелов), я использую скрипт поверх REST API NetBox, который сравнивает шаблон Device Type с фактическими компонентами устройства и добавляет только разницу. Это тот же подход, который участник сообщества выложил в обсуждении #8189: отчёт, подсвечивающий недостающие компоненты, и скрипт, добавляющий их всем устройствам. Его скрипт запускается из командной строки, не удаляет существующие компоненты и не меняет компоненты с тем же именем — значит, безопасен для повторного запуска.

Логика простая: забираю список шаблонов интерфейсов по device_type (/api/dcim/interface-templates/?device_type_id=), забираю фактические интерфейсы устройства (/api/dcim/interfaces/?device_id=), нахожу имена шаблонов, которых нет среди фактических интерфейсов, и создаю только их через POST /api/dcim/interfaces/. То же самое отдельно для console-port-templates, power-port-templates и так далее — под каждый тип компонента своя пара эндпоинтов template/фактический объект.

На практике я оформляю такую сверку как NetBox custom script (раздел Scripts в самом NetBox): он выполняется внутри приложения и работает через ORM, поэтому отдельный API-токен не нужен, а изменения проходят через тот же журнал изменений (changelog), что и ручные правки в UI, и их видно в истории объекта. Вариант через REST API с токеном оставляю для запуска извне — из CI или с машины инженера.

Тело запроса на создание интерфейса минимальное — device, name, type обязательны, остальное (mgmt_only, enabled, описание) беру из шаблона, если оно там задано:

curl -s -X POST https://netbox.example.com/api/dcim/interfaces/ \
  -H "Authorization: Token $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device": 142, "name": "GigabitEthernet1/0/25", "type": "1000base-t"}'

Для консольных и силовых портов эндпоинты и тип объекта другие — /api/dcim/console-ports/ с type: rj-45 и /api/dcim/power-ports/ с type: iec-60320-c14 (значения зависят от паспорта конкретной модели), но логика сравнения «шаблон минус факт» та же самая. Я держу этот скрипт в общем репозитории интеграций и переиспользую его между проектами — донастройка под конкретного клиента обычно ограничивается токеном и списком типов компонентов, которые нужно сверить.

• GET `/api/dcim/interface-templates/?device_type_id=<id>` — что должно быть по шаблону.
• GET `/api/dcim/interfaces/?device_id=<id>` — что есть по факту.
• Разница по именам → создать только недостающие через POST.
• Повторить для console-port-templates, power-port-templates, device-bay-templates.

Кейс: «ПерсоналДвор», 31 рабочее место — 14 коммутаторов без консольных портов в модели

У кадрового консалтинга «ПерсоналДвор» (31 рабочее место, два офиса) мы внедряли NetBox под инвентаризацию сети примерно за полгода до этого случая: завели площадки, стойки, 20 устройств, из них 14 — коммутаторы доступа одной модели, под которую сделали отдельный Device Type. Изначально в шаблон занесли только Ethernet-интерфейсы — 24 порта, без консольного и без power-порта, потому что на старте документации для консоли и питания просто использовали общую таблицу в Excel, отдельную от NetBox.

Через полгода, когда я собирал схему подключений для проекта резервного канала, обнаружилось, что в NetBox нет ни одного консольного порта ни у одного коммутатора этой модели — а это 14 устройств из 20 в инвентаре. Отредактировали Device Type, добавили Console Port (RJ-45) и Power Port по паспорту модели. Проверил одно устройство — компонентов не прибавилось. Ожидаемо, уже знал механику, но для заказчика это был неприятный момент: «мы же только что всё поправили».

Сделал так: сначала через фильтр Devices по этому Device Type выделил все 14 устройств и одним Add Components добавил Console Ports с именем «Console» — заняло около 5 минут вместе с проверкой формы. Power Port добавил отдельным прогоном тем же способом, ещё 3 минуты. После этого сверил через API количество компонентов каждого типа по всем 14 устройствам — совпало с шаблоном один в один. Итог: коммутаторы задокументированы полностью, план резервного канала пересчитан по актуальным консольным подключениям, и я завёл заказчику простое правило на будущее — см. следующий раздел.

Дальше в NetBox добавили ещё один Device Type для второго офиса «ПерсоналДвор» и делали то же самое сразу правильно: сначала полный паспорт устройства со всеми типами портов, потом создание устройств — повторно чинить задним числом не пришлось. Для самого проекта внедрения NetBox под документацию сети это был не первый и не последний подобный урок про порядок заполнения шаблонов.

• 14 из 20 устройств в инвентаре — коммутаторы без консольного и силового порта в модели.
• Правка Device Type: +Console Port, +Power Port по паспорту модели.
• Add Components на 14 устройствах — Console Port: ~5 минут, Power Port: ~3 минуты.
• Сверка через API: состав компонентов совпал с шаблоном по всем 14 устройствам.

Как я теперь веду жизненный цикл Device Type, чтобы не чинить задним числом

После пары таких историй у разных клиентов я поменял порядок работы с Device Type в проектах внедрения NetBox. Главное правило: полный паспорт устройства — все типы портов, module bays, если модель модульная, — собираю до того, как по этому Device Type создано хотя бы одно устройство. Источник — официальный datasheet производителя, а не то, что «пока нужно». Добавить лишний неиспользуемый интерфейс в шаблон почти ничего не стоит, а досоздавать компоненты задним числом на живом парке — отдельная операция с риском дублей.

Второе правило — если Device Type всё же приходится редактировать после того, как по нему уже есть устройства, эта правка сразу сопровождается задачей «добить компоненты» с конкретным списком device_id, а не остаётся в состоянии «когда-нибудь потом». На практике «потом» означает, что через год кто-то откроет устройство, увидит нестыковку и снова примет её за баг NetBox.

Третье — для парков больше 20–30 устройств одного типа я сразу использую скриптовый идемпотентный способ, а не bulk-форму в UI: он безопасен для повторного запуска, если правку приходится делать в несколько заходов (например, сначала по одному офису, потом по второму, или пока часть моделей ещё сверяется с паспортом). Тот же принцип «состояние выглядит финальным, а на деле процесс не завершён» я разбирал и на другом кейсе — Stop publishing после Instant Recovery в Veeam тоже не значит «восстановление закончено», пока не проверены все промежуточные шаги.

• Полный паспорт устройства по datasheet — до создания первого Device по этому типу.
• Каждая правка существующего Device Type — сразу с задачей «добить компоненты», а не «когда-нибудь».
• Для парков от ~20 устройств — идемпотентный скрипт вместо ручной bulk-формы.

Частые вопросы