Wszystko w tym wpisie zostało uruchomione na NetBox 4.7.2 na moim własnym biurku, z załadowaną prawdziwą infrastrukturą: jedna lokalizacja, jedna szafa, czternaście urządzeń, okablowanych, zasilonych i zaadresowanych dla trzech klientów. Każdy zrzut ekranu to ta instancja i każdy komunikat o błędzie to taki, który naprawdę dostałem.

Kolejność jest taka, w jakiej to spotkasz. Czym to jest, po co ci to, fork, o którym usłyszysz w ciągu tygodnia szukania, jak to postawić, w jakiej kolejności musisz to wypełnić, a potem co z tego dostajesz. Dostosowywanie i rozszerzanie jest na końcu, bo nic z tego nie ma sensu, dopóki nie zobaczysz kształtu tego, co rozszerzasz.

Czym jest NetBox

NetBox to baza danych z bardzo konkretnym zdaniem na temat tego, z czego składa się sieć, plus aplikacja webowa na wierzchu. To aplikacja Django na PostgreSQL, jest open source na licencji Apache 2.0 od czasu, gdy DigitalOcean wypuścił ją w czerwcu 2016, a dziś projektem opiekuje się NetBox Labs razem z zespołem wolontariuszy.12

Pod spodem to 149 modeli w dziesięciu aplikacjach, dostępnych przez 146 endpointów REST i jeden endpoint GraphQL. Policzone na instancji, którą do tego zbudowałem, a nie przepisane ze strony z funkcjami:

AplikacjaModeleAplikacjaModele
dcim56virtualization7
extras23tenancy6
ipam18wireless3
circuits11users7
vpn10core8

Pięćdziesiąt sześć z nich to DCIM, warstwa fizyczna: lokalizacje, pomieszczenia, szafy, typy urządzeń, urządzenia i każdy rodzaj portu, wnęki i zakończenia kabla, jaki urządzenie może mieć. Osiemnaście to IPAM. Reszta obejmuje łącza, tunele i polityki IKE, maszyny wirtualne i klastry, łącza bezprzewodowe, dzierżawców i mechanizmy, które sprawiają, że całość da się rozszerzać.

Liczba nie jest tu najważniejsza. Najważniejsze są powiązania, a najszybciej zobaczysz to na ekranie, z którego NetBox jest najbardziej znany.

Zacznij od szafy, bo to ekran, który sprzedaje całą rzecz.

Strona szczegółów szafy MCR1-A07 w NetBox, po lewej region North West, lokalizacja Manchester DC1, pomieszczenie Hall 2, status Active i zajętość miejsca 28,6%, po prawej widok z przodu i z tyłu z panelami krosowymi na U41 i U42, dwoma routerami na U38 i U39, dwoma przełącznikami na U35 i U36 oraz sześcioma hiperwizorami między U15 a U20, każde urządzenie pokolorowane według roli

Ten widok jest rysowany z danych, a nie wgrany. Każde urządzenie jest tam, bo coś mówi, że zajmuje te jednostki, od tej strony, a kolory biorą się z roli, którą mu nadałeś. Zajętość miejsca wynosi 28,6%, bo NetBox to policzył. Nikt tej liczby nie utrzymuje.

Wynikają z tego dwie rzeczy, które są warte więcej niż sam obrazek.

Możesz zapytać, które jednostki są wolne, i dostać odpowiedź, na podstawie której da się działać. Możesz też zarezerwować jednostki, zanim cokolwiek w nich zamontujesz, a to jest różnica między sprzedawaniem miejsca, które masz, a sprzedawaniem miejsca, które wydaje ci się, że masz.

Czego celowo nie robi

Produkt, który wie, czym nie jest, spotyka się rzadziej niż taki, który wszystko robi źle, a dokumentacja NetBoxa mówi o tym bez ogródek. Nie zapewnia monitoringu sieci, usługi DNS, RADIUS-a, zarządzania konfiguracją ani zarządzania obiektem.1

Co ważniejsze, przechowuje zamierzony stan twojej sieci, a nie jej stan operacyjny, a dokumentacja mówi, że automatyczny import żywego stanu sieci jest „strongly discouraged”, bo każdy rekord powinien najpierw sprawdzić człowiek.1

Na tej decyzji opiera się wszystko inne i to z nią ludzie się kłócą. Argument brzmi: przecież źródło prawdy powinno być prawdą, więc wykryj sieć i ją załaduj. Odpowiedź jest taka, że wykryta sieć mówi ci, co tam jest, a to, co tam jest, obejmuje każdy błąd, jaki ktokolwiek kiedykolwiek popełnił. Port przełącznika zostawiony w złym VLAN-ie w 2021 roku jest faktem. Nie jest zamiarem.

NetBox przechowuje zamiar. Twój monitoring przechowuje rzeczywistość. Ciekawą liczbą jest różnica między nimi, a różnicy nie policzysz z jednego wejścia.

Druga zasada jest wyrażona równie wprost: mając wybór między stosunkowo prostym rozwiązaniem na osiemdziesiąt procent a dużo bardziej złożonym kompletnym, wybierz to proste.1 Poczujesz to za pierwszym razem, gdy zechcesz zamodelować coś, czego on nie modeluje, a pod koniec jest cała seria rozdziałów o tym, co wtedy zrobić.

NetBox robiNetBox nie robi
Zapisuje, co powinno tam byćOdpytuje, co tam jest
Trzyma zamierzony VLAN dla portuMówi ci, że port leży
Mówi, do którego klienta należy prefiksWystawia mu za to fakturę
Renderuje konfigurację urządzenia z szablonuWgrywa ją na urządzenie
Śledzi łącze, dostawcę i zobowiązanieMonitoruje łącze
Mówi, w której szafie jest urządzenie i na którym UOtwiera szafę

Czytaj prawą kolumnę jako listę narzędzi, których wciąż potrzebujesz. Przeczytaj ją źle, a spróbujesz zrobić z NetBoxa je wszystkie, i tak właśnie źródło prawdy staje się kolejnym systemem, któremu nikt nie ufa.

Po co ci on

Zapytaj dostawcę usług zarządzanych, gdzie leży wiarygodny zapis sieci klienta, a dostaniesz odpowiedź. Zapytaj osobno dwóch jego inżynierów, a dostaniesz dwie.

Jeden wskaże arkusz kalkulacyjny. Drugi wskaże diagram ostatnio zapisany przez kogoś, kto odszedł w 2023. Ktoś jeszcze powie, że dokumentacją jest konfiguracja firewalla, co jest przynajmniej uczciwe, bo konfiguracja opisuje, co pudełko robi. Nie opisuje tylko, dlaczego, kto o to prosił ani który z czterech klientów za tym pudełkiem płaci za daną regułę.

Porażka nigdy nie przychodzi w dniu, w którym zauważasz, że zapis jest błędny. Przychodzi w dniu, w którym ktoś go potrzebuje.

MomentCo musisz pokazaćIle kosztuje, gdy nie możesz
Rozmowa o przedłużeniu umowyRozpisane, co kupuje miesięczna opłataOferta konkurencji jest rozpisana, bo oni poszli i policzyli
Inżynier składa wypowiedzenieWszystko, co wiedział, spisanePół roku dowiadywania się, zgłoszenie po zgłoszeniu
Klient odchodziOpis jego własnej infrastrukturyTrzy tygodnie składania tego w całość i referencje, których udzieli szczerze
Audytor pyta o zakresKtóre systemy przechowują dane osobowe i gdzie fizycznie stojąRegulator, któremu powiedziano coś, co później okazuje się nieprawdą
Migrację trzeba wycenićLiczba tego, co naprawdę tam jestLicytujesz na podstawie szacunku i pokrywasz różnicę z własnej kieszeni

Nic z tego nie jest egzotyczne. To zwykły wtorek.

To, co z tego dostajesz, nie jest dokumentacją. Dokumentacja to coś, co piszesz, a potem przestajesz utrzymywać. Dostajesz bazę danych, która odmawia przechowania sprzeczności i która odpowiada na pytania, których nikt wcześniej nie pomyślał jej zadać. Dalej w tym wpisie jest szafa, która okazuje się zapełniona w 28,6 procent sprzętem i w 90,7 procent mocą. Nikt nie wyruszył, żeby to znaleźć. Wypadło to z jednorazowego wpisania mocy na typie urządzenia.

Razem z tym przychodzi uczciwe zastrzeżenie i o nim jest ostatni rozdział. Zapis jest wart tyle, ile kosztuje cię utrzymanie go w poprawności. Ale alternatywą jest firma, która nie potrafi opisać samej siebie, a pierwszą osobą, która się o tym dowiaduje, jest zwykle klient.

Ten drugi: Nautobot

Natkniesz się na niego mniej więcej w ciągu tygodnia szukania, więc warto wiedzieć, co się stało.

W 2021 roku Network to Code zrobił fork NetBoxa i nazwał wynik Nautobot. Nie miękki fork ani dystrybucja: twardy fork, który rozchodzi się od pięciu lat. Jego własne notatki do wydania v1.0 opisują go jako „a divergent fork of NetBox 2.10”, repozytorium powstało 19 lutego 2021, a v1.0.0 wyszło 26 kwietnia 2021.3

Podane przez nich powody są na ich własnym blogu i warto je przeczytać ich słowami, a nie moimi. Kierowały nimi trzy rzeczy. Chcieli sprzedawać wsparcie dla firm: „We need to offer high-touch support models with Service Level Agreements (SLAs) we can guarantee. We need flexibility to offer Long-term Support (LTS) for customers who can’t upgrade at the pace of a fast moving open source project.” Chcieli, żeby źródło prawdy było w centrum platformy automatyzacji, zamiast służyć dokumentacji. I „there became a growing divergence in our vision about what a Source of Truth for networking should look like and how to get there”.4

Ten pierwszy powód wymaga dopisania daty, bo przestał być prawdziwy. W lutym 2021 za NetBoxem nie stała żadna firma, która mogłaby ci cokolwiek sprzedać. NetBox Labs powstał dopiero w 2023 roku, wydzielony z NS1 po przejęciu tej firmy przez IBM, współzałożony przez głównego maintainera NetBoxa.5

I nie jest to ktoś z zewnątrz, kto zbudował biznes na cudzym projekcie. NetBox Labs jest opiekunem NetBoxa: dokumentacja projektu mówi „the open source project is stewarded by NetBox Labs and a team of volunteer maintainers”.1 Sprzedają NetBox Enterprise do instalacji we własnym zakresie, hostują go dla ciebie jako NetBox Cloud i oferują wsparcie 24/7.6

Więc „nie da się kupić wsparcia dla NetBoxa” było uczciwym stwierdzeniem, gdy Network to Code robił forka, a dziś uczciwe nie jest. Za oboma projektami stoi komercyjna firma, która coś podpisze, a w przypadku NetBoxa jest to firma, która opiekuje się projektem.

Zdanie, które większość ludzi przeocza, jest następne i to ono sprawia, że to nie jest brudna historia: „the NetBox project team suggested that we should consider forking.”

To mniej więcej tak cywilizowany fork, jak to tylko możliwe. Dwie grupy chciały różnych rzeczy, mówiły o tym przez długi czas i rozeszły się, zamiast walczyć o jeden kod. Obie połowy wciąż są na Apache 2.0. Nikt nie wziął niczego, do czego nie miał prawa.

Po co naprawdę był ten fork

Notatki do wydania Nautobot 1.0 wymieniają, co dodał względem NetBox 2.10, i ta lista opowiada spór lepiej niż jakikolwiek wpis na blogu:3

Co Nautobot dodał w 2021Gdzie jest teraz NetBox
Obsługa GraphQLNetBox ją ma
Integracja z Git jako źródło danychNetBox ją ma, jako synchronizowane źródła danych
Single sign-onNetBox go ma
SekretyNetBox je ma przez wtyczkę
Skrypty i raporty połączone w JobsNetBox w 4.7 przenosi skrypty do wtyczki
Pola własne na wszystkich modelachNetBox ma szeroką obsługę pól własnych
API wtyczek do walidacji danychNetBox ma własne reguły walidacji
Konfigurowalne statusy jako obiekty w bazieStatusy NetBoxa to wciąż zestaw wyborów w Pythonie
Relacje między modelami definiowane przez użytkownikaNetBox nie ma odpowiednika
Klucze główne UUIDNetBox używa kluczy całkowitych
Rozszerzenia API wtyczekFramework wtyczek NetBoxa bardzo od tego czasu urósł

Większość górnej połowy się zbiegła. Kilka rzeczy, które Nautobot wypuścił w 2021, trafiło później do NetBoxa, co zwykle się dzieje, gdy dwa projekty rozwiązują publicznie te same problemy.

Dolne trzy się nie zbiegły i są architektoniczne, a nie kosmetyczne. Sprawdziłem dziś oba kody źródłowe, zamiast ufać notatkom z 2021.

Status w Nautobocie to model bazodanowy, opisany w jego własnym kodzie jako „Model for database-backend enum choice objects”, więc status to wiersz, który ktoś może dodać w interfejsie. Statusy NetBoxa pochodzą z zestawu wyborów w Pythonie i dlatego rozdział FIELD_CHOICES dalej dodaje jeden przez edycję configuration.py i restart. Nautobot ma modele Relationship i RelationshipAssociation, więc relację między dwoma istniejącymi typami obiektów zdefiniujesz bez pisania kodu. Odpowiedzią NetBoxa na ten problem jest wtyczka, która dostaje własną serię rozdziałów dalej. A klucze główne Nautobota to UUID, podczas gdy w NetBoxie to liczby całkowite.

Zrobili też to, po co robili forka. Na dziś Nautobot wydaje 3.2.x i 2.4.x tego samego dnia, czyli prawdziwą linię długoterminowego utrzymania obok bieżącej, a to był jeden z trzech podanych powodów.

Który wybrać

Najpierw uczciwe liczby. NetBox ma 21 625 gwiazdek i 3133 forki; Nautobot ma 1617 i 422.7 Do obu coś wypchnięto w ciągu ostatnich dwóch dni, oba są na Apache 2.0 i za oboma stoi teraz komercyjna firma sprzedająca wsparcie i hosting.

Ta różnica nie jest werdyktem co do jakości. Odzwierciedla pięć lat przewagi na starcie i to, że większość ludzi szukających źródła prawdy najpierw trafia na NetBoxa. Ale rozstrzyga o tym, co zwykle liczy się bardziej niż funkcje, czyli ile wtyczek, integracji, modułów Ansible, odpowiedzi na forach i kolegów znajdziesz dla tego, który wybierzesz.

Więc: jeśli chcesz inwentarza i źródła prawdy, które czytają inne systemy, i chcesz największego ekosystemu i najłatwiejszej rekrutacji, odpowiedzią jest NetBox i o nim jest reszta tego wpisu. Jeśli powodem, dla którego chcesz źródła prawdy, jest konkretnie sterowanie z niego automatyzacją, albo chcesz, żeby statusy i relacje definiował twój zespół, a nie plik konfiguracyjny i restart, to porządnie przyjrzyj się Nautobotowi, zanim zdecydujesz.

Nie pozwól nikomu sprzedać ci żadnego z nich na samo wsparcie. Obie strony mają to teraz załatwione, a różnice, które nadal będą za pięć lat, to te z tabeli powyżej.

Czego nie powinieneś robić, to wybierać jednego dlatego, że ktoś ci powiedział, że drugi jest martwy. Żaden nie jest i oba wydały w tym tygodniu nowe wersje.

Jak go uruchomić

Dwie drogi i obie przeszedłem do tego wpisu. Kontenery, jeśli chcesz, żeby działał za dwadzieścia minut, pakiety na hoście, jeśli ma dźwigać prawdziwy ciężar.

Stos kontenerów

Społeczność utrzymuje netbox-docker, i to jest szybka odpowiedź:8

git clone -b release https://github.com/netbox-community/netbox-docker.git
cd netbox-docker
tee docker-compose.override.yml <<'EOF'
services:
  netbox:
    ports:
      - 8000:8080
EOF
docker compose pull
docker compose up

To daje ci aplikację, PostgreSQL, Redis i proces roboczy w tle, połączone ze sobą. Zbudowałem to samo ręcznie pod podmanem, żeby zobaczyć części, a części warto znać, bo dwie z nich łapią ludzi:

KontenerCo robiJeśli go pominiesz
netboxAplikacja Django za gunicornemnic nie działa
postgresBaza danych, 15 lub nowszanic nie działa
redis / valkeyDwie bazy: jedna na zadania, jedna na cachenic nie działa
netbox-workerrqworker, który opróżnia kolejkę zadańwebhooki nigdy się nie odpalają, zadania w tle nigdy się nie wykonują i nic cię o tym nie ostrzega
netbox-housekeepingOkresowe sprzątaniewpisy dziennika zmian nigdy nie wygasają

Ten czwarty wiersz jest najważniejszy. Bez procesu roboczego wszystko wygląda zdrowo. Reguły zdarzeń ustawiają się w kolejce i tam leżą.

Dwie rzeczy ugryzły mnie przy pierwszym uruchomieniu i żadnej nie ma w komunikacie o błędzie, którego mógłbyś szukać.

Pierwsza migracja trwa długo. Nie minutę. Na tej maszynie kilka, bo NetBox 4.7 zastępuje django-mptt PostgreSQL-owym ltree i po drodze przebudowuje każdą tabelę hierarchiczną. Kontener po prostu siedzi i nakłada migracje. Zostaw go w spokoju.

Bez API_TOKEN_PEPPERS nie utworzysz tokena API v2, a jedynym znakiem jest ostrzeżenie w logu:

UserWarning: API_TOKEN_PEPPERS is not defined. v2 API tokens cannot be used.

Ustaw co najmniej jeden, o długości co najmniej pięćdziesięciu znaków, zanim zaczniesz szukać, czemu API cię odrzuca.

Na hoście, z pakietów

Udokumentowana droga jest testowana na Ubuntu 24.04. Przeszedłem ją od początku do końca na czystej instalacji i skończyło się na tym:

KomponentCo dało mi 24.04Czego potrzebuje NetBox 4.7
PostgreSQL16.1515 lub nowszy
Redis7.0.156.0 lub nowszy
Python3.12.33.12, 3.13 lub 3.14
Django6.1.1przychodzi z NetBoxem
NetBoxv4.7.2

Te minima są NetBoxa, a 4.7 podniosła próg zarówno dla PostgreSQL, jak i dla Redisa.9

Cała robota to pięć kroków.

# 1. the services
sudo apt install -y postgresql redis-server
sudo -u postgres psql -c "CREATE DATABASE netbox;"
sudo -u postgres psql -c "CREATE USER netbox WITH PASSWORD 'something-you-generated';"
sudo -u postgres psql -c "ALTER DATABASE netbox OWNER TO netbox;"
sudo -u postgres psql -d netbox -c "GRANT CREATE ON SCHEMA public TO netbox;"

# 2. the build dependencies
sudo apt install -y python3 python3-pip python3-venv python3-dev build-essential   libxml2-dev libxslt1-dev libffi-dev libpq-dev libssl-dev zlib1g-dev git

# 3. the application, at a release tag rather than at main
sudo mkdir -p /opt/netbox && cd /opt/netbox
sudo git clone https://github.com/netbox-community/netbox.git .
sudo git checkout v4.7.2
sudo adduser --system --group netbox
sudo chown -R netbox /opt/netbox/netbox/media/ /opt/netbox/netbox/scripts/ /opt/netbox/netbox/reports/

# 4. the configuration: five values, no more
cd /opt/netbox/netbox/netbox/
sudo cp configuration_example.py configuration.py
python3 /opt/netbox/netbox/generate_secret_key.py   # run it twice
sudo $EDITOR configuration.py

# 5. let the upgrade script do the rest
sudo /opt/netbox/upgrade.sh

Te pięć wartości to ALLOWED_HOSTS, DATABASES, REDIS, SECRET_KEY i API_TOKEN_PEPPERS. Wygeneruj dwie ostatnie osobno i nie używaj jednej jako drugiej. Dlatego uruchom generator kluczy dwa razy i wklej wyniki w różne linie.

upgrade.sh buduje środowisko wirtualne, instaluje każdą zależność Pythona, wykonuje migracje, buduje dokumentację do użytku offline i zbiera pliki statyczne. Gdy skończy na świeżej maszynie, wypisuje ostrzeżenie, które wygląda groźnie, a groźne nie jest:

WARNING: No existing virtual environment was detected. A new one has
been created. Update your systemd service files to reflect the new
Python and gunicorn executables. (If this is a new installation,
this warning can be ignored.)

Potem superużytkownik i działa:

source /opt/netbox/venv/bin/activate
cd /opt/netbox/netbox && python3 manage.py createsuperuser

Do czegokolwiek prawdziwego postaw przed nim gunicorna zamiast runserver. Konfiguracja i pliki jednostek są już w repozytorium, i to jest szczegół warty uwagi, bo ludzie piszą własne:

sudo cp /opt/netbox/contrib/gunicorn.py /opt/netbox/gunicorn.py
sudo cp -v /opt/netbox/contrib/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now netbox netbox-rq

netbox.service uruchamia gunicorna na 127.0.0.1:8001, netbox-rq.service uruchamia proces roboczy, a nginx albo Apache idzie z przodu, żeby kończyć TLS i serwować /static. Dwie usługi, a druga to ten sam proces roboczy, którego potrzebuje stos kontenerów.

Kolejność, w jakiej musisz go wypełniać

Świeży NetBox to pusta baza danych z poglądami, a pierwszą godzinę z nim zwykle spędza się na odkrywaniu, jakie to poglądy. Idziesz dodać urządzenie, a on ci nie pozwala.

Formularz Add a new device w NetBox: pod nagłówkiem Device pola Name, Device role oznaczone czerwoną gwiazdką, Description i Tags, potem pod Hardware Device type również oznaczone czerwoną gwiazdką, a dalej Serial number, Asset tag, Cooling method i Airflow

Te czerwone gwiazdki to cała lekcja. NetBox nie zapisze rzeczy, zanim nie będą istnieć rzeczy, na których ona wisi, i nie robi tego na złość: urządzenie bez typu to wiersz, który nie odpowie na żadne z pytań, do których służy urządzenie.

Więc zamiast zgadywać, zapytałem model, które klucze obce są naprawdę obowiązkowe, a potem próbowałem złamać każdą regułę przez API, żeby zobaczyć, co wraca.

POST /api/dcim/device-types/   no manufacturer
  {"manufacturer": ["This field is required."]}
POST /api/dcim/devices/        no device type
  {"device_type": ["This field is required."]}
POST /api/dcim/interfaces/     no device
  {"device": ["This field is required."]}
POST /api/ipam/aggregates/     no RIR
  {"rir": ["This field is required."]}
POST /api/circuits/circuits/   no provider, no type
  {"provider": ["This field is required."], "type": ["This field is required."]}
POST /api/virtualization/virtual-machines/   nothing at all
  {"__all__": ["A virtual machine must be assigned to a site, cluster, or device."]}

Każda próba odrzucona, z dokładną informacją, czego brakuje. Oto te same informacje jako lista warunków wstępnych:

Żeby utworzyćNajpierw wymaganeOpcjonalne, ale chcesz to mieć wcześniej
TenantnicTenant group
Region, Site groupnicrodzic tego samego rodzaju, zagnieżdżają się
SitenicRegion, Site group, Tenant
LocationSitenadrzędna Location, Tenant
Rack typeManufacturer
RackSiteLocation, Rack group, Rack role, Rack type, Tenant
Device typeManufacturer
Device rolenicnadrzędna Device role, zagnieżdżają się
DeviceDevice role, Device type, SiteRack i pozycja, Platform, Tenant
Interface i każdy inny komponentDevice
Cabledwie rzeczy, na których się kończyTenant
AggregateRIRTenant
VLANnicVLAN group, Role, Tenant
PrefixnicSite, VLAN, Role, VRF, Tenant
IP addressnicInterface, do którego go przypisać, Tenant
CircuitProvider i Circuit typeTenant
Circuit terminationCircuitSite, na którym ląduje
ClusterCluster typeCluster group, Site, Tenant
Virtual machineSite, Cluster albo DevicePlatform, Tenant
VM interfaceVirtual machine

To druga kolumna kosztuje. Prefiksy, adresy IP, VLAN-y i dzierżawcy nie wymagają niczego, więc nic nie powstrzyma cię przed utworzeniem ich pierwszego dnia w dowolnej kolejności. Czy będą do czegoś przydatne, to inna sprawa, bo adres bez interfejsu za nim to wiersz na liście, a urządzenie bez dzierżawcy to urządzenie, które później będziesz edytować jeszcze raz.

Kolejność, w jakiej naprawdę pracować

To daje sekwencję. Idź po niej w dół, a nic ci nigdy nie odmówi.

Najpierw rzeczy, na których wisi wszystko inne. Żadna z nich nie jest ekscytująca i każdą tanio jest zrobić źle.

  1. Grupy dzierżawców, potem dzierżawcy. Zrób je przed czymkolwiek innym. Dwadzieścia osiem modeli przyjmuje dzierżawcę, w tym Site, Location i Rack, więc jeśli klientów jeszcze nie ma, nie przypiszesz ich na bieżąco i później będziesz robić masową edycję.
  2. Regiony i grupy lokalizacji. Oba opcjonalne, oba zagnieżdżają się same w sobie i są od siebie niezależne. Regiony są do geografii, grupy lokalizacji do funkcji, a możesz użyć jednego, obu albo żadnego.
  3. Lokalizacje (Site). Korzeń prawie wszystkiego. Lokalizacja nie wymaga niczego i dlatego jest pierwszą rzeczą, którą faktycznie możesz utworzyć.
  4. Pomieszczenia (Location). Wymagają lokalizacji i zagnieżdżają się, więc hala zawierająca rzędy zawierające pody to jeden model na trzech poziomach.
  5. Role szaf i grupy szaf. Obie opcjonalne. Grupy szaf są płaskie i stoją obok pomieszczeń jako druga oś, co przydaje się na rzędy i pody.
  6. Producenci, potem typy szaf. Typ szafy wymaga producenta. Pomiń typy szaf, jeśli nie modelujesz samych szaf.
  7. Szafy. Wymagają lokalizacji. Jeśli dasz szafie także pomieszczenie, to pomieszczenie musi należeć do tej lokalizacji, a NetBox to sprawdza.

Potem katalog sprzętu, a nie sam sprzęt. Zanim dodasz choćby jedno urządzenie, potrzebujesz producentów, typów urządzeń, ról urządzeń i w praktyce platform.

  1. Producenci. Możesz już jakichś mieć z kroku 6, bo typy szaf też ich potrzebują. Typy modułów również.
  2. Typy urządzeń, każdy wymaga producenta.
  3. Role urządzeń, które się zagnieżdżają, oraz platformy.

To jest krok, który ludzie pomijają, i to jest krok, który decyduje, ile pisania wymaga reszta roboty. Typ urządzenia niesie własne interfejsy, porty i wnęki jako szablony, więc każde urządzenie, które z niego utworzysz, przychodzi już z właściwymi komponentami. Zrób typ dobrze raz, a zamontowanie czterdziestu sztuk to czterdzieści nazw.

Platforma jest na tej liście wyjątkiem, bo urządzenie formalnie jej nie wymaga. I tak zrób to teraz. To ona później niesie szablon konfiguracji i sterownik NAPALM, a wracanie, żeby ustawić ją na całej infrastrukturze, to ten sam wieczór, który spędziłbyś na dzierżawcach.

Potem sam sprzęt.

  1. Urządzenia. Rola, typ i lokalizacja są wymagane. Szafa i pozycja są opcjonalne, a jeśli je podasz, muszą być spójne z lokalizacją.
  2. Komponenty, jeśli typ urządzenia ich jeszcze nie dostarczył.
  3. Kable między komponentami.

Potem adresacja, bo adres chce mieć interfejs, na którym żyje, a interfejs istnieje dopiero po kroku 12.

  1. RIR-y, potem agregaty.
  2. Role prefiksów i VLAN-ów, VRF-y, grupy VLAN-ów, potem VLAN-y.
  3. Prefiksy, potem pojedyncze adresy IP.

Potem warstwa handlowa.

  1. Dostawcy, konta dostawców i typy łączy.
  2. Łącza, potem ich zakończenia w lokalizacjach.

I infrastruktura wirtualna, która odzwierciedla fizyczną.

  1. Typy klastrów i grupy klastrów, potem klastry.
  2. Maszyny wirtualne, które potrzebują lokalizacji, klastra albo urządzenia, a potem ich interfejsy.

Kroki od 1 do 10 to jedno popołudnie i wyglądają na papierologię. Nie ma w nich nic efektownego. To też jest popołudnie, które decyduje, czy krok 11 zajmie poranek, czy dwa tygodnie.

Reguły, które gryzą później

Pola wymagane to łatwiejsza połowa, bo zawodzą od razu i mówią dlaczego. Ludzi łapią reguły spójności, które odpalają się dopiero wtedy, gdy masz wystarczająco danych, żeby sam sobie zaprzeczyć:

device at Leeds, put in a Manchester rack
  {"rack": ["Rack MCR1-A07 (A07) does not belong to site Leeds Edge."]}
device at Leeds, in a Manchester location
  {"location": ["Location Hall 2 does not belong to site Leeds Edge."]}
rack at Leeds, in a Manchester location
  {"__all__": ["Assigned location must belong to parent site (Leeds Edge)."]}
a second device in a unit that is already taken
  {"position": ["U39.0 is already occupied or does not have sufficient
                 space to accommodate this device type: MX204 (1.0U)"]}

Ten ostatni wskazałbym, gdyby ktoś zapytał, po co to wszystko. NetBox wie, że urządzenie ma 1U, wie, co jest w szafie, i nie pozwoli ci zapisać dwóch rzeczy w tym samym miejscu. Twój arkusz kalkulacyjny pozwoli ci na to przez całe popołudnie i słowem się nie odezwie, a dowiesz się, gdy ktoś będzie stał w hali z pudłem w rękach.

Żadnej z tych reguł nie da się skonfigurować i żadnej nie powinno się dać. To one są różnicą między zapisem a pobożnym życzeniem.

Używanie: co daje ci każdy ekran

Z załadowaną infrastrukturą, oto co naprawdę z niej dostajesz. Wszystko poniżej to ta sama instancja: jedna szafa, czternaście urządzeń, okablowanych i zaadresowanych dla trzech klientów.

Urządzenie to jego komponenty

Kliknij w jeden z tych hiperwizorów, a ciekawą zakładką nie jest podsumowanie, tylko interfejsy.

Zakładka interfejsów NetBox dla urządzenia mcr1-hv-01 z trzema interfejsami: eno1, SFP28 25GE, opisany jako do leaf-01, z adresem IP 10.20.20.11/24 i kablem MCR1-DAC-0001A do mcr1-leaf-01 Ethernet1; eno2 SFP28 25GE do leaf-02 z kablem MCR1-DAC-0001B do mcr1-leaf-02 Ethernet1; oraz ipmi 1000BASE-T opisany jako BMC z adresem 10.20.10.101/24

Przeczytaj jeden wiersz w poprzek. Interfejs, jego prędkość, co o nim napisałeś, adres na nim, etykieta na kablu i port na drugim końcu. To jedno zapytanie i odpowiedź na pytanie, które wszyscy naprawdę zadają, czyli „do czego to jest wpięte”.

Zwróć uwagę, gdzie siedzi adres. Jest na eno1, a nie na serwerze. Brzmi to jak pedanteria aż do chwili, gdy masz pudełko z interfejsem zarządzania, dwoma interfejsami danych i loopbackiem, a ktoś pyta, który adres za nie odpowiada. Model, który wiesza adresy na urządzeniach, nie powie ci tego. Ten powie, a do tego obsłuży całkiem zwyczajny przypadek czterech adresów na jednym interfejsie.

Idź za kablem

Kable kończą się na komponentach, a nie na urządzeniach. Interfejs na jednym końcu, interfejs na drugim, albo port przedni, port tylny, gniazdo zasilania, zakończenie łącza. Na tym szczególe opiera się cała funkcja i dlatego lista interfejsów powyżej mogła wypisać drugi koniec we własnej kolumnie, nikt jej tego nie musiał mówić.

Zamodeluj kabel od urządzenia do urządzenia, a narysowałeś obrazek. Zakończ go na portach, a NetBox może po nim przejść.

Śledzenie kabla w NetBox dla interfejsu eno1, narysowane jako pionowy diagram: mcr1-hv-01, Supermicro SYS-1029U-TN10RT w Manchester DC1 / Hall 2 / MCR1-A07 (A07) / Front / U20.0, jego interfejs eno1, kabel MCR1-DAC-0001A oznaczony jako Connected, potem Ethernet1 na mcr1-leaf-01, Arista DCS-7050SX3-48YC8 na Front / U36.0. Trace Completed, łącznie 1 segment

Tu jeden przeskok, bo to kabel DAC. Wstaw pośrodku panele krosowe, a przejdzie przez nie, panel po panelu, i powie ci, co jest na końcu trasy przez trzy szafy. To robota, która w przeciwnym razie wymaga latarki i kogoś trzymającego drugi koniec sondy tonowej.

Śledzenie wypisuje też pełną lokalizację każdego końca. Lokalizacja, hala, szafa, strona, jednostka. Jeśli kiedykolwiek próbowałeś przez telefon wytłumaczyć technikowi remote hands, na które pudło ma patrzeć, ta jedna linia to cała wartość.

Adresy jako drzewo, a nie zakładka

IPAM to połowa, dla której ludzie przychodzą.

Lista prefiksów NetBox z 10.20.0.0/16 jako Container z 5 dziećmi przy zajętości 1,6%, opisanym jako Manchester DC1, a pod nim pięć aktywnych prefiksów podrzędnych wciętych o jeden poziom: 10.20.10.0/24 na VLAN mgmt (100) z rolą Management, 10.20.20.0/24 przypisany do Ravenscroft Legal na VLAN ravenscroft-prod (200), 10.20.21.0/24 do Padgate Foods, 10.20.22.0/24 do Hartley Components oraz 10.20.30.0/29 na VLAN transit (110) przy zajętości 16,7%

Wcięcia są liczone z samych adresów. Nie mówisz NetBoxowi, że 10.20.20.0/24 siedzi wewnątrz 10.20.0.0/16, on to wylicza i będzie to wyliczał dalej, gdy ktoś w przyszłym roku doda /26 w środku.

Każdy wiersz niesie to, po czym naprawdę filtrujesz: VLAN, do którego się mapuje, rolę i klienta, do którego należy. Zajętość też jest liczona.

Otwórz jeden, a dostaniesz adresy w nim i luki.

Zakładka IP Addresses w NetBox dla prefiksu 10.20.20.0/24, z zielonym wierszem „10 IPs available”, potem 10.20.20.11/24 i 10.20.20.12/24, oba aktywne i przypisane do Ravenscroft Legal, potem zielony wiersz „242 IPs available”

Te zielone wiersze to wolne miejsce, pokazane w jednej linii z zajętym. Jest wywołanie API, które podaje ci następny wolny adres z prefiksu, i to jest jedyny kawałek automatyzacji IPAM, który zwraca się od razu, bo to rzecz, którą ludzie w przeciwnym razie robią, mrużąc oczy nad arkuszem i mając nadzieję.

Interfejs przyjmuje tyle adresów, ile chcesz, z obu rodzin, a ty wskazujesz po jednym z każdej jako główny adres urządzenia.

Lista adresów IP w NetBox przefiltrowana do interfejsu eno1 na mcr1-hv-01, z czterema adresami: 10.20.20.11/24 oznaczony jako primary, 10.20.20.201/24 jako adres usługi, 2001:db8:20:20::11/64 jako primary v6 oraz 2001:db8:20:20::201/64 jako adres usługi, wszystkie przypisane do Ravenscroft Legal

Dwa IPv4 i dwa IPv6 na jednym porcie, co jest zwykłym wtorkiem i czymś, czego model skupiony na urządzeniach w ogóle nie wyrazi.

Wpisuj adresy z maską sieci, w której są, a nie jako /32. NetBox przyjmie 10.20.20.11/32 i zaliczy go do właściwego prefiksu, bo zawieranie jest liczone z adresu hosta. Czego nie zrobi, to poprawiać cię potem: maska jest zapisywana dokładnie tak, jak ją wpisałeś, i oddawana temu, co ją czyta, więc /32 na adresie w LAN-ie wyrenderuje /32 do konfiguracji urządzenia. Ugryzie cię to za trzy miesiące w szablonie konfiguracji, a nie dziś w formularzu.

Jedna instalacja, trzech klientów

Większość obiektów w NetBoxie można przypisać do dzierżawcy (tenant). Przedsiębiorstwo używa tego dla jednostek biznesowych. Jeśli sprzedajesz usługi zarządzane, tworzysz jednego na klienta.

Strona dzierżawcy Ravenscroft Legal w NetBox w grupie Customers, z panelem Related Objects wymieniającym Circuits 2, Devices 2, IP Addresses 2, Prefixes 1 i VLANs 1 oraz zakładkami u góry Custom Objects, Contacts, Journal i Changelog

Ten panel po prawej to odpowiedź na pytanie „co ma ten klient” i złożył się sam. Bez raportu, bez arkusza, bez pytania inżyniera, który to budował.

Warto uważać, co oznacza dzierżawa, bo pomyłka pierwszego dnia to rok rozplątywania później. Dzierżawca oznacza, że obiekt jest dedykowany temu klientowi. Router, który obsługuje tylko jego, dostaje jego dzierżawcę. Firewall obsługujący czterech z nich nie należy do żadnego, więc nie dostaje żadnego, a relacja trafia gdzie indziej. Więcej o tym dalej, bo to moment, w którym większość ludzi odkrywa, że musi dodać coś własnego.

Wpisz liczby na typie urządzenia

To jest krok, który oddziela inwentarz od czegoś, co odpowiada na pytania, i kosztuje około dziesięciu minut na typ urządzenia.

Typ urządzenia może nieść swoją wagę, a przez szablony portów zasilania swój pobór mocy. Wpisz je na typie raz, a każde urządzenie, które kiedykolwiek z niego utworzysz, je odziedziczy. Pomiń je, a NetBox z radością powie ci, że szafa jest zapełniona w 28,6% i nic więcej.

Strona typu urządzenia Supermicro SYS-1029U-TN10RT w NetBox z wysokością 1U, zaznaczonym full depth, wagą 19,10 kg i metodą chłodzenia Air, z zakładką Power Ports pokazującą liczbę 2 i panelem Related Objects pokazującym 6 urządzeń

Wpisałem wagę na wszystkich pięciu typach, dałem każdemu dwa szablony portów zasilania z maksymalnym i przydzielonym poborem, dałem typowi PDU wejście i dwanaście gniazd, a potem utworzyłem panel zasilania i dwa zasilania do szafy i okablowałem całość: PSU1 każdego urządzenia do PDU A, każdy PSU2 do PDU B, a wejście każdego PDU do jego zasilania.

Zasilanie MCR1-A07-A w NetBox, typ Primary, status Active, podłączone do mcr1-pdu-a INPUT, z zajętością przydzieloną 5340VA z 5888VA jako czerwony pasek 90,7 procent i parametrami elektrycznymi: zasilanie AC, 230 woltów, 32 ampery, jedna faza i maksymalna zajętość 80 procent

Wtedy strona szafy zmienia się zupełnie.

Strona szafy MCR1-A07 w NetBox, teraz z możliwością chłodzenia Hybrid, wydajnością chłodzenia 15,00 kW, zajętością miejsca 28,6 procent na zielono i zajętością mocy 90,7 procent na czerwono, obok widoku z przodu i z tyłu

Zajętość miejsca 28,6%. Zajętość mocy 90,7%.

Ta szafa jest w jednej trzeciej pełna sprzętu i prawie bez mocy, a to fakt o twojej infrastrukturze, którego żaden arkusz nigdy sam z siebie nie poda. To też fakt, który decyduje, czy następne zamówienie zostanie tam zamontowane, czy gdzie indziej, i wypadł z danych, które wpisałeś raz, na typach.

Dwie rzeczy, przez które pokaże zero

Na początku dostałem 0,0%, dwa razy, i obie przyczyny warto znać, bo żadna nie daje błędu.

Gniazda muszą wskazywać na wejście. Gniazdo zasilania na PDU ma pole power_port wskazujące na port wyżej w łańcuchu na tym samym urządzeniu. Zostaw je puste, a łańcuch jest przerwany: NetBox nie ma jak wiedzieć, że tych dwanaście gniazd jest zasilanych przez to wejście, więc nic się nie sumuje.

Zostaw pola poboru na wejściu puste. To jest ta wbrew intuicji. NetBox liczy pobór portu zasilania z tego, co jest do niego wpięte, tylko jeśli oba jego własne pola poboru są puste:

if self.allocated_draw is None and self.maximum_draw is None:
    ...aggregate the downstream power ports...
# otherwise
return {'allocated': self.allocated_draw or 0, ...}

Usłużnie ustawiłem maximum_draw: 7400 na wejściu PDU, bo na tyle PDU jest znamionowane. NetBox więc mi uwierzył, uznał allocated_draw za nieustawione i zgłosił zero. Wyczyść oba, a sam to policzy:

mcr1-pdu-a INPUT -> allocated 5340 VA, maximum 8480 VA, across 12 outlets
mcr1-pdu-b INPUT -> allocated 5340 VA, maximum 8480 VA, across 12 outlets
feed MCR1-A07-A: available 5888 VA   (230 V x 32 A x 80% max utilisation)
RACK power utilisation: 90.7 %
RACK weight: 166.6 kg of 900 kg

Więc reguła brzmi: wpisz prawdziwe liczby na liściach, a porty pośrednie zostaw puste, żeby NetBox mógł je zsumować. Wartość zdefiniowana administracyjnie zawsze wygrywa z wyliczoną, co jest poprawnym zachowaniem i dokładnie tym, czego nie należy robić na PDU.

Chłodzenie, które jest nowe

Wersja 4.7 dodała chłodzenie do DCIM i przyszło z tą połową, która robi się droga. Szafa niesie możliwość chłodzenia (powietrze, hybryda albo ciecz) i wydajność w kilowatach; typ urządzenia niesie metodę chłodzenia. Nad tym są źródła chłodzenia dla agregatów wody lodowej i jednostek CRAC, zasilania chłodzenia reprezentujące pętlę do szafy oraz komponenty wlotu i wylotu na samych urządzeniach, dla płyt chłodzących i rozdzielaczy.

Szafa powyżej pokazuje Hybrid, 15,00 kW, bo tak powiedziałem szafie. Jeśli w tym roku odbierasz sprzęt chłodzony cieczą, to jest model dla rzeczy, którą obecnie trzymasz w arkuszu.

Jedna instalacja, wielu klientów

Dzierżawa to powód, dla którego dostawca może prowadzić jeden NetBox, a nie po jednym na klienta, i warto rozumieć, co robi, a co ważniejsze, czego nie robi.

Dwadzieścia osiem modeli NetBoxa ma pole dzierżawcy. Lokalizacje, pomieszczenia, szafy i rezerwacje w szafach. Urządzenia, kable i wirtualne konteksty urządzeń. Prefiksy, adresy IP, zakresy, agregaty, VLAN-y, grupy VLAN-ów, VRF-y, route targety, numery ASN. Łącza i grupy łączy. Klastry i maszyny wirtualne. Tunele, L2VPN-y, sieci bezprzewodowe i łącza. Zasilania i zasilania chłodzenia.

To każdy rzeczownik, za który się wystawia fakturę. Ustawiaj to konsekwentnie, a „co ma ten klient” przestaje być śledztwem.

Ale dzierżawca to etykieta, a nie zamek. Mówi, że obiekt jest dedykowany temu klientowi. Nie powstrzymuje nikogo, kto może się zalogować, przed przeczytaniem całości, co jest w porządku wewnątrz jednej firmy i zupełnie bezużyteczne w chwili, gdy klient ma konto.

Wynikają z tego dwie rzeczy, a druga to ta, którą ludzie robią źle.

Dzierżawca oznacza dedykowany. Router, który obsługuje tylko jednego klienta, dostaje jego dzierżawcę. Firewall obsługujący czterech z nich nie należy do żadnego, więc nie dostaje nic, a relację zapisujesz zamiast tego na rzeczy, którą faktycznie sprzedałeś. Wciskanie dzierżawcy na współdzielony sprzęt sprawia, że każdy raport zbudowany na dzierżawie jest po cichu błędny.

A dostęp to zupełnie osobny mechanizm.

Izolacja żyje w uprawnieniach

Uprawnienia do obiektów w NetBoxie przyjmują ograniczenie w JSON, a to ograniczenie jest filtrem Django ORM. Zawęża queryset, zanim cokolwiek zostanie z niego zbudowane, więc każdy widok, eksport, wywołanie API i wyszukiwanie jest zawężane razem z nim.

Strona szczegółów uprawnienia Ravenscroft read-only w NetBox z zaznaczonym Enabled, w Actions zaznaczone View, a Add, Change, Delete, Render configuration i Synchronize data przekreślone, Object Types wymieniające Circuits circuit, DCIM device i IPAM prefix, jeden przypisany użytkownik ravenscroft-ro i panel Constraints z JSON-em tenant__slug ustawionym na ravenscroft-legal

Robotę robią trzy pola. Typy obiektów, do których się odnosi, akcje, które przyznaje, i to ograniczenie na dole. Cała reszta to księgowość.

Oto lista urządzeń widziana przez administratora.

Lista urządzeń NetBox jako użytkownik admin, Results 14, z mcr1-core-01 i 02, mcr1-hv-01 do 06, mcr1-leaf-01 i 02, mcr1-pdu-a i b oraz mcr1-pp-01 i 02, z kolumnami status, tenant, site, location, rack, role, manufacturer, type i IP address

A oto ten sam URL, ta sama instalacja, zalogowany jako klient.

Ta sama lista urządzeń NetBox po zalogowaniu jako ravenscroft-ro, Results 2, pokazuje tylko mcr1-hv-01 i mcr1-hv-02, oba przypisane do Ravenscroft Legal, z nawigacją po lewej ograniczoną do Devices, IPAM, Circuits, Plugins i Admin

Dwa wiersze zamiast czternastu, i spójrz na menu po lewej. Skurczyło się do czterech rzeczy, których to konto może dotykać. Nikt tego nie konfigurował. Nawigacja jest budowana z tych samych uprawnień, więc klient nigdy nie widzi linku do czegoś, co by mu odmówiło.

Dwa sposoby, w jakie mówi nie

To jest szczegół wart poznania, bo te dwie odmowy znaczą co innego i obie są celowe.

Token klienta prosi oDostaje
/api/dcim/devices/200, jeden wiersz z dwóch
/api/dcim/devices/1/, własne200
/api/dcim/devices/2/, cudze404
/api/tenancy/tenants/403
/api/dcim/sites/, nigdy nieprzyznane403
w ogóle bez tokena403

404 oznacza, że typ jest twój, ale ten wiersz nie. Ograniczenie usunęło go z querysetu, więc z punktu widzenia żądania on nie istnieje. 403 w tym miejscu potwierdziłoby, że istnieje, i pozwoliłoby ciekawskiemu klientowi policzyć twoją infrastrukturę, przechodząc po ID.

403 oznacza, że typ nigdy nie był twój. Dzierżawcy i lokalizacje nigdy nie zostały przyznane, więc odmowa jest od razu, a klient nie może wyliczyć, kto jeszcze jest na platformie.

Potem pozwól im pisać

Tylko do odczytu to łatwy przypadek. Prawdziwe pytanie brzmi, czy klientowi z prawem edycji można to prawo powierzyć, więc przyznałem change z tym samym ograniczeniem i zacząłem szukać wyjścia.

PróbaWynik
Edycja własnego urządzenia200, zapisane
Edycja urządzenia innego klienta404
Edycja własnego urządzenia z przeniesieniem go do dzierżawcy innego klienta403
Usunięcie własnego urządzenia403, usuwanie nigdy nie zostało przyznane

Trzeci wiersz jest tym, który się liczy. Przepisanie własnego urządzenia do cudzego dzierżawcy to oczywista ucieczka, bo obiekt jest wewnątrz twojego ograniczenia, gdy żądanie przychodzi, i poza nim potem. NetBox sprawdza ograniczenie względem stanu, w jakim obiekt zostałby zostawiony, więc odmawia. Odczytałem urządzenie z powrotem, zamiast ufać kodowi statusu, i dzierżawca się nie zmienił.

To jest dziura, którą większość domowej roboty wielodzierżawności zostawia otwartą, i zwykle znajduje ją klient, a nie test.

Zmienne, które muszą się dziedziczyć

Oto rozróżnienie, które ludzie robią źle, a zrobienie go dobrze oszczędza mnóstwo edycji.

Pole własne (custom field) to wartość na jednym obiekcie. Ustawiasz je dla każdego obiektu osobno i tam zostaje. Dobre na fakt o samej rzeczy: numer inwentarzowy, numer umowy serwisowej, datę uruchomienia.

Config context to wartość przypięta do cechy, którą dziedziczy wszystko, co tę cechę ma. Dobre na zmienną, która powinna spływać w dół: twoje serwery NTP, cele syslogu, community SNMP, domenę DNS, VLAN zarządzania, okno kopii zapasowych.

Jeśli łapiesz się na ustawianiu tego samego pola własnego na tę samą wartość na czterdziestu urządzeniach, chciałeś config contextu.

Lista config contexts w NetBox: North West base z wagą 1000 przypisany do regionu North West oraz Manchester DC1 syslog z wagą 2000 przypisany do lokalizacji Manchester DC1, oba aktywne

Kontekst to dowolny JSON i można go przypiąć do regionu, grupy lokalizacji, lokalizacji, pomieszczenia, typu urządzenia, roli, platformy, klastra, typu klastra, grupy klastrów, grupy dzierżawców, dzierżawcy albo tagu. Dzierżawca jest na tej liście, co dla dostawcy oznacza, że fakt prawdziwy dla jednego klienta wszędzie idzie za nim na każde urządzenie, jakie kiedykolwiek dla niego dodasz.

Scalanie odbywa się po kluczu, a waga decyduje, kto wygrywa każdy z nich.

Zakładka Config Context dla mcr1-core-01 w NetBox: po lewej Rendered Context z domain, ntp_servers, snmp_community i syslog_servers, po prawej Source Contexts z North West base o wadze 1000 ze wszystkimi czterema kluczami oraz Manchester DC1 syslog o wadze 2000 zawierającym tylko syslog_servers

Przeczytaj prawy panel względem lewego. Region dostarcza cztery klucze z wagą 1000. Lokalizacja dostarcza jeden klucz z wagą 2000. Wyrenderowany kontekst zachowuje nietknięte domenę, serwery NTP i community z regionu, a bierze serwer syslog z lokalizacji, bo to jedyny klucz, o który był spór.

Piszesz wyjątek, a nie świeżą kopię wszystkiego z wyjątkiem w środku. To jest cała wartość i dlatego to się skaluje, a plik zmiennych na urządzenie nie.

Kontekst lokalny bije wszystko powyżej

Stos dziedziczenia ma szczyt i jest nim sam obiekt. Lokalne dane kontekstu na urządzeniu wygrywają z każdym kontekstem źródłowym, który się do niego odnosi, niezależnie od wag.

Ustawiłem to na mcr1-core-01:

{"syslog_servers": ["10.20.10.99"], "note": "this box logs somewhere else"}

a jego wyrenderowany kontekst stał się taki:

{
  "note": "this box logs somewhere else",
  "domain": "mcr1.example.net",
  "ntp_servers": ["172.16.10.22", "172.16.10.33"],
  "snmp_community": "n0rthwest",
  "syslog_servers": ["10.20.10.99"]
}

Zakładka Config Context dla mcr1-core-01 w NetBox z wypełnionym teraz Local Context zawierającym syslog_servers 10.20.10.99 i notatkę, panel informujący, że lokalny config context nadpisuje wszystkie konteksty źródłowe, oraz Rendered Context pokazujący lokalny serwer syslog obok odziedziczonej domeny, serwerów NTP i community

Lokalny serwer syslog pobił zarówno nadpisanie z lokalizacji z wagą 2000, jak i region z wagą 1000. Wszystko, o czym nic nie mówił, nadal się odziedziczyło, więc domena, serwery NTP i community przeszły nietknięte, a nowy klucz po prostu został dodany.

To jest wyjście awaryjne dla tego jednego pudełka, które naprawdę jest inne, a panel mówi ci wprost, że nadpisuje wszystkie konteksty źródłowe. Jeśli łapiesz się na używaniu tego na wielu urządzeniach, a nie na jednym, znalazłeś cechę, którą te urządzenia dzielą, i chciałeś kontekstu przypiętego do niej.

Trzy pułapki

Kontekst bez zakresu jest globalny. Utwórz go i zapomnij do czegoś przypisać, a obejmie każde urządzenie i każdą maszynę wirtualną, jaką masz. To udokumentowane zachowanie i czasem dokładnie to, czego chcesz. Jest też ciche.

Klucze nie mogą mieć myślników, jeśli chcesz się do nich łatwo dostać. Dane kontekstu to JSON, więc ntp-servers jest całkowicie legalne, ale nazwy zmiennych w Jinja to nie klucze JSON. {{ ntp-servers }} jest parsowane jako odejmowanie i rzuca UndefinedError: 'ntp' is undefined. Napisz {{ ntp_servers }} przy danych z myślnikiem, a dostaniesz pusty ciąg, HTTP 200 i nigdzie żadnego ostrzeżenia. Używaj podkreśleń w kluczach, a oczywisty szablon zadziała.

Profil może zatrzymać literówki. Profil config contextu grupuje powiązane konteksty i wymusza na ich danych schemat JSON przy zapisie. Dałem jednemu schemat wymagający syslog_servers jako tablicy ciągów IPv4, a potem popełniłem dwa błędy, które ludzie popełniają naprawdę:

{"syslog-server": ["10.1.1.1"]}          singular, by accident
  400  Data does not conform to profile schema:
       'syslog-servers' is a required property

{"syslog_servers": [...], "syslog_port": 99999}
  400  Data does not conform to profile schema:
       99999 is greater than the maximum of 65535

Odrzucone tam, gdzie ktoś je popełnił, a nie czterysta urządzeń później.

Renderowanie konfiguracji

Dane kontekstu plus szablon Jinja dają ci plik konfiguracyjny. Urządzenie jest w zasięgu jako device, jego scalony kontekst jest w zasięgu jako zwykłe zmienne, a po jego komponentach możesz iterować.

Zakładka Render Config dla mcr1-core-01 w NetBox z szablonem konfiguracji Junos base i wyrenderowaną konfiguracją Junos: host-name mcr1-core-01, domain-name mcr1.example.net, linia location o treści Manchester DC1 / MCR1-A07 / U39, dwa serwery NTP, jeden host syslog 10.20.10.99, community SNMP n0rthwest oraz każdy interfejs z opisem i rodziną adresów

Wszystko na tej stronie przyszło z innego miejsca i o to właśnie chodzi:

LiniaSkąd się wzięła
host-name mcr1-core-01z urządzenia
domain-name mcr1.example.netz regionalnego config contextu
location "Manchester DC1 / MCR1-A07 / U39"z lokalizacji, szafy i pozycji w niej
server 172.16.10.22z kontekstu regionalnego, waga 1000
host 10.20.10.99 any noticez własnego lokalnego kontekstu urządzenia, który bije i lokalizację, i region
family inet address 10.20.10.11/24z adresu na tym interfejsie, z maską taką, jak wpisano

Szablon jest szukany na urządzeniu, potem na roli, potem na platformie, a żądanie kończy się błędem, jeśli żadne z trzech go nie ma. Więc przypisujesz szablon do platformy raz, a każde urządzenie z tym oprogramowaniem renderuje się z niego, chyba że jego rola albo samo urządzenie mówi inaczej. Do tego służy platforma: rodzina systemu operacyjnego albo oprogramowania producenta, a nie sprzęt.

NetBox renderuje. Nie wgrywa. Dostarczenie wyniku na pudełko to robota twojej automatyzacji, a w dniu, w którym błąd w szablonie przekonfigurowałby czterysta urządzeń, będziesz zadowolony, że to dwa różne systemy.

Wtyczki

Wtyczka to aplikacja Django zainstalowana obok NetBoxa. Może dodawać modele, strony, rozszerzać oba API, wstrzykiwać treść do istniejących szablonów, dodawać nawigację, kolejki zadań w tle i ładować kolejne aplikacje Django. Niewiele jest rzeczy, których nie potrafi, bo pod spodem to po prostu Django.

Instalacja to cztery polecenia i restart:

source /opt/netbox/venv/bin/activate
pip install netbox-topology-views netbox-qrcode
# add the package names to PLUGINS in configuration.py, then
python3 manage.py migrate
python3 manage.py collectstatic --no-input
sudo systemctl restart netbox netbox-rq

Na stosie kontenerów te same pakiety idą do plugin_requirements.txt i przebudowujesz obraz. Tak czy inaczej, przypnij wersje i najpierw sprawdź macierz zgodności, bo wtyczka, która nie nadąża za wydaniem NetBoxa, nie wyłączy się sama, tylko nie pozwoli wystartować całej aplikacji.

Strona zainstalowanych wtyczek NetBox: Custom Objects w wersji 0.7.0 od NetBox Labs, Topology views w wersji 4.7.0 od Mattijsa Vanhaverbeke i qrcode w wersji 1.0.0 od Nikolaya Yuzefovicha

Opublikowany katalog wymienia 31. Oto te, które warto znać, z licencją, na jakiej każda faktycznie jest wydawana:

WtyczkaCo robiLicencja
DNSStrefy, rekordy i serwery nazw jako źródło prawdyMIT
BGPSesje, community i polityki routinguApache 2.0
Topology ViewsGraficzne mapy topologii budowane z twoich kabliApache 2.0
FloorplanGraficzne mapy lokalizacji i pomieszczeńLGPL 3.0
QR CodeKody na szafach, urządzeniach i kablach, do etykiet inwentarzowychApache 2.0
ACLsListy dostępu i regułyApache 2.0
Prometheus SDPodaje Prometheusowi listę hostów prosto z NetBoxaMIT
DocumentsDokumenty przypięte do łączy i urządzeńApache 2.0
LifecycleKoniec życia sprzętu, licencje i umowyApache 2.0
ContractUmowy i fakturyMIT
Reorder RackPrzeciąganie jednostek w szafieApache 2.0
BranchingIzolowane, scalalne gałęzie twoich danychNetBox Limited Use
Custom ObjectsNowe typy obiektów definiowane w interfejsieNetBox Limited Use

Prometheus SD to uczciwy kształt całej idei. NetBox wie, co istnieje, więc niech NetBox powie to systemowi monitoringu, a ty przestań utrzymywać drugą listę hostów, która się rozjeżdża.

Jedna rzecz, którą trzeba wiedzieć, zanim zbudujesz coś na dwóch ostatnich wierszach. Sam NetBox jest na Apache 2.0 od czasu, gdy DigitalOcean wypuścił go w 2016 roku, a dziś projektem opiekuje się NetBox Labs razem z zespołem wolontariuszy.21 NetBox Branching i NetBox Custom Objects nie są: są wydawane na NetBox Limited Use License 1.0, która pozwala na użycie „only as part of a NetBox installation obtained from NetBox Labs or a NetBox distributor authorized by NetBox Labs, and only for your own internal use” i nie daje prawa do użycia oprogramowania „to provide a managed service or software products that includes, integrates with, or extends NetBox in a way that competes with any product or service of NetBox Labs”. Jeśli zainstalowałeś NetBox Community z GitHuba i prowadzisz go w imieniu klientów, przeczytaj warunki sam, zanim postawisz na nich schemat.10 Własny przewodnik instalacji NetBoxa poleca obie wtyczki, nie wspominając o tym.11

Pola własne

Pole własne dodaje atrybut do istniejącego modelu. Wartości są przechowywane jako JSON obok każdego obiektu, więc nie ma migracji ani restartu, a typów jest trzynaście, w tym odwołania do jednego i wielu obiektów NetBoxa.

Strona urządzenia mcr1-core-01 w NetBox z panelem Custom Fields, w którym grupa Asset zawiera Warranty expires 2029-06-30 i Support contract JNPR-448120, obok panelu Device Type z Juniper MX204 i panelu Dimensions z łączną wagą 9,5 kilograma

Dwa pola, zgrupowane pod wybranym przeze mnie nagłówkiem „Asset”. Zwróć uwagę na panel Dimensions po ich prawej: 9,5 kg, czego nikt nie wpisał na tym urządzeniu. Przyszło z typu urządzenia.

Pola własne są walidowane i warto wiedzieć, że są, bo to realna różnica względem drogi opisanej niżej. Dałem polu umowy wyrażenie regularne i API je wymusiło:

PATCH {"custom_fields": {"support_contract": "nonsense"}}
  {"__all__": ["Invalid value for custom field 'support_contract':
                Value must match regex '^[A-Z]{2,4}-[0-9]{6}$'"]}

W 4.7 zmieniły się dwie rzeczy, które mają znaczenie w skali. Utworzenie pola z wartością domyślną albo usunięcie pola musi przepisać zapisane dane każdego obiektu, którego dotyczy, więc na dużej tabeli ta praca jest przekazywana do zadania w tle, a pole zgłasza „provisioning” albo „deleting”, dopóki ono trwa. Pole działa tylko wtedy, gdy jest aktywne: podczas każdej z tych operacji nie pojawia się na obiektach, w formularzach, w filtrach ani w żadnym z API. To wymaga działającego procesu roboczego, inaczej pole zostaje w tym stanie bez końca.

Użyj pola własnego, gdy dodajesz fakt o samej rzeczy. Użyj config contextu, gdy wartość ma spływać w dół. Użyj następnego rozdziału, gdy rzecz, której potrzebujesz, nie istnieje.

Własne menu wyboru i nadpisywanie tego, co jest w pudełku

Pod tym nagłówkiem żyją dwa różne mechanizmy i rozwiązują różne problemy. Jeden jest dla twoich własnych pól. Drugi przepisuje pola NetBoxa.

Zestaw wyborów dla twojego własnego pola wyboru

Pole własne typu „selection” bierze opcje z zestawu wyborów (choice set), czyli obiektu, którym zarządzasz w interfejsie jak wszystkim innym. Więc „poziom wsparcia” staje się prawdziwą listą rozwijaną zamiast wolnego tekstu, który ktoś zapisze na trzy sposoby.

Zestaw wyborów pola własnego o nazwie Support tier w NetBox, opisany jako to, za co płaci klient, z trzema wyborami: bronze na następny dzień roboczy, silver na 8 godzin i gold na 4 godziny 24x7

Jest wymuszany, także przez API:

PATCH {"custom_fields": {"support_tier": "platinum"}}
  {"__all__": ["Invalid value for custom field 'support_tier':
                Invalid choice (platinum) for choice set Support tier."]}

Zestawy wyborów są współdzielone, więc jeden zestaw może obsługiwać to samo pole na kilku modelach, a zmiana listy w jednym miejscu zmienia ją wszędzie.

FIELD_CHOICES dla własnych pól NetBoxa

O tym ludzie nie wiedzą, że istnieje. Kilka wbudowanych pól wyboru NetBoxa można rozszerzyć albo zastąpić z configuration.py, w tym status urządzenia, status lokalizacji, status szafy, status łącza i wiele innych.12

Dopisz znak plus, żeby dodać do tego, co jest w pudełku. Pomiń go, żeby zastąpić listę w całości.

FIELD_CHOICES = {
    # add to what NetBox ships with
    'dcim.Device.status+': (
        ('burn-in', 'Burn-in', 'cyan'),
        {'value': 'awaiting-rma', 'label': 'Awaiting RMA', 'color': 'orange',
         'description': 'Faulty, with the vendor'},
    ),
    # replace the stock list outright
    'dcim.Site.status': (
        ('surveyed', 'Surveyed', 'purple'),
        ('building', 'Building out', 'orange'),
        ('active', 'Active', 'green'),
        ('closing', 'Closing', 'red'),
    ),
}

Wpisałem dokładnie to na tej instancji. Status urządzenia wrócił z siedmioma standardowymi wartościami i moimi dwiema:

offline, active, planned, staged, failed, inventory, decommissioning,
burn-in, awaiting-rma

a status lokalizacji wrócił tylko z moimi, bez standardowej listy:

surveyed, building, active, closing

Wybór może być zwykłą krotką wartości, etykiety i koloru albo słownikiem, który przyjmuje też opis pokazywany w formularzu jako podtytuł. I zachowują się jak natywne wartości wszędzie, bo z punktu widzenia reszty NetBoxa są natywnymi wartościami:

Lista urządzeń NetBox, na której mcr1-hv-06 ma cyjanową plakietkę statusu Burn-in obok pozostałych urządzeń ze standardowym statusem Active, w takim samym stylu jak każdy wbudowany status

Ta plakietka to mój status, w moim kolorze, sortujący się i filtrujący jak każdy inny.

Trzy rzeczy, które warto wiedzieć, zanim tego użyjesz.

Zastąpienie usuwa standardowe wartości z menu, a nie z bazy danych. Każdy obiekt, który już ma jedną z nich, ją zachowuje, ale wartość nie jest już oferowana i nie będzie poprawnym wyborem, gdy ktoś następnym razem edytuje ten obiekt. Jeśli zastępujesz listę, sprawdź, czy nic nie siedzi na wartości, którą właśnie usunąłeś.

To żyje w pliku konfiguracyjnym, więc wymaga restartu i nie jest czymś, co użytkownik interfejsu może zmienić. Dla dostawcy to właściwy kierunek: zestaw statusów, które uznaje twoja firma, to decyzja z zakresu zarządzania, a nie z wtorkowego popołudnia.

Rozszerzaj, zanim zastąpisz. Standardowe wartości to to, czego oczekuje każda wtyczka, skrypt i integracja. Dopisanie nic nie kosztuje. Zastąpienie to decyzja, której jesteś właścicielem na zawsze.

Własne obiekty

Oto prawdziwa luka. NetBox modeluje klastry, maszyny wirtualne i dyski wirtualne. Nie modeluje datastore, na którym te dyski naprawdę żyją, a dla każdego, kto prowadzi Proxmoxa albo VMware, to jest obiekt, który łączy kupiony przez ciebie storage z obciążeniem, które go używa.

Wtyczka Custom Objects pozwala zdefiniować nowy typ obiektu z interfejsu albo przez API, bez pisania kodu. Więc:

Strona Custom Object Type dla Datastore w NetBox, wersja 1.0.0, opisana jako współdzielony storage, na którym klaster trzyma dyski VM, z zakładką Fields pokazującą 7 i panelem Fields wymieniającym Name jako Text, Cluster jako Object wskazujący na Virtualization > Cluster, Provisioned by jako Multiple objects wskazujący na DCIM > Device, Backing jako Text, Capacity (GB) jako Integer, Thin provisioned jako Boolean i Customer jako Object wskazujący na Tenancy > Tenant

Siedem pól, z których dwa to cały sens. cluster to pojedyncze odwołanie do prawdziwego klastra NetBoxa, ustawione na protect, żeby nikt nie mógł usunąć klastra spod jego storage’u. provisioned_by to odwołanie do wielu obiektów, czyli urządzeń, które faktycznie go serwują.

To daje ci pełnoprawny obiekt z własnym wpisem w nawigacji, widokiem listy, filtrami, importem i eksportem:

Lista Datastores w NetBox z czterema wierszami: ds-nvme-01 na klastrze MCR1-PVE serwowany przez mcr1-hv-01, 02 i 03, oparty na puli Ceph RBD NVMe o pojemności 40\u00a0960 GB i z thin provisioningiem; ds-nvme-02; ds-archive-01 na puli HDD z WAL na NVMe o pojemności 196\u00a0608 GB, bez thin provisioningu; oraz ds-ravenscroft-01 o pojemności 8192 GB przypisany do Ravenscroft Legal

A ponieważ odwołania są prawdziwe, relację widać też z drugiej strony. Otwórz klaster, a datastore’y są przy nim wymienione.

Strona klastra MCR1-PVE w NetBox, klastra Proxmox VE w zakresie Manchester DC1, z zakładką Custom Objects pokazującą datastore’y, które się do niego odwołują

Własny typ obiektu dziedziczy większość tego, co czyni obiekt NetBoxa obiektem NetBoxa: widoki listy i szczegółów, wpis w nawigacji, endpointy REST, wyszukiwanie pełnotekstowe, dziennik zmian, journaling, tagi, zakładki, import i eksport, reguły zdarzeń i powiadomienia. Nic z tego nie trzeba było pisać.

To też nie jest blob JSON udający tabelę. Wtyczka wykonuje prawdziwy DDL, a w PostgreSQL pojawia się prawdziwa tabela z prawdziwymi ograniczeniami:

                    Table "public.custom_objects_2"
     Column      |   Type   | Nullable |     Default
-----------------+----------+----------+------------------
 id              | bigint   | not null | identity
 name            | varchar  |          |
 cluster_id      | bigint   |          |
 backing         | varchar  |          |
 capacity_gb     | bigint   |          |
 thin_provisioned| boolean  |          |
Indexes:
    "custom_objects_2_name_key" UNIQUE CONSTRAINT, btree (name)
Foreign-key constraints:
    ... FOREIGN KEY (cluster_id) REFERENCES virtualization_cluster(id) ON DELETE RESTRICT

protect, o które prosiłem, stało się ON DELETE RESTRICT i działa: próba usunięcia tego klastra wraca z 409 i nazwą tego, co od niego zależy.

Dwie rzeczy, które trzeba wiedzieć, zanim zaczniesz na tym polegać

Walidacja jest w formularzu, a nie w API. To jest ta, która złapałaby automatyzację. Zadeklarowałem required, wyrażenie regularne i granice liczbowe na polach własnego typu obiektu, a potem zapisałem do nich przez REST API:

Co zadeklarowałemCo wysłałemWynik
validation_regexwartość niepasującą do niczego201 Created
required: truepole całkiem pominięte201 Created
validation_minimum: 1liczbę ujemną201 Created
unique: trueduplikat400, odrzucone
on_delete_behavior: protectusunięcie obiektu, do którego jest odwołanie409, odrzucone

Dwie, które wytrzymały, to te dwie, które stały się ograniczeniami w bazie danych. Reszta istnieje tylko w formularzu webowym, więc człowiek, który pisze, jest ograniczony, a nocna synchronizacja nie. Porównaj to ze zwykłym polem własnym wyżej, gdzie to samo wyrażenie regularne było wymuszane przez API. Dopóki to się nie zmieni, wszystko, od czego zależy faktura, postaw za prawdziwym ograniczeniem.

Usunięcie typu usuwa tabelę. Usunięcie pola usuwa kolumnę. To DDL z formularza webowego, wykonywany przez każdego, kto ma uprawnienie, a dokumentacja mówi to wprost.13 Ogranicz, kto może je usuwać.

Kiedy zamiast tego napisać prawdziwą wtyczkę

Jeśli obiekt ma znaczenie, jeśli automatyzacja do niego pisze i jeśli byłbyś zły, znajdując w nim śmieci, napisz model sam. Minimalna wtyczka NetBoxa to PluginConfig, model, serializer, viewset, tabela, formularz, kilka widoków i mapa URL-i, i wychodzi poniżej dwustu linii, w większości deklaracji. Dziedziczenie po PrimaryModel daje ci za darmo tagi, pola własne, dziennik zmian, journaling, szablony eksportu i własność, a każde ograniczenie, które nałożysz na model, jest wymuszane wszędzie, bo uruchamia je mechanizm serializerów samego NetBoxa.

Jest szablon cookiecutter i pełny samouczek wtyczek utrzymywane przez społeczność. Zacznij od nich, a nie od pustego katalogu.

I jest na licencji, którą sam wybierzesz, a której nikt później nie zmieni.

Własna walidacja i klasy walidacji

Wszystko powyżej dotyczy zapisywania tego, co jest. To dotyczy odmowy zapisania tego, czego być nie powinno.

NetBox waliduje każdy obiekt, zanim go zapisze, a ty możesz dodać na wierzch własne reguły. Są trzy mechanizmy, wszystkie żyją w configuration.py i razem obejmują prawie wszystko, czego potrzebuje wewnętrzny standard.

Pierwszy: zwykłe reguły, bez kodu

Walidator może być zwykłym odwzorowaniem nazw pól na warunki. Bez Pythona, a przenosi się między instalacjami, bo to po prostu dane.

CUSTOM_VALIDATORS = {
    'dcim.site': (
        {'description': {'required': True}},
    ),
    'dcim.device': (
        {'name': {'regex': r'^[a-z0-9]+-[a-z]+-([0-9]{2}|[a-z])$'}},
    ),
}

Dostępne warunki to min, max, min_length, max_length, regex, required, prohibited, eq i neq. Możesz sięgnąć do powiązanego obiektu przez ścieżkę z kropkami, więc region.name na lokalizacji jest w porządku, i możesz dopasowywać po request.user.username, choć dokumentacja całkiem słusznie mówi ci, żeby do tego używać uprawnień.

Obie te reguły odpalają się od razu:

POST a site with no description
  {"__all__": ["Custom validation failed for description:
                ['This field must not be empty.']"]}

POST a device named "Server1"
  {"__all__": ["Custom validation failed for name: ['Enter a valid value.']"]}

Ta druga to standard nazewnictwa, wymuszony. Nie napisany na stronie wiki, nie w czyjejś głowie, nie coś, za co nowa osoba dostanie burę na przeglądzie trzy tygodnie później. Baza danych tego nie przyjmie.

Drugi: klasa walidatora, gdy reguła jest zdaniem

Zwykłe reguły sprawdzają jedno pole względem stałej. Prawdziwe zasady domowe są zwykle warunkowe: to ma znaczenie tylko wtedy, gdy tamto. Do nich dziedziczysz po CustomValidator, nadpisujesz validate() i wywołujesz fail().

Wstawiłem trzy do modułu w /opt/netbox/netbox/house_rules.py:

from extras.validators import CustomValidator


class BillableKitNamesItsCustomer(CustomValidator):
    """Anything in a role we sell has to say whose it is."""
    BILLABLE_ROLES = {'hypervisor'}

    def validate(self, instance, request):
        role = getattr(instance, 'role', None)
        if role and role.slug in self.BILLABLE_ROLES and not instance.tenant:
            self.fail(
                f"A {role} is billable kit, so it must name the customer it belongs to.",
                field='tenant',
            )


class RackedDeviceNeedsAPosition(CustomValidator):
    """A device in a rack with no rack unit is a device nobody can find."""
    def validate(self, instance, request):
        if instance.rack and instance.position is None:
            if instance.device_type and instance.device_type.u_height:
                self.fail(
                    "A device in a rack needs a rack unit. Somebody has to find it.",
                    field='position',
                )


class CustomerPrefixNeedsATenant(CustomValidator):
    """A customer prefix that names no customer cannot be billed."""
    def validate(self, instance, request):
        role = getattr(instance, 'role', None)
        if role and role.slug == 'customer' and not instance.tenant:
            self.fail(
                "A customer prefix must be assigned to a tenant.",
                field='tenant',
            )

i podpiąłem je przez ścieżkę z kropkami:

CUSTOM_VALIDATORS = {
    'dcim.device': (
        {'name': {'regex': r'^[a-z0-9]+-[a-z]+-([0-9]{2}|[a-z])$'}},
        'house_rules.BillableKitNamesItsCustomer',
        'house_rules.RackedDeviceNeedsAPosition',
    ),
    'ipam.prefix': (
        'house_rules.CustomerPrefixNeedsATenant',
    ),
}

Zwróć uwagę, że model przyjmuje krotkę walidatorów, zwykłe reguły i klasy wymieszane dowolnie, i wszystkie się uruchamiają. Nawet pojedynczy walidator trzeba podać jako obiekt iterowalny, a na tym łatwo stracić pięć minut.

Potem reguły robią, co mówią:

POST a hypervisor with no tenant
  {"tenant": ["A Hypervisor is billable kit, so it must name
              the customer it belongs to."]}

POST a device into a rack with no position
  {"position": ["A device in a rack needs a rack unit.
                Somebody has to find it."]}

POST a prefix with role "customer" and no tenant
  {"tenant": ["A customer prefix must be assigned to a tenant."]}

POST a leaf switch with no tenant
  accepted, because a leaf switch is not in BILLABLE_ROLES

Ponieważ fail() przyjmuje field, komunikat ląduje przy właściwym polu formularza, a nie na górze strony, i to jest różnica między regułą, której ludzie się uczą, a regułą, której nie znoszą.

To jest też odpowiedź na lukę z rozdziału o własnych obiektach. Tamta walidacja istniała tylko w formularzu webowym. CustomValidator działa w warstwie modelu, więc obejmuje interfejs, REST API, mutacje GraphQL, importy masowe i wszystko, co robi skrypt. Jest jedno miejsce, w którym piszesz regułę, i nie ma jak jej obejść.

Trzeci: reguły ochrony, przy usuwaniu

CUSTOM_VALIDATORS pilnuje zapisów. PROTECTION_RULES pilnuje usunięć i przyjmuje dokładnie te same dwie formy.

PROTECTION_RULES = {
    'dcim.device': (
        {'status': {'eq': 'offline'}},
    ),
}

To mówi, że urządzenie można usunąć tylko wtedy, gdy jest offline. Co daje:

DELETE an active device
  {"detail": "Deletion is prevented by a protection rule:
              [\"Custom validation failed for status:
                ['Ensure this value is equal to offline.']\"]"}

set it to offline, then DELETE
  204 No Content

Dwa naciśnięcia klawiszy oporu między kimś a działającym urządzeniem, i to najtańsze ubezpieczenie w całej aplikacji. Niech proces wycofywania z eksploatacji będzie tym, co odblokowuje przycisk usuwania.

Ta, która cię złapie

Istniejące dane nie są sprawdzane, dopóki ich następnym razem nie dotkniesz. Dodanie reguły nie wraca i nie waliduje tego, co już jest. Siedzi cicho, aż ktoś zapisze obiekt, który ją łamie, a wtedy dostaje błąd o decyzji, z którą nie miał nic wspólnego.

Widziałem, jak to się dzieje. mcr1-hv-06 został utworzony, zanim napisałem cokolwiek z tego, jako hiperwizor bez dzierżawcy. Siedział tam całkiem zadowolony. Potem zmieniłem mu opis:

PATCH {"description": "touching it to trigger revalidation"}
  {"tenant": ["A Hypervisor is billable kit, so it must name
              the customer it belongs to."]}

Edycja nie miała nic wspólnego z dzierżawcą. Reguła i tak się odpaliła, bo walidacja działa na całym obiekcie.

To poprawne zachowanie i zarazem sposób, w jaki nowa reguła zamienia się w zgłoszenie do wsparcia. Zanim ją włączysz, puść zapytanie o obiekty, które by jej nie przeszły, i najpierw je popraw. API to ułatwia: reguła jest filtrem, więc poproś o urządzenia z tą rolą i bez dzierżawcy, i masz swoją listę.

Regułę włącz potem. Wtedy łapie już tylko nowe błędy, a po to jest.

Sterowanie z Ansible

Źródło prawdy, którego nic nie czyta, zgnije. Kolekcja netbox.netbox to sposób, w jaki większość ludzi temu zapobiega, i działa w obie strony: NetBox mówi Ansible, co istnieje, a Ansible mówi NetBoxowi, co zbudował.

Jest w wersji 3.23.0, na licencji GPL-3.0, i pobrano ją z Galaxy ponad 13,4 mln razy. Zawiera 91 modułów i jedną wtyczkę inwentarza.14 Wszystko poniżej zostało uruchomione na tej samej instancji, z kontenera, w którym nie było nic poza ansible-core 2.21.4, pynetbox 7.8.0 i kolekcją.

Inwentarz jest zapytaniem, a nie plikiem

To jest połowa, która zwraca się pierwszego popołudnia. nb_inventory buduje twój inwentarz Ansible bezpośrednio z NetBoxa:

plugin: netbox.netbox.nb_inventory
api_endpoint: http://netbox:8080
token: "{{ lookup('env', 'NETBOX_TOKEN') }}"
config_context: false
group_by:
  - sites
  - device_roles
  - tenants
  - racks
device_query_filters:
  - has_primary_ip: true

To daje taki wynik, bez nikogo, kto utrzymuje listę hostów:

@sites_manchester-dc1:      @device_roles_hypervisor:
  |--mcr1-core-01             |--mcr1-hv-01
  |--mcr1-core-02             |--mcr1-hv-02
  |--mcr1-hv-01               |--mcr1-hv-03
  |--mcr1-hv-02               |--mcr1-hv-04
  ...                         |--mcr1-hv-05
@racks_MCR1-A07:            @tenants_ravenscroft-legal:
  |--mcr1-core-01             |--mcr1-hv-01
  |--mcr1-core-02             |--mcr1-hv-02
  ...                       @tenants_padgate-foods:
@device_roles_core-router:    |--mcr1-hv-03
  |--mcr1-core-01             |--mcr1-hv-04
  |--mcr1-core-02           @tenants_hartley-components:
                              |--mcr1-hv-05

Spójrz na prawą kolumnę. Ponieważ dzierżawa jest ustawiona na urządzeniach, dostajesz grupę na klienta za darmo, więc --limit tenants_ravenscroft-legal uruchamia play na sprzęcie dokładnie jednego klienta. Dodaj urządzenie w NetBoxie, a przy następnym uruchomieniu jest w grupie. Wycofaj jedno, a znika. Nikt niczego nie edytuje.

Każdy host przychodzi z tym, co NetBox o nim wie:

ansible_host     "2001:db8:20:20::11"
primary_ip4      "10.20.20.11"
primary_ip6      "2001:db8:20:20::11"
device_roles     ["hypervisor"]
sites            ["manchester-dc1"]
racks            ["MCR1-A07"]
tenants          ["ravenscroft-legal"]
device_types     ["sys-1029u-tn10rt"]
manufacturers    ["supermicro"]
status           {"label": "Active", "value": "active"}

Łącznie dwadzieścia dwa klucze, a jeden z nich warto zauważyć, zanim cię zaskoczy. ansible_host to adres IPv6, bo to urządzenie ma ustawiony główny adres v6. Sprawdziłem to na dwóch innych, które mają tylko v4, i wróciły z v4, więc reguła jest taka, że wtyczka woli v6 tam, gdzie istnieje główny v6. Co jest poprawne, a zarazem jest rzeczą, którą wolisz odkryć teraz niż wtedy, gdy będziesz się zastanawiać, czemu play łączy się ścieżką, o której nie pomyślałeś.

Zapis w drugą stronę

Moduły to drugi kierunek, a ten, który warto mieć, to przydzielanie adresów IP, bo NetBox wie, co jest wolne, a twój playbook nie.

- name: Rack the device
  netbox.netbox.netbox_device:
    netbox_url: "{{ nb_url }}"
    netbox_token: "{{ nb_token }}"
    data:
      name: mcr1-hv-07
      device_type: SYS-1029U-TN10RT
      device_role: Hypervisor
      site: Manchester DC1
      rack: MCR1-A07
      position: 14
      face: Front
      tenant: Hartley Components
    state: present

- name: Let NetBox pick the next free address out of the customer prefix
  netbox.netbox.netbox_ip_address:
    netbox_url: "{{ nb_url }}"
    netbox_token: "{{ nb_token }}"
    data:
      prefix: 10.20.22.0/24
      tenant: Hartley Components
      assigned_object:
        device: mcr1-hv-07
        name: eno1
    state: new

Zwróć uwagę, czego tam nie ma. Adresu IP. Podajesz prefiks, a NetBox oddaje następny wolny:

TASK [Let NetBox pick the next free address out of the customer prefix] ****
changed: [localhost]

"device   : mcr1-hv-07  (created)"
"interface: eno1  (created)"
"address  : 10.20.22.1/24  (allocated)"

I sekundę później jest w interfejsie, jeszcze do niczego niepodłączony kablem, ale zamontowany, przypisany do dzierżawcy i zaadresowany:

Zakładka interfejsów NetBox dla mcr1-hv-07, urządzenia utworzonego przez playbook, z jednym interfejsem eno1 typu SFP28 25GE opisanym jako do leaf-01 i z adresem 10.20.22.1/24

Pułapka w tym playbooku

Uruchom go drugi raz bez zmiany ani jednej linii, a stanie się to:

"device   : mcr1-hv-07  (already correct)"
"interface: eno1  (already correct)"
"address  : 10.20.22.2/24  (allocated)"

Urządzenie i interfejs są idempotentne. Adres nie jest, i to nie jest błąd. state: present znaczy „niech to wygląda tak”. state: new znaczy „daj mi nowy”, za każdym razem, i dokładnie to zrobił: dwa adresy na jednym interfejsie po dwóch uruchomieniach.

To w porządku, gdy naprawdę przygotowujesz coś nowego, i po cichu zje ci prefiks, jeśli wstawisz to do zadania uruchamianego co noc. Przydziel raz i zapisz wynik albo użyj state: present z adresem, który już masz. Moduł robi to, o co prosiłeś. Pytanie brzmi, czy prosiłeś o to, o co ci chodziło.

To nie tylko Ansible

Kolekcja zbiera uwagę, bo Ansible to miejsce, gdzie większość zespołów sieciowych już jest, ale produktem jest API, a mówi nim mnóstwo rzeczy.

RzeczCzym jestLicencja
pynetboxKlient Pythona, którego używa sama kolekcjaApache 2.0
terraform-provider-netboxZarządzanie obiektami NetBoxa jako zasobami Terraform, aktywnie utrzymywane przez e-breuningerMPL 2.0
nornir_netboxNetBox jako inwentarz Nornira, dla ludzi piszących w Pythonie zamiast YAMLApache 2.0
Prometheus SDPodaje Prometheusowi cele do odpytywania z NetBoxaMIT
go-netboxKlient w Go, choć nikt go nie ruszał od maja 2025zobacz repozytorium
DiodeWłasny potok NetBox Labs do wpychania wykrytych danychNetBox Limited Use

Ten od Terraform to ciekawa pozycja dla każdego, kto już tak zarządza infrastrukturą, bo pozwala jednemu planowi utworzyć zasób w chmurze i rekord w NetBoxie, który go dokumentuje, zamiast zostawiać drugą połowę czyjejś pamięci.15

Diode ma tę samą licencję co Branching i Custom Objects, więc ta sama lektura obowiązuje, zanim coś na nim zbudujesz.

Co naprawdę kupuje to popołudnie

Wszystko powyżej zajęło mi dzień na jednej maszynie, a większość tego dnia to było wprowadzanie danych, żeby ekrany miały co pokazać. Instalacja to dwadzieścia minut tak czy inaczej. Liczą się decyzje i wszystkie zapadają w pierwszej godzinie: dzierżawcy przed wszystkim, typy urządzeń przed urządzeniami, liczby na typach, a nie na sprzęcie.

To, co za to dostajesz, nie jest dokumentacją. Nikt nie robi tego rozróżnienia, dopóki nie miał obu: dokumentacja to coś, co piszesz, a potem przestajesz utrzymywać. Dostajesz bazę danych, która odmawia przechowania sprzeczności: nie pozwoli ci wstawić dwóch rzeczy w jedną jednostkę szafy, szafy w pomieszczenie należące do innej lokalizacji ani urządzenia na typie, który nie istnieje. Każda z tych odmów to kłótnia, której nie będziesz mieć za pół roku.

I powie ci rzeczy, o które nikt nie pytał. Ta szafa jest zapełniona w 28,6% sprzętem i w 90,7% mocą. Nikt nie wyruszył, żeby to znaleźć. Wypadło to z jednorazowego wpisania mocy na typie urządzenia i to jest różnica między zamontowaniem tam następnego zamówienia a przekonaniem się na własnej skórze.

Uczciwe zastrzeżenie jest to samo, które ma każde źródło prawdy. Jest warte tylko tyle, ile kosztuje cię utrzymanie go w poprawności, a jedyna wersja, która przetrwa pracowity kwartał, to ta, w której coś widocznie się psuje, gdy dane są błędne. Podepnij monitoring, provisioning albo reguły firewalla tak, żeby z niego czytały, a błędny wpis przestaje być problemem z dokumentacją, którym ktoś się kiedyś zajmie. Staje się awarią o wpół do dziesiątej we wtorek, z nazwiskiem przy niej. Brzmi jak koszt. To cały mechanizm.

Nikt ci też za to nie podziękuje. Poprawny zapis widać jako migrację, która zajęła dwa tygodnie zamiast kwartału, audyt, który zajął popołudnie, klienta, który dostał przez telefon prostą odpowiedź. Nic z tego nie pojawia się w raporcie obok twojego nazwiska.

I tak to zrób. Alternatywą jest firma, która nie potrafi opisać samej siebie, a firma, która nie potrafi opisać samej siebie, nie jest prowadzona. Jest pamiętana, przez coraz mniej ludzi każdego roku.


  1. NetBox, Introduction — „Today, the open source project is stewarded by NetBox Labs and a team of volunteer maintainers”, oraz początki w DigitalOcean w 2015, udostępnienie jako open source w czerwcu 2016. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  2. NetBox, LICENSE.txt — Apache License 2.0, copyright DigitalOcean, LLC. Pochodzenie i opieka nad projektem według wprowadzenia. ↩︎ ↩︎

  3. Notatki do wydania Nautobot v1.0.0 — „a divergent fork of NetBox 2.10”, opublikowane 26 kwietnia 2021, oraz lista tego, co dodał względem NetBox 2.10. ↩︎ ↩︎

  4. Network to Code, “Why Did Network to Code Fork NetBox?”, 25 lutego 2021 — uzasadnienie SLA i wsparcia długoterminowego, rozbieżność wizji oraz „the NetBox project team suggested that we should consider forking”. ↩︎

  5. NetBox Labs powstał w 2023 roku jako spółka wydzielona z NS1 po jej przejęciu przez IBM, współzałożony przez głównego maintainera NetBoxa Jeremy’ego Stretcha, i w kwietniu 2023 ogłosił rundę Series A na 20 mln $: NetBox Labs, “Let’s Go: Announcing NetBox Labs” oraz ogłoszenie Series A. ↩︎

  6. NetBox Labs, NetBox Enterprise — komercyjna edycja do samodzielnego hostowania, z „24/7 expert assistance from the NetBox Labs team”; NetBox Cloud to oferta hostowana. Konkretne warunki SLA nie są na tej stronie opublikowane. ↩︎

  7. Liczby gwiazdek i forków, daty wydań i licencje obu projektów odczytane z API GitHuba 30 września 2026: netbox-community/netbox i nautobot/nautobot. Równoległe wydania Nautobota 3.2.x i 2.4.x mają obie datę 28 września 2026. ↩︎

  8. netbox-community/netbox-docker — stos kontenerów społeczności, Apache 2.0. ↩︎

  9. NetBox, Installation — tabela wspieranych wersji oraz notatki do wydania v4.7 z podniesionymi minimami PostgreSQL i Redisa. Wersja i edycja odczytane z netbox/release.yaml. ↩︎

  10. NetBox Limited Use License 1.0 — dołączona do netbox-custom-objects i, w identycznym brzmieniu, do netbox-branching. Obie cytowane klauzule są dosłowne. ↩︎

  11. NetBox, HTTP Server installation, “What’s Next?” — „Some of the most popular plugins include” NetBox Branching, NetBox Custom Objects, NetBox DNS i NetBox BGP, bez wzmianki o warunkach licencji. ↩︎

  12. NetBox, Data Validation configuration — FIELD_CHOICES i przyrostek ze znakiem plus, który rozszerza zamiast zastępować: „To replace the available choices, specify the app, model, and field name separated by dots … To extend the available choices, append a plus sign”. ↩︎

  13. Dokumentacja netboxlabs/netbox-custom-objects — „Deleting a Custom Object Type drops an entire database table and should be done with caution.” ↩︎

  14. netbox.netbox w Ansible Galaxy i netbox-community/ansible_modules — wersja 3.23.0, GPL-3.0, 91 modułów plus wtyczka inwentarza nb_inventory. Liczba pobrań odczytana z Galaxy 30 września 2026. Wszystko pokazane zostało uruchomione z ansible-core 2.21.4 i pynetbox 7.8.0. ↩︎

  15. Licencje, aktywność i liczby gwiazdek odczytane z każdego projektu 30 września 2026: pynetbox (Apache 2.0), terraform-provider-netbox (MPL 2.0, v6.0.0-rc.1 w rejestrze Terraform), nornir_netbox (Apache 2.0), netbox-plugin-prometheus-sd (MIT), go-netbox (ostatni push 9 maja 2025) oraz Diode, który ma tę samą NetBox Limited Use License 1.0 co Branching i Custom Objects. ↩︎