Можно ли привязать VM к одиночному гипервизору в NetBox 4.6 без кластера из одного сервера

Да, начиная с NetBox 4.6 виртуальную машину можно назначить напрямую на Device без создания Cluster — этого не хватало годами, и решали костылём: фиктивным кластером на один хост. Разбираю, что изменилось в модели VirtualMachine, какие правила валидации действуют для site/cluster/device и стоит ли переводить старые фиктивные кластеры на прямую привязку.

Симптом: NetBox требует Cluster там, где кластера физически нет

Ситуация типовая для небольшой инфраструктуры: один физический сервер, на нём десяток виртуальных машин под VMware ESXi или Proxmox VE, никакого отказоустойчивого пула хостов нет и не планируется. Когда доходит до внедрения NetBox как единого источника правды по инфраструктуре, администратор создаёт объект VirtualMachine и упирается в модель размещения. В версиях до 4.6 у VM было два честных варианта: указать Site или указать Cluster. Поле Device у виртуальной машины существует давно, ещё с NetBox 3.3, но до 4.6 оно работало только как закрепление VM за конкретным хостом внутри кластера — без кластера сохранить device было нельзя. Указать голый Site можно, но тогда VM формально не привязана ни к какому физическому серверу, и в карточке сервера при аварии не видно, что на нём было.

Первая реакция — завести Cluster Type вроде «single-host» и создать по кластеру на каждый одиночный сервер, чтобы формально удовлетворить модель данных. Работает, но раздражает: в базе появляются кластеры, которые кластерами не являются ни по смыслу, ни по факту, а при экспорте отчётов и построении топологии их приходится держать в голове как исключение. Вопрос, который я слышу регулярно: это баг, недоработка модели или так и задумано — и существует ли способ обойтись без фиктивного кластера.

Как эту проблему решали до NetBox 4.6 — и почему это был именно костыль

До версии 4.6 модель VirtualMachine требовала Site или Cluster, а поле device (добавленное в 3.3) принималось только в паре с кластером: прямой привязки «VM → Device» без промежуточного Cluster не существовало. В официальном обсуждении на GitHub (Discussions #9655, вопрос про документирование Docker-контейнеров) сообщество предлагало ровно тот обходной путь, с которым сталкивается любой администратор одиночного гипервизора: «create separate 'clusters' each containing a single host. Create a cluster type of docker» — то есть завести отдельный Cluster Type под сценарий и создавать по кластеру на каждый одиночный хост, даже если реального кластера нет.

Решение рабочее, но с двумя минусами. Первый — семантический шум: в списке кластеров NetBox начинают жить объекты, которые не выполняют функцию кластера (нет распределения нагрузки, нет миграции между хостами, нет отказоустойчивости) — это путает и новых сотрудников, и интеграции, которые опираются на Cluster как на признак «группы хостов». Второй — лишний уровень косвенности при автоматизации: скрипты и отчёты, которые ищут физический сервер под VM, вынуждены идти через Cluster → Device вместо прямой связи VM → Device, и любой велосипед, который сериализует эту цепочку, приходится содержать отдельно от штатной модели.

Что изменилось в NetBox 4.6: прямая привязка VM к Device

В релизе NetBox 4.6.0 (вышел 5 мая 2026 года) это ограничение сняли. В официальных release notes указан пункт enhancement #12024 — «Permit virtual machines to be assigned to devices without a cluster» (разрешить назначение виртуальных машин на устройства без кластера). В анонсирующем блоге NetBox Labs эта возможность прямо перечислена среди изменений модели инфраструктуры версии 4.6 наравне с Cable Bundles, Rack Groups и Virtual Machine Types — формулировка там ровно такая: «VMs assignable directly to devices without an intervening cluster».

Официальная документация модели VirtualMachine описывает актуальные правила размещения так: у VM должно быть указано хотя бы одно из трёх — site, cluster или device. Это даёт четыре законные комбинации: только Site (VM существует на площадке без привязки к железу или кластеру), только Cluster (сайт при этом определяется автоматически по кластеру), только Device — «VM runs directly on a physical host device without a cluster (e.g. containers)», и Cluster + Device одновременно, когда VM закреплена за конкретным хостом внутри кластера. Именно третий вариант и закрывает исходный вопрос: одиночный гипервизор без всякого кластера теперь может быть местом размещения VM напрямую.

Правила валидации: что проверяет NetBox при связке device и cluster

Если задать VM одновременно и cluster, и device, NetBox накладывает согласованность: устройство обязано быть зарегистрированным хостом именно того кластера, что указан у VM. Указать device из одного кластера, а cluster — от другого, не получится: такая комбинация не проходит валидацию. Это логично — device в контексте виртуализации сам является членом Cluster через поле Device.cluster, и NetBox не разрешает VM ссылаться на несовместимую пару.

Есть и обратное правило, о котором документация модели прямо не пишет, но которое видно в коде проверки VirtualMachine: прямое назначение на Device предназначено только для отдельно стоящих хостов. Если у выбранного устройства заполнено собственное поле Cluster, NetBox откажет в сохранении VM «только с device» с ошибкой вида «Must specify the assigned device's cluster…» — то есть потребует указать и кластер этого устройства. Именно здесь спотыкаются при миграции со старых кластеров-заглушек: сервер по-прежнему числится членом фиктивного кластера, и перенос VM на прямую привязку не проходит, пока сам Device из кластера не выведен. Плюс проверка площадки: если у VM явно указан Site, а устройство стоит на другой площадке, сохранение тоже будет отклонено.

Ещё одно последствие смены модели размещения — правила уникальности имени VM (сравнение имён, кстати, без учёта регистра: ERP-APP-01 и erp-app-01 в одном контексте не уживутся). Для VM, привязанной к Cluster, имя должно быть уникальным в пределах связки cluster + tenant (как и раньше). А для VM, назначенной напрямую на Device без кластера, уникальность считается в пределах связки device + tenant. То есть на двух разных одиночных гипервизорах в одном арендаторе (tenant) вполне может существовать по VM с одинаковым именем — NetBox не станет на это ругаться, в отличие от ситуации внутри одного и того же кластера или одного и того же device.

Как назначить VM на Device напрямую: интерфейс и REST API

В веб-интерфейсе после обновления до 4.6 или новее при создании или редактировании VirtualMachine в блоке размещения появляется отдельное поле Device — заполнять его можно независимо от Cluster. Если оставить Cluster пустым и указать только Device, площадка (Site) подставится автоматически по площадке этого устройства — отдельно её указывать не нужно, хотя явное указание Site тоже не запрещено и не мешает валидации.

Через REST API (POST /api/virtualization/virtual-machines/) это делается передачей device вместо cluster в теле запроса:

curl -s -X POST https://netbox.example.com/api/virtualization/virtual-machines/ \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp-app-01",
    "status": "active",
    "device": 42,
    "vcpus": 4,
    "memory": 8192,
    "disk": 120
  }'

Заголовок Authorization: Bearer — формат токенов v2, которые появились в NetBox 4.5; устаревший Authorization: Token для v1-токенов в 4.6–4.7 ещё работает, но его поддержку уберут в 5.0. ID устройства (42 в примере) должен указывать на уже существующий объект Device — например, тот самый одиночный сервер, заведённый в DCIM, причём не состоящий ни в одном кластере. Если параллельно нужно указать и кластер, добавляется поле cluster с ID кластера, членом которого это устройство зарегистрировано — иначе запрос отклонится по описанному выше правилу согласованности.

Для массового переноса существующих VM с фиктивного кластера на прямую привязку к Device порядок важен. Сначала выгрузите список VM конкретного фиктивного кластера через фильтр ?cluster_id=, чтобы не упустить объекты, у которых кластер использовался ещё и как метка группировки в отчётах. Затем выведите сам сервер из кластера — PATCH /api/dcim/devices/42/ с телом {"cluster": null}: пока Device числится членом кластера, VM «только с device» не сохранится по правилу из предыдущего раздела. И только после этого переносите сами VM тем же эндпоинтом виртуальных машин с методом PATCH: cluster обнуляется, device проставляется явно. Опустевший кластер-заглушку удаляете последним.

В виде команд для одного сервера и двух его VM это выглядит так (эндпоинт списка принимает PATCH с массивом объектов, у каждого указан id):

# 1. Сервер выходит из фиктивного кластера
curl -s -X PATCH https://netbox.example.com/api/dcim/devices/42/ \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cluster": null}'

# 2. VM переезжают на прямую привязку к устройству
curl -s -X PATCH https://netbox.example.com/api/virtualization/virtual-machines/ \
  -H "Authorization: Bearer $NETBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"id": 101, "cluster": null, "device": 42},
       {"id": 102, "cluster": null, "device": 42}]'

Массовая операция в REST API выполняется по принципу «всё или ничего»: если хотя бы одна VM не проходит проверку — например, забыли вывести из кластера её сервер, — не применится ни одна правка, и ответ укажет, какой объект виноват. Мне так даже удобнее: половинчатого состояния, когда часть VM уже на Device, а часть ещё на заглушке, не возникает.

Кейс «Старина и стиль»: один сервер и NAS, а в NetBox — два «кластера»

Клиент — антикварный магазин «Старина и стиль», 37 рабочих мест, инфраструктура собрана вокруг единственного физического сервера под Proxmox VE: 1С, файловый сервер, внутренний каталог с фотографиями и описаниями лотов для оценщиков, контроллер домена. Никакого второго хоста нет и в обозримом будущем не планируется — весь смысл в компактности. Когда мы разворачивали NetBox для документирования этой инфраструктуры (тот же проект, что описан в нашей статье про порядок в учёте против 12 Excel-файлов), NetBox на тот момент был версии 4.4 — поле Device у VirtualMachine уже было, но без кластера его сохранить не давали.

Завели по инструкции, актуальной для того релиза: Cluster Type «single-host» и два кластера-заглушки — один под основной сервер Proxmox VE с семью виртуальными машинами, второй под NAS, на котором крутятся два Docker-контейнера (сервис резервного копирования и внутренний каталог лотов с фотографиями), тоже промаркированные как VM. В отчётах и на дашборде эти «кластеры» из одного хоста каждый визуально ничем не отличались от настоящих кластеров на других клиентских проектах — путаница при передаче инфраструктуры новому инженеру возникла в первую же неделю: он потратил время, разбираясь, почему у «кластера» нет второго узла и куда мигрируют машины при отказе.

После обновления клиентского инстанса NetBox до 4.6 мы пересмотрели эту схему. Первая попытка переназначить VM на Device предсказуемо упала с ошибкой про кластер устройства: и сервер, и NAS всё ещё числились членами своих заглушек. Порядок поправили — сначала вывели оба устройства из кластеров, потом одним массовым PATCH перенесли все 9 объектов (7 VM и 2 контейнера) на прямую привязку к Device, затем удалили пустые кластеры и сам Cluster Type «single-host». Раздел Clusters в NetBox опустел полностью — настоящих многоузловых кластеров у клиента нет, — а вся топология стала на один уровень косвенности проще. На перенос ушло около часа, включая сверку, что после PATCH у каждой VM осталась верная площадка и что вкладка виртуальных машин в карточке сервера показывает все семь.

Что проверить после переноса: отчёты, фильтры и синхронизация

Сам перенос — полдела. Всё, что раньше опиралось на кластер как на «группу машин этого сервера», теперь нужно перевести на устройство. В REST API список VM конкретного хоста берётся фильтром ?device_id=42 — он существует давно и работает одинаково для VM с кластером и без него, так что я сразу переписываю скрипты и экспортные шаблоны на него, а не на cluster_id. В интерфейсе у устройства есть вкладка со списком размещённых на нём виртуальных машин: именно её я открываю при разборе аварии хоста, чтобы за минуту понять, какие сервисы пострадали.

Второе — внешние интеграции. Если NetBox наполняется автоматически из гипервизора (собственным скриптом, плагином синхронизации или импортом CSV), проверьте, что именно они создают для одиночного хоста: многие инструменты по привычке заводят кластер под каждый хост и после ближайшего прогона вернут заглушку обратно. Здесь нет универсального ответа — поведение зависит от конкретного плагина и его версии, так что я прогоняю синхронизацию на копии базы и смотрю, не появились ли снова кластеры. И последнее: если через год рядом появится второй сервер и настоящий кластер Proxmox, обратный переход прямой — создаёте Cluster, добавляете в него оба устройства и проставляете VM связку cluster + device.

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