Tudo neste artigo foi corrido contra um NetBox 4.7.2 na minha própria secretária, com um parque real carregado lá dentro: um local, um armário, catorze equipamentos, cablados, alimentados e endereçados entre três clientes. Cada captura de ecrã é essa instância, e cada mensagem de erro é uma que eu recebi de facto.

Segue a ordem pela qual o vais encontrar. O que a coisa é, porque havias de querer uma, o fork de que vais ouvir falar ao fim de uma semana de pesquisas, como levantar uma, a ordem pela qual tens de a preencher, e depois o que tiras de lá. O trabalho de personalização e extensão fica para o fim, porque nada disso faz sentido antes de teres visto a forma daquilo que estás a estender.

O que é o NetBox

O NetBox é uma base de dados com uma opinião muito concreta sobre aquilo de que uma rede é feita, e uma aplicação web por cima dela. É uma aplicação Django sobre PostgreSQL, é open source sob Apache 2.0 desde que a DigitalOcean a lançou em junho de 2016, e o projeto é hoje gerido pela NetBox Labs em conjunto com uma equipa de mantenedores voluntários.12

Por baixo disso são 149 modelos repartidos por dez aplicações, alcançados através de 146 endpoints REST e um endpoint GraphQL. Contados na instância que construí para isto, e não lidos numa página de funcionalidades:

AplicaçãoModelosAplicaçãoModelos
dcim56virtualization7
extras23tenancy6
ipam18wireless3
circuits11users7
vpn10core8

Cinquenta e seis deles são DCIM, a camada física: locais, localizações, bastidores, tipos de equipamento, equipamentos, e todo o tipo de porta, baía e terminação de cabo que um equipamento pode ter. Dezoito são IPAM. O resto cobre circuitos, túneis e políticas IKE, máquinas virtuais e clusters, ligações sem fios, tenancy, e a maquinaria que torna tudo extensível.

A contagem não é o que interessa. As ligações entre os dados é que são, e a maneira mais rápida de o ver é o ecrã pelo qual o NetBox é mais conhecido.

Começa pelo armário, porque é o ecrã que vende a coisa.

Página de detalhe do bastidor MCR1-A07 no NetBox, com a região North West, o local Manchester DC1, a localização Hall 2, o estado Active e 28,6% de utilização de espaço à esquerda, e à direita as elevações frontal e traseira com painéis de patch em U41 e U42, dois routers em U38 e U39, dois switches em U35 e U36, e seis hipervisores entre U15 e U20, cada um colorido pela sua função

Aquela elevação é desenhada a partir dos dados, não carregada como imagem. Cada equipamento está lá porque alguma coisa diz que ocupa aquelas unidades de bastidor, virado para aquele lado, e as cores vêm da função que lhe deste. A utilização de espaço diz 28,6% porque o NetBox fez as contas. Ninguém mantém esse número.

Daí seguem-se duas coisas que valem mais do que a imagem.

Podes perguntar que unidades estão livres, e obter uma resposta com a qual podes agir. Também podes reservar unidades antes de lá estar instalada qualquer coisa, que é a diferença entre vender espaço que tens e vender espaço que achas que tens.

O que se recusa deliberadamente a fazer

Um produto que sabe o que não é é mais raro do que um que faz tudo mal, e a própria documentação do NetBox é direta quanto a isso. Não faz monitorização de rede, serviço de DNS, RADIUS, gestão de configuração nem gestão de instalações.1

Mais importante ainda, guarda o estado desejado da tua rede, não o seu estado operacional, e a documentação diz que a importação automática do estado real da rede é «strongly discouraged», porque cada registo deve ser verificado primeiro por uma pessoa.1

É essa a decisão sobre a qual assenta tudo o resto, e é a que as pessoas contestam. O argumento é este: uma fonte de verdade devia ser a verdade, portanto descobre a rede e carrega-a lá para dentro. A resposta é que uma rede descoberta diz-te o que lá está, e o que lá está inclui todos os erros que alguém alguma vez fez. Uma porta de switch deixada na VLAN errada em 2021 é um facto. Não é uma intenção.

O NetBox guarda a intenção. A tua monitorização guarda a realidade. O número interessante é a diferença entre as duas, e não se calcula uma diferença a partir de um só valor.

O outro princípio é dito com a mesma clareza: entre uma solução relativamente simples que resolve oitenta por cento e uma completa muito mais complexa, escolhe a simples.1 Vais senti-lo da primeira vez que quiseres modelar uma coisa que ele não modela, e há toda uma série de secções perto do fim sobre o que fazer quando bateres nisso.

O NetBox fazO NetBox não faz
Registar o que devia lá estarInterrogar o que lá está
Guardar a VLAN pretendida para uma portaDizer-te que a porta está em baixo
Dizer a que cliente pertence um prefixoFaturar-lho
Gerar a configuração de um equipamento a partir de um modeloEnviá-la para o equipamento
Seguir o circuito, o fornecedor e o compromissoMonitorizar o circuito
Dizer em que bastidor está um equipamento, e em que UAbrir o armário

Lê a coluna da direita como uma lista de ferramentas de que ainda precisas. Lê-a mal e vais tentar transformar o NetBox em todas elas, que é como uma fonte de verdade se torna mais um sistema em que ninguém confia.

Porque precisas de um

Pergunta a um prestador de serviços geridos onde vive o registo oficial da rede de um cliente, e vais obter uma resposta. Pergunta a dois dos seus engenheiros em separado e vais obter duas.

Um vai apontar para uma folha de cálculo. Outro vai apontar para um diagrama gravado pela última vez por alguém que saiu em 2023. Mais alguém vai dizer que a configuração da firewall é a documentação, o que pelo menos é honesto, porque uma configuração descreve de facto o que uma caixa está a fazer. Só não descreve porquê, nem quem o pediu, nem qual dos quatro clientes atrás daquela caixa está a pagar pela regra.

A falha nunca é o dia em que reparas que o registo está errado. É o dia em que alguém precisa dele.

O momentoO que tens de apresentarO que custa quando não consegues
Uma conversa de renovaçãoUma conta detalhada do que a mensalidade compraA proposta do concorrente vem detalhada, porque eles foram contar
Um engenheiro apresenta a demissãoTudo o que ele sabia, por escritoSeis meses a descobrir, um ticket de cada vez
Um cliente vai-se emboraUma descrição do seu próprio parqueTrês semanas a montá-la, e uma referência que ele vai dar com honestidade
Um auditor faz uma pergunta de âmbitoQue sistemas guardam dados pessoais, e onde estão fisicamenteUm regulador a quem foi dito algo que depois se revela falso
Uma migração precisa de orçamentoUma contagem do que lá está realmenteLicitas sobre uma estimativa e comes a diferença

Nada disto é exótico. É uma terça-feira qualquer.

O que tiras disto não é documentação. Documentação é uma coisa que escreves e depois deixas de manter. O que tens é uma base de dados que se recusa a guardar uma contradição, e que responde a perguntas que ninguém pensou em fazer-lhe de antemão. Há um armário mais abaixo neste artigo que afinal está 28,6 por cento cheio de equipamento e 90,7 por cento cheio de energia. Ninguém foi à procura disso. Saiu de se ter introduzido uma potência num tipo de equipamento uma vez.

A ressalva honesta vem junto, e a última secção é sobre ela. Um registo só vale aquilo que te custa mantê-lo certo. Mas a alternativa é uma empresa que não se consegue descrever a si própria, e a primeira pessoa a descobri-lo costuma ser um cliente.

O outro: Nautobot

Vais dar com isto ao fim de mais ou menos uma semana de pesquisas, por isso vale a pena saber o que aconteceu.

Em 2021, a Network to Code fez um fork do NetBox e chamou ao resultado Nautobot. Não um fork suave nem uma distribuição: um fork a sério que diverge há cinco anos. As notas da sua própria versão v1.0 descrevem-no como «a divergent fork of NetBox 2.10», o repositório foi criado a 19 de fevereiro de 2021 e a v1.0.0 saiu a 26 de abril de 2021.3

As razões que apresentaram estão no blogue deles e vale a pena lê-las nas palavras deles e não nas minhas. Foram três as coisas que o motivaram. Queriam vender suporte empresarial: «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.» Queriam que a fonte de verdade ficasse no centro de uma plataforma de automação em vez de servir de documentação. E «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

Essa primeira razão precisa da data agarrada, porque deixou de ser verdade. Em fevereiro de 2021 não havia nenhuma empresa por trás do NetBox para te vender o que quer que fosse. A NetBox Labs só foi fundada em 2023, separada da NS1 depois de a IBM a ter comprado, e cofundada pelo próprio mantenedor principal do NetBox.5

E não é um terceiro que montou um negócio em cima do projeto de outra pessoa. A NetBox Labs é a guardiã do NetBox: a própria documentação do projeto diz que «the open source project is stewarded by NetBox Labs and a team of volunteer maintainers».1 Vendem o NetBox Enterprise para instalações autogeridas, alojam-no por ti como NetBox Cloud, e oferecem suporte 24/7.6

Portanto «não consegues comprar suporte para o NetBox» era uma coisa justa de dizer quando a Network to Code fez o fork, e não é uma coisa justa de dizer agora. Os dois projetos têm uma empresa comercial por trás que assina um contrato, e no caso do NetBox essa empresa é a que gere o projeto.

A frase que a maioria das pessoas não vê é a seguinte, e é a razão pela qual esta não é uma história sórdida: «the NetBox project team suggested that we should consider forking.»

É mais ou menos o mais civilizado que um fork consegue ser. Dois grupos queriam coisas diferentes, disseram-no durante muito tempo, e separaram-se em vez de lutarem por um só código-fonte. As duas metades continuam a ser Apache 2.0. Ninguém levou nada a que não tivesse direito.

Para que servia realmente o fork

As notas da versão 1.0 do Nautobot listam o que acrescentou em relação ao NetBox 2.10, e a lista explica a discussão melhor do que qualquer artigo de blogue:3

O que o Nautobot acrescentou em 2021Onde está o NetBox agora
Suporte para GraphQLO NetBox tem
Integração com Git como fonte de dadosO NetBox tem, como fontes de dados sincronizadas
Single sign-onO NetBox tem
SegredosO NetBox tem, através de um plugin
Scripts e relatórios consolidados em JobsO NetBox vai passar os scripts para um plugin na 4.7
Custom fields em todos os modelosO NetBox tem um suporte alargado de custom fields
API de plugins para validação de dadosO NetBox tem regras de validação personalizadas
Estados personalizáveis, como objetos na base de dadosOs estados do NetBox continuam a ser um choice set em Python
Relações definidas pelo utilizador entre modelosO NetBox não tem equivalente
Chaves primárias UUIDO NetBox usa chaves inteiras
Melhorias na API de pluginsA framework de plugins do NetBox cresceu muito desde então

A maior parte da metade de cima convergiu. Várias coisas que o Nautobot lançou em 2021 chegaram depois ao NetBox, que é o que costuma acontecer quando dois projetos estão a resolver os mesmos problemas em público.

As três de baixo não convergiram, e são de arquitetura e não de cosmética. Verifiquei os dois códigos-fonte hoje em vez de confiar nas notas de 2021.

O Status do Nautobot é um modelo da base de dados, descrito no seu próprio código como «Model for database-backend enum choice objects», portanto um estado é uma linha que alguém pode acrescentar na interface. Os estados do NetBox vêm de um choice set em Python, que é a razão pela qual a secção FIELD_CHOICES mais abaixo acrescenta um editando o configuration.py e reiniciando. O Nautobot tem os modelos Relationship e RelationshipAssociation, por isso podes definir uma relação entre dois tipos de objeto existentes sem escrever código. A resposta do NetBox a esse problema é um plugin, que tem direito a uma série de secções próprias mais abaixo. E as chaves primárias do Nautobot são UUIDs, enquanto as do NetBox são inteiros.

Também fizeram aquilo para que fizeram o fork. Neste momento o Nautobot está a publicar a 3.2.x e a 2.4.x no mesmo dia, o que é uma verdadeira linha de manutenção a longo prazo a correr ao lado da atual, e essa era uma das três razões apresentadas.

Qual escolher

Primeiro os números honestos. O NetBox tem 21 625 estrelas e 3133 forks; o Nautobot tem 1617 e 422.7 Ambos receberam commits nos últimos dois dias, ambos são Apache 2.0, e ambos têm agora uma empresa comercial por trás a vender suporte e alojamento.

Essa diferença não é um veredicto sobre a qualidade. Reflete cinco anos de avanço e o facto de a maioria das pessoas que precisa de uma fonte de verdade encontrar primeiro o NetBox. Mas decide aquilo que normalmente importa mais do que as funcionalidades, que é quantos plugins, integrações, módulos Ansible, respostas em fóruns e colegas vais encontrar para aquele que escolheres.

Portanto: se queres um inventário e uma fonte de verdade que outros sistemas leem, e queres o maior ecossistema e a contratação mais fácil, a resposta é o NetBox, e é disso que trata o resto deste artigo. Se a tua razão para quereres uma fonte de verdade é especificamente conduzir automação a partir dela, ou queres estados e relações definidos pela tua equipa e não por um ficheiro de configuração e um reinício, vai ver o Nautobot com atenção antes de decidires.

Não deixes ninguém vender-te nenhum dos dois só pelo suporte. Os dois lados já têm isso coberto, e as diferenças que ainda lá vão estar daqui a cinco anos são as da tabela acima.

O que não deves fazer é escolher um porque alguém te disse que o outro está morto. Nenhum está, e os dois ainda lançaram versões esta semana.

Pôr um a funcionar

Dois caminhos, e corri os dois para isto. Contentores se o queres a funcionar em vinte minutos, pacotes num host se vai ter de aguentar peso.

A pilha de contentores

A comunidade mantém o netbox-docker, que é a resposta rápida: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

Isso dá-te a aplicação, o PostgreSQL, o Redis e um worker em segundo plano, ligados entre si. Construí a mesma coisa à mão com podman para poder ver as peças, e vale a pena conhecer as peças porque duas delas apanham as pessoas:

ContentorO que fazSe o deixares de fora
netboxA aplicação Django atrás do gunicornnada funciona
postgresA base de dados, 15 ou posteriornada funciona
redis / valkeyDuas bases de dados: uma para tarefas, outra para cachenada funciona
netbox-workerrqworker, que esvazia a fila de tarefasos webhooks nunca disparam, as tarefas em segundo plano nunca correm, e nada te avisa
netbox-housekeepingA arrumação periódicaos registos do change log nunca expiram

A quarta linha é que é. Sem um worker, tudo parece saudável. As event rules ficam em fila e ficam por lá.

Duas coisas morderam-me na primeira execução e nenhuma delas aparece numa mensagem de erro que fosses pesquisar.

A primeira migração demora muito. Não um minuto. Nesta máquina foram vários, porque o NetBox 4.7 substitui o django-mptt pelo ltree do PostgreSQL e reconstrói todas as tabelas hierárquicas pelo caminho. O contentor fica simplesmente parado a aplicar migrações. Deixa-o estar.

Sem API_TOKEN_PEPPERS não consegues criar um token de API v2, e o único sinal é um aviso no log:

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

Define pelo menos um, com pelo menos cinquenta caracteres, antes de ires à procura do porquê de a API te rejeitar.

Num host, a partir dos pacotes

O caminho documentado é testado em Ubuntu 24.04. Corri-o de ponta a ponta num limpo, e foi nisto que deu:

ComponenteO que o 24.04 me deuO que o NetBox 4.7 precisa
PostgreSQL16.1515 ou posterior
Redis7.0.156.0 ou posterior
Python3.12.33.12, 3.13 ou 3.14
Django6.1.1vem com o NetBox
NetBoxv4.7.2

Esses mínimos são do próprio NetBox, e a 4.7 subiu tanto o mínimo do PostgreSQL como o do Redis.9

O trabalho todo são cinco passos.

# 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

Esses cinco valores são ALLOWED_HOSTS, DATABASES, REDIS, SECRET_KEY e API_TOKEN_PEPPERS. Gera os dois últimos em separado e não reutilizes um para o outro. Assim sendo, corre o gerador de chaves duas vezes e cola os resultados em linhas diferentes.

O upgrade.sh constrói o ambiente virtual, instala todas as dependências Python, corre as migrações, constrói a documentação para uso offline e recolhe os ficheiros estáticos. Quando acaba numa máquina nova, imprime um aviso que parece alarmante e não é:

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.)

Depois um superutilizador, e está a correr:

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

Para qualquer coisa a sério, põe o gunicorn à frente em vez do runserver. A configuração e os ficheiros de unidade já estão no repositório, que é o pormenor que vale a pena saber, porque há quem escreva os seus:

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

O netbox.service corre o gunicorn em 127.0.0.1:8001, o netbox-rq.service corre o worker, e o nginx ou o Apache vão à frente para terminar o TLS e servir o /static. Dois serviços, e o segundo é o mesmo worker de que a pilha de contentores precisa.

A ordem pela qual o tens de preencher

Um NetBox acabado de instalar é uma base de dados vazia com opiniões, e a primeira hora com um costuma ser passada a descobrir que opiniões são essas. Vais acrescentar um equipamento, e ele não te deixa.

Formulário Add a new device do NetBox, com Name, Device role marcado com um asterisco vermelho, Description e Tags sob o título Device, depois Device type também marcado com um asterisco vermelho sob Hardware, seguido de Serial number, Asset tag, Cooling method e Airflow

Aqueles asteriscos vermelhos são a lição toda. O NetBox não regista uma coisa antes de existirem as coisas de que ela depende, e não está a ser picuinhas: um equipamento sem tipo é uma linha que não consegue responder a nenhuma das perguntas para que um equipamento serve.

Por isso, em vez de adivinhar, perguntei ao modelo que chaves estrangeiras são de facto obrigatórias, e depois tentei partir cada regra através da API para ver o que voltava.

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."]}

Todos recusaram, e disseram exatamente o que faltava. Aqui está a mesma informação como lista de pré-requisitos:

Para criarObrigatório antesOpcional, mas queres antes
Tenantnadaum Tenant group
Region, Site groupnadaum pai do mesmo tipo, aninham-se
Sitenadauma Region, um Site group, um Tenant
Locationum Siteuma Location pai, um Tenant
Rack typeum Manufacturer
Rackum Siteuma Location, Rack group, Rack role, Rack type, Tenant
Device typeum Manufacturer
Device rolenadaum Device role pai, aninham-se
Deviceum Device role, um Device type, um Siteum Rack e uma posição, uma Platform, um Tenant
Interface, e qualquer outro componenteum Device
Cableduas coisas onde terminarum Tenant
Aggregateum RIRum Tenant
VLANnadaum VLAN group, um Role, um Tenant
Prefixnadaum Site, uma VLAN, um Role, uma VRF, um Tenant
IP addressnadauma Interface a que o atribuir, um Tenant
Circuitum Provider e um Circuit typeum Tenant
Circuit terminationum Circuitum Site onde chegar
Clusterum Cluster typeum Cluster group, um Site, um Tenant
Virtual machineum Site, um Cluster ou um Deviceuma Platform, um Tenant
VM interfaceuma Virtual machine

A segunda coluna é a que te sai cara. Prefixos, endereços IP, VLANs e tenants não exigem nada, por isso nada te impede de os criar no primeiro dia pela ordem que te apetecer. Se servem para alguma coisa é outra questão, porque um endereço sem interface por trás é uma linha numa lista, e um equipamento sem tenant é um equipamento que vais voltar a editar mais tarde.

A ordem pela qual trabalhar de facto

Isso dá uma sequência. Segue-a de cima para baixo e nada te vai recusar.

Primeiro, as coisas de que tudo o resto depende. Nenhuma delas é empolgante e todas são baratas de errar.

  1. Tenant groups, depois tenants. Faz estes antes de tudo o resto. Vinte e oito modelos aceitam um tenant, incluindo Site, Location e Rack, por isso se os clientes ainda não existirem não os consegues carimbar à medida que avanças e vais andar a editar em massa mais tarde.
  2. Regions e site groups. Ambos opcionais, ambos se aninham dentro de si próprios, e são independentes um do outro. As regions são para a geografia, os site groups para a função, e podes usar um, os dois ou nenhum.
  3. Sites. A raiz de quase tudo. Um site não exige nada, e é por isso que é a primeira coisa que consegues realmente criar.
  4. Locations. Precisam de um site, e aninham-se, por isso um pavilhão com filas que contêm pods é um único modelo com três níveis.
  5. Rack roles e rack groups. Ambos opcionais. Os rack groups são planos e ficam ao lado das locations como um segundo eixo, o que dá jeito para filas e pods.
  6. Manufacturers, depois rack types. Um rack type precisa de um manufacturer. Salta os rack types se não estiveres a modelar os próprios armários.
  7. Racks. Precisam de um site. Se também lhes deres uma location, essa location tem de pertencer a esse site, e o NetBox verifica.

Depois o catálogo de hardware, não o hardware. Antes de poderes acrescentar um único equipamento precisas de manufacturers, device types, device roles e, na prática, platforms.

  1. Manufacturers. Pode ser que já tenhas alguns do passo 6, porque os rack types também precisam deles. Os module types também.
  2. Device types, cada um a precisar de um manufacturer.
  3. Device roles, que se aninham, e platforms.

Este é o passo que as pessoas saltam, e é o passo que decide quanto vais escrever no resto do trabalho. Um device type traz as suas próprias interfaces, portas e baías como modelos, por isso cada equipamento que crias a partir dele chega já com os componentes certos. Acerta no tipo uma vez e montar quarenta deles são quarenta nomes.

A platform é a exceção nessa lista, porque um equipamento não precisa estritamente de uma. Faz já de qualquer maneira. É ela que vai levar o config template e o driver NAPALM mais tarde, e voltar atrás para a definir num parque inteiro é o mesmo serão que terias gasto com os tenants.

Depois o equipamento propriamente dito.

  1. Devices. Role, type e site são todos obrigatórios. Rack e posição são opcionais, e se os deres têm de ser coerentes com o site.
  2. Componentes, se o device type não os tiver já fornecido.
  3. Cabos, entre os componentes.

Depois o endereçamento, porque um endereço quer uma interface onde viver e a interface só existe depois do passo 12.

  1. RIRs, depois aggregates.
  2. Roles de prefixo e de VLAN, VRFs, VLAN groups e depois VLANs.
  3. Prefixos, depois os endereços IP individuais.

Depois a camada comercial.

  1. Providers, provider accounts e circuit types.
  2. Circuits, depois termina-os em sites.

E o parque virtual, que espelha o físico.

  1. Cluster types e cluster groups, depois clusters.
  2. Virtual machines, que precisam de um site, de um cluster ou de um device, e depois as suas interfaces.

Os passos 1 a 10 são uma tarde e parecem trabalho administrativo. Não há nada de glamoroso em nenhum deles. São também a tarde que decide se o passo 11 leva uma manhã ou quinze dias.

As regras que mordem mais tarde

Os campos obrigatórios são a metade fácil, porque falham logo e dizem-te porquê. As que apanham as pessoas desprevenidas são as regras de coerência, que só disparam quando já tens dados suficientes para te contradizeres:

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)"]}

Essa última é a que eu apontaria se alguém perguntasse para que serve isto tudo. O NetBox sabe que o equipamento tem 1U, sabe o que está no armário, e não te deixa registar duas coisas no mesmo espaço. A tua folha de cálculo deixa-te fazer isso a tarde inteira sem dizer uma palavra, e vais descobrir quando alguém estiver no pavilhão com uma caixa nas mãos.

Nenhuma destas é configurável e nenhuma devia ser. São a diferença entre um registo e um desejo.

Usá-lo: o que te dá cada ecrã

Com o parque carregado, eis o que tiras realmente de lá. Tudo o que se segue é a mesma instância: um armário, catorze equipamentos, cablados e endereçados entre três clientes.

Um equipamento são os seus componentes

Entra num desses hipervisores e o separador interessante não é o resumo, são as interfaces.

Separador de interfaces do NetBox para o equipamento mcr1-hv-01 com três interfaces: eno1, SFP28 25GE, descrita como leaf-01, com o endereço IP 10.20.20.11/24 e o cabo MCR1-DAC-0001A ligado a mcr1-leaf-01 Ethernet1; eno2 SFP28 25GE para leaf-02 com o cabo MCR1-DAC-0001B para mcr1-leaf-02 Ethernet1; e ipmi 1000BASE-T descrita como BMC com 10.20.10.101/24

Lê uma linha de ponta a ponta. A interface, a sua velocidade, o que escreveste sobre ela, o endereço que tem, a etiqueta do cabo, e a porta na outra ponta. É uma única consulta, e é a resposta à pergunta que toda a gente faz de facto, que é «isto está ligado a quê».

Repara onde está o endereço. Está na eno1, não no servidor. Isso parece picuinhice até ao dia em que tens uma caixa com uma interface de gestão, duas interfaces de dados e uma loopback, e alguém pergunta que endereço responde por ela. Um modelo que pendura os endereços nos equipamentos não te consegue dizer. Este consegue, e também consegue guardar o caso perfeitamente banal de quatro endereços numa interface.

Segue o cabo

Os cabos terminam em componentes, não em equipamentos. Uma interface numa ponta, uma interface na outra, ou uma front port, uma rear port, uma tomada de energia, uma terminação de circuito. É o pormenor em que assenta a funcionalidade toda, e é por isso que a lista de interfaces acima conseguiu mostrar a outra ponta numa coluna própria sem ninguém lho dizer.

Modela um cabo de equipamento para equipamento e fizeste um desenho. Termina-o nas portas e o NetBox consegue percorrê-lo.

Traçado de cabo do NetBox para a interface eno1, desenhado como um diagrama vertical: mcr1-hv-01, um Supermicro SYS-1029U-TN10RT em Manchester DC1 / Hall 2 / MCR1-A07 (A07) / Front / U20.0, a sua interface eno1, o cabo MCR1-DAC-0001A marcado como Connected, depois Ethernet1 em mcr1-leaf-01, um Arista DCS-7050SX3-48YC8 em Front / U36.0. Trace Completed, total de segmentos 1

Aqui é um salto, porque é um cabo de ligação direta. Põe painéis de patch pelo meio e ele percorre-os, painel a painel, e diz-te o que está na outra ponta de um percurso que atravessa três armários. É o trabalho que de outra forma envolve uma lanterna e alguém a segurar a outra ponta de uma sonda de tom.

O traçado também mostra a localização completa de cada ponta. Site, pavilhão, armário, face, unidade de bastidor. Se alguma vez estiveste numa chamada a tentar dizer a um técnico de remote hands para que caixa olhar, aquela linha é o valor todo.

Endereços, como uma árvore e não como um separador

O IPAM é a metade pela qual as pessoas chegam.

Lista de prefixos do NetBox com 10.20.0.0/16 como Container com 5 filhos a 1,6% de utilização e descrito como Manchester DC1, e por baixo cinco prefixos filhos ativos indentados um nível: 10.20.10.0/24 na VLAN mgmt (100) com a função Management, 10.20.20.0/24 atribuído ao tenant Ravenscroft Legal na VLAN ravenscroft-prod (200), 10.20.21.0/24 à Padgate Foods, 10.20.22.0/24 à Hartley Components, e 10.20.30.0/29 na VLAN transit (110) a 16,7% de utilização

A indentação é calculada a partir dos próprios endereços. Não dizes ao NetBox que 10.20.20.0/24 está dentro de 10.20.0.0/16, ele descobre-o sozinho, e vai continuar a descobri-lo quando alguém acrescentar um /26 no meio dele no próximo ano.

Cada linha traz as coisas pelas quais filtras de facto: a VLAN a que corresponde, a função, e o cliente a que pertence. A utilização também é calculada.

Abre um e tens os endereços que lá estão, e os buracos.

Separador IP Addresses do NetBox para o prefixo 10.20.20.0/24, com uma linha verde «10 IPs available», depois 10.20.20.11/24 e 10.20.20.12/24, ambos ativos e atribuídos ao tenant Ravenscroft Legal, e depois uma linha verde «242 IPs available»

Aquelas linhas verdes são o espaço livre, mostrado em linha com o espaço usado. Há uma chamada à API que te entrega o próximo endereço livre de um prefixo, que é a única peça de automação IPAM que se paga logo, porque é aquilo que as pessoas de outra forma fazem a semicerrar os olhos para uma folha de cálculo e a ter esperança.

Uma interface leva os endereços que quiseres, das duas famílias, e nomeias um de cada como o primário do equipamento.

Lista de endereços IP do NetBox filtrada pela interface eno1 em mcr1-hv-01, com quatro endereços: 10.20.20.11/24 marcado como primário, 10.20.20.201/24 um endereço de serviço, 2001:db8:20:20::11/64 primário v6, e 2001:db8:20:20::201/64 um endereço de serviço, todos atribuídos ao tenant Ravenscroft Legal

Dois IPv4 e dois IPv6 numa porta, o que é uma terça-feira normal e uma coisa que um modelo centrado no equipamento não consegue exprimir de todo.

Introduz os endereços com a máscara da rede em que estão, não como /32. O NetBox aceita 10.20.20.11/32 e arquiva-o sob o prefixo certo, porque a contenção é calculada a partir do endereço do host. O que não faz é corrigir-te depois: a máscara é guardada exatamente como foi escrita e devolvida a quem a ler, por isso um /32 num endereço de LAN gera um /32 na configuração do equipamento. O sítio onde isso morde é três meses depois num config template, não hoje no formulário.

Uma instalação, três clientes

A maioria dos objetos no NetBox pode ser atribuída a um tenant. Uma empresa usa isso para unidades de negócio. Se vendes serviços geridos, crias um por cliente.

Página do tenant Ravenscroft Legal no NetBox, no grupo Customers, com um painel Related Objects que lista Circuits 2, Devices 2, IP Addresses 2, Prefixes 1 e VLANs 1, e separadores no topo para Custom Objects, Contacts, Journal e Changelog

Aquele painel à direita é a resposta a «o que é que este cliente tem», e montou-se sozinho. Sem relatório, sem folha de cálculo, sem perguntar ao engenheiro que o construiu.

Vale a pena ter cuidado com o que tenancy quer dizer, porque errar no primeiro dia é um ano a desfazer mais tarde. Um tenant quer dizer que o objeto é dedicado a esse cliente. Um router que só os serve a eles recebe o tenant deles. Uma firewall que serve quatro deles não pertence a nenhum, por isso não recebe nenhum, e a relação vai para outro lado. Mais sobre isso mais abaixo, porque é o ponto em que a maioria das pessoas descobre que precisa de acrescentar uma coisa sua.

Põe os números no device type

Este é o passo que separa um inventário de uma coisa que responde a perguntas, e custa uns dez minutos por device type.

Um device type pode levar o seu peso e, através dos seus modelos de porta de alimentação, o seu consumo de energia. Põe isso no tipo uma vez e cada equipamento que alguma vez criares a partir dele herda-o. Deixa-os de fora e o NetBox diz-te alegremente que um armário está 28,6% cheio e mais nada.

Página do device type Supermicro SYS-1029U-TN10RT no NetBox, com altura de 1U, profundidade total marcada, peso de 19,10 kg e método de arrefecimento Air, com um separador Power Ports com a contagem 2 e um painel Related Objects que mostra 6 equipamentos

Pus o peso nos cinco tipos aqui, dei a cada um dois modelos de porta de alimentação com um consumo máximo e um alocado, dei ao tipo de PDU uma entrada e doze tomadas, e depois criei um quadro elétrico e duas alimentações para o armário e cablei tudo: a PSU1 de cada equipamento à PDU A, cada PSU2 à PDU B, e a entrada de cada PDU à sua alimentação.

Power feed MCR1-A07-A do NetBox, tipo Primary, estado Active, ligado a mcr1-pdu-a INPUT, com a utilização alocada de 5340VA de 5888VA numa barra vermelha a 90,7 por cento, e as características elétricas de alimentação AC, 230 volts, 32 amperes, monofásica e 80 por cento de utilização máxima

Depois a página do bastidor muda por completo.

Página do bastidor MCR1-A07 no NetBox, agora com capacidade de arrefecimento Hybrid, capacidade de arrefecimento de 15,00 kW, utilização de espaço de 28,6 por cento a verde e utilização de energia de 90,7 por cento a vermelho, ao lado das elevações frontal e traseira

Utilização de espaço 28,6%. Utilização de energia 90,7%.

Aquele armário está um terço cheio de equipamento e quase sem energia, e isso é um facto sobre o teu parque que nenhuma folha de cálculo te vai alguma vez oferecer. É também o facto que decide se a próxima encomenda é montada ali ou noutro lado, e saiu de dados que introduziste uma vez, nos tipos.

Duas coisas que o vão deixar a mostrar zero

Ao princípio obtive 0,0%, duas vezes, e vale a pena conhecer as duas causas porque nenhuma produz um erro.

As tomadas têm de referenciar a entrada. Uma tomada de energia numa PDU tem um campo power_port que aponta para a porta a montante no mesmo equipamento. Deixa-o em branco e a cadeia fica partida: o NetBox não tem maneira de saber que aquelas doze tomadas são alimentadas por aquela entrada, por isso nada é somado.

Deixa vazios os campos de consumo da entrada. Esta é a que vai contra a intuição. O NetBox só calcula o consumo de uma porta de alimentação a partir do que lá está ligado se os seus próprios dois campos de consumo estiverem em branco:

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, ...}

Eu tinha posto, muito prestável, maximum_draw: 7400 na entrada da PDU, porque é essa a potência nominal da PDU. O NetBox acreditou em mim, tomou o allocated_draw como não definido, e reportou zero. Limpa os dois e ele faz as contas:

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

Portanto a regra é: põe números reais nas folhas, e deixa as portas intermédias em branco para o NetBox as poder somar. Um valor definido administrativamente ganha sempre ao calculado, o que é o comportamento correto e exatamente a coisa errada de fazer numa PDU.

Arrefecimento, que é novo

A versão 4.7 acrescentou o arrefecimento ao DCIM, e chegou com a metade que está a ficar cara. Um bastidor leva uma capacidade de arrefecimento de ar, híbrida ou líquida e uma capacidade em quilowatts; um device type leva um método de arrefecimento. Acima disso ficam as fontes de arrefecimento para os chillers e as unidades CRAC, as alimentações de arrefecimento que representam um circuito até um bastidor, e componentes de entrada e saída nos próprios equipamentos para cold plates e coletores.

O armário acima diz Hybrid, 15,00 kW, porque eu disse isso ao bastidor. Se vais receber equipamento com arrefecimento líquido este ano, é um modelo para aquilo que neste momento tens numa folha de cálculo.

Uma instalação, muitos clientes

A tenancy é a razão pela qual um prestador pode correr um só NetBox em vez de um por cliente, e vale a pena perceber o que faz e, mais importante ainda, o que não faz.

Vinte e oito dos modelos do NetBox têm um campo de tenant. Sites, locations, racks e reservas de rack. Devices, cabos e virtual device contexts. Prefixos, endereços IP, ranges, aggregates, VLANs, VLAN groups, VRFs, route targets, ASNs. Circuits e circuit groups. Clusters e máquinas virtuais. Túneis, L2VPNs, wireless LANs e links. Power feeds e cooling feeds.

São todos os substantivos faturáveis. Define-o de forma coerente e «o que é que este cliente tem» deixa de ser uma investigação.

Mas um tenant é uma etiqueta, não uma fechadura. Diz que o objeto é dedicado a esse cliente. Não impede quem consegue entrar de ler tudo, o que está bem dentro de uma empresa e não serve para nada a partir do momento em que um cliente tem conta.

Daí seguem-se duas coisas, e a segunda é a que as pessoas erram.

Um tenant quer dizer dedicado. Um router que serve um só cliente recebe o tenant dele. Uma firewall que serve quatro deles não pertence a nenhum, por isso não recebe nada, e registas a relação na coisa que de facto vendeste. Forçar um tenant em equipamento partilhado torna discretamente errado cada relatório construído sobre a tenancy.

E o acesso é um mecanismo completamente à parte.

As permissões são onde vive o isolamento

As permissões de objeto do NetBox aceitam uma restrição em JSON, e a restrição é um filtro do ORM do Django. Estreita o queryset antes de se construir o que quer que seja a partir dele, por isso cada vista, exportação, chamada à API e pesquisa é estreitada com ele.

Página de detalhe da permissão Ravenscroft read-only no NetBox, com Enabled marcado, Actions com View marcado e Add, Change, Delete, Render configuration e Synchronize data todos cruzados, Object Types com Circuits circuit, DCIM device e IPAM prefix, um utilizador atribuído ravenscroft-ro, e um painel Constraints com o JSON tenant__slug definido como ravenscroft-legal

Três campos fazem o trabalho. Os tipos de objeto a que se aplica, as ações que concede, e aquela restrição ao fundo. Tudo o resto é contabilidade.

Aqui está a lista de equipamentos como administrador.

Lista de equipamentos do NetBox como utilizador admin, Results 14, com mcr1-core-01 e 02, mcr1-hv-01 a 06, mcr1-leaf-01 e 02, mcr1-pdu-a e b, e mcr1-pp-01 e 02, com colunas para estado, tenant, site, location, rack, função, fabricante, tipo e endereço IP

E aqui está o mesmo URL, a mesma instalação, com a sessão iniciada como o cliente.

A mesma lista de equipamentos do NetBox com a sessão iniciada como ravenscroft-ro, Results 2, só com mcr1-hv-01 e mcr1-hv-02, ambos atribuídos ao tenant Ravenscroft Legal, e a navegação à esquerda reduzida a Devices, IPAM, Circuits, Plugins e Admin

Duas linhas em vez de catorze, e olha para o menu da esquerda. Encolheu para as quatro coisas em que aquela conta pode mexer. Ninguém configurou isso. A navegação é construída a partir das mesmas permissões, por isso um cliente nunca vê uma ligação para uma coisa que o recusaria.

As duas maneiras de dizer não

Este é o pormenor que vale a pena saber, porque as duas recusas querem dizer coisas diferentes e ambas são deliberadas.

O token do cliente pedeRecebe
/api/dcim/devices/200, uma linha de duas
/api/dcim/devices/1/, o seu200
/api/dcim/devices/2/, o de outra pessoa404
/api/tenancy/tenants/403
/api/dcim/sites/, nunca concedido403
nenhum token403

404 quer dizer que o tipo é teu mas aquela linha não é. A restrição retirou-a do queryset, por isso, para o pedido, ela não existe. Um 403 ali confirmaria que existe, e deixaria um cliente curioso contar o teu parque percorrendo os IDs.

403 quer dizer que o tipo nunca foi teu. Tenants e sites nunca foram concedidos, por isso recusam logo, e o cliente não consegue enumerar quem mais está na plataforma.

Depois deixa-os escrever

Só leitura é o caso fácil. A verdadeira questão é se se pode confiar a um cliente direitos de edição, por isso concedi change sob a mesma restrição e fui à procura da saída.

TentativaResultado
Editar o seu próprio equipamento200, gravado
Editar o equipamento de outro cliente404
Editar o seu próprio equipamento, passando-o para o tenant do outro cliente403
Apagar o seu próprio equipamento403, apagar nunca foi concedido

A terceira linha é a que importa. Reatribuir o teu próprio equipamento ao tenant de outra pessoa é a fuga óbvia, porque o objeto está dentro da tua restrição quando o pedido chega e fora dela depois. O NetBox avalia a restrição contra o estado em que o objeto ficaria, por isso recusa. Voltei a ler o equipamento em vez de confiar no código de estado, e o tenant não tinha mudado.

É esse o buraco que a maior parte da multi-tenancy feita em casa deixa aberto, e normalmente é encontrado por um cliente e não por um teste.

Variáveis que precisam de ser herdadas

Aqui está a distinção que as pessoas erram, e acertar nela poupa muita edição.

Um custom field é um valor num objeto. Defines por objeto, e fica lá. Bom para um facto sobre a própria coisa: uma etiqueta de inventário, um número de contrato de suporte, uma data de entrada em serviço.

Um config context é um valor ligado a uma característica, que tudo o que corresponde a essa característica herda. Bom para uma variável que deve descer em cascata: os teus servidores NTP, os teus destinos de syslog, a tua comunidade SNMP, o teu domínio DNS, a tua VLAN de gestão, a tua janela de backup.

Se dás por ti a definir o mesmo custom field com o mesmo valor em quarenta equipamentos, querias um config context.

Lista de config contexts do NetBox com North West base com peso 1000 atribuído à região North West, e Manchester DC1 syslog com peso 2000 atribuído ao site Manchester DC1, ambos ativos

Um contexto é JSON arbitrário, e pode ser ligado a uma region, site group, site, location, device type, role, platform, cluster, cluster type, cluster group, tenant group, tenant ou tag. O tenant está nessa lista, o que para um prestador quer dizer que um facto verdadeiro para um cliente em todo o lado o segue para cada equipamento que alguma vez acrescentares para ele.

A fusão é chave a chave, e o peso decide quem ganha cada uma.

Separador Config Context do NetBox para mcr1-core-01 com o Rendered Context à esquerda, que contém domain, ntp_servers, snmp_community e syslog_servers, e os Source Contexts à direita, com North West base de peso 1000 com as quatro chaves e Manchester DC1 syslog de peso 2000 só com syslog_servers

Lê o painel da direita contra o da esquerda. A região fornece quatro chaves com peso 1000. O site fornece uma chave com peso 2000. O contexto gerado mantém intactos o domínio, os servidores NTP e a comunidade da região, e fica com o servidor de syslog do site, porque é a única chave que alguém disputou.

Escreves a exceção, não uma cópia nova de tudo com a exceção lá dentro. É esse o valor todo, e é por isso que isto escala onde um ficheiro de variáveis por equipamento não escala.

O contexto local ganha a tudo o que está acima

A pilha de herança tem um topo, e é o próprio objeto. Os dados de contexto local num equipamento ganham a todos os contextos de origem que se lhe aplicam, sejam quais forem os seus pesos.

Defini isto em mcr1-core-01:

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

e o seu contexto gerado passou a ser:

{
  "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"]
}

Separador Config Context do NetBox para mcr1-core-01 com o Local Context agora preenchido com syslog_servers 10.20.10.99 e uma nota, o painel a dizer que o config context local sobrepõe todos os contextos de origem, e o Rendered Context a mostrar o servidor de syslog local ao lado do domínio, dos servidores NTP e da comunidade herdados

O servidor de syslog local ganhou tanto à sobreposição do site com peso 2000 como à região com peso 1000. Tudo aquilo sobre o qual não disse nada continuou a ser herdado, por isso o domínio, os servidores NTP e a comunidade passaram intactos, e a chave nova foi simplesmente acrescentada.

É essa a porta de saída para a única caixa que é genuinamente diferente, e o painel diz-te claramente que sobrepõe todos os contextos de origem. Se dás por ti a usá-lo em muitos equipamentos e não num só, encontraste uma característica que esses equipamentos partilham e querias um contexto com esse âmbito.

Três armadilhas

Um contexto sem âmbito é global. Cria um e esquece-te de o atribuir a alguma coisa, e aplica-se a todos os equipamentos e máquinas virtuais que tens. É comportamento documentado e de vez em quando é o que queres. Também é silencioso.

As chaves não podem ter hífenes se as quiseres alcançar de forma simples. Os dados de contexto são JSON, por isso ntp-servers é perfeitamente legal, mas os nomes de variáveis do Jinja não são chaves JSON. {{ ntp-servers }} é interpretado como uma subtração e lança UndefinedError: 'ntp' is undefined. Escreve {{ ntp_servers }} sobre dados com hífenes e recebes uma string vazia, HTTP 200, e nenhum aviso em lado nenhum. Usa underscores nas chaves e o modelo óbvio funciona.

Um perfil pode travar as gralhas. Um config context profile agrupa contextos relacionados e impõe um JSON schema aos seus dados no momento da gravação. Dei a um deles um schema que exige syslog_servers como array de strings IPv4, e depois cometi os dois erros que as pessoas cometem de facto:

{"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

Rejeitados onde alguém os cometeu, e não quatrocentos equipamentos depois.

Gerar a configuração

Dados de contexto mais um modelo Jinja dão-te um ficheiro de configuração. O equipamento está no âmbito como device, o seu contexto fundido está no âmbito como variáveis normais, e podes percorrer os seus componentes.

Separador Render Config do NetBox para mcr1-core-01, com o config template Junos base e a configuração Junos gerada: host-name mcr1-core-01, domain-name mcr1.example.net, uma linha de localização com Manchester DC1 / MCR1-A07 / U39, dois servidores NTP, o único host de syslog 10.20.10.99, a comunidade SNMP n0rthwest, e cada interface com a sua descrição e família de endereços

Tudo naquela página veio de um sítio diferente, e é esse o objetivo:

LinhaDe onde veio
host-name mcr1-core-01o equipamento
domain-name mcr1.example.neto config context regional
location "Manchester DC1 / MCR1-A07 / U39"o site, o bastidor e a posição nele
server 172.16.10.22o contexto regional, peso 1000
host 10.20.10.99 any noticeo próprio contexto local do equipamento, a ganhar ao site e à região
family inet address 10.20.10.11/24o endereço naquela interface, com a máscara tal como foi escrita

O modelo é resolvido primeiro no equipamento, depois na role, depois na platform, e o pedido falha se nenhum dos três tiver um. Por isso atribuis um modelo a uma platform uma vez, e cada equipamento que corre esse software gera a partir dele, a não ser que a sua role ou o próprio equipamento digam outra coisa. É para isso que serve uma platform: o sistema operativo ou a família de software do fabricante, não o hardware.

O NetBox gera. Não envia. Pôr o resultado na caixa é trabalho da tua automação, e no dia em que um erro num modelo teria de outra forma reconfigurado quatrocentos equipamentos, vais ficar contente por serem dois sistemas diferentes.

Plugins

Um plugin é uma aplicação Django instalada ao lado do NetBox. Pode acrescentar modelos, acrescentar páginas, estender as duas APIs, injetar conteúdo em modelos de página existentes, acrescentar navegação, acrescentar filas de tarefas em segundo plano e carregar mais aplicações Django. Há muito pouco que não consiga fazer, porque por baixo é só Django.

Instalar um são quatro comandos e um reinício:

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 pilha de contentores os mesmos pacotes vão para o plugin_requirements.txt e reconstróis a imagem. De uma forma ou de outra, fixa as versões e verifica primeiro a matriz de compatibilidade, porque um plugin que ainda não acompanhou uma versão do NetBox recusa-se a arrancar a aplicação inteira em vez de se desativar a si próprio.

Página de plugins instalados do NetBox, com Custom Objects versão 0.7.0 da NetBox Labs, Topology views versão 4.7.0 de Mattijs Vanhaverbeke, e qrcode versão 1.0.0 de Nikolay Yuzefovich

O catálogo publicado lista 31. Estes são os que vale a pena conhecer, com a licença com que cada um é de facto distribuído:

PluginO que fazLicença
DNSZonas, registos e servidores de nomes como fonte de verdadeMIT
BGPSessões, comunidades e políticas de encaminhamentoApache 2.0
Topology ViewsMapas de topologia gráficos construídos a partir dos teus cabosApache 2.0
FloorplanMapas gráficos de sites e locationsLGPL 3.0
QR CodeCódigos em bastidores, equipamentos e cabos, para etiquetas de inventárioApache 2.0
ACLsListas de acesso e regrasApache 2.0
Prometheus SDDá ao Prometheus a lista de hosts diretamente do NetBoxMIT
DocumentsDocumentos ligados a circuitos e equipamentosApache 2.0
LifecycleFim de vida do hardware, licenças e contratosApache 2.0
ContractContratos e faturasMIT
Reorder RackArrastar e largar unidades de bastidorApache 2.0
BranchingRamos isolados e fundíveis dos teus dadosNetBox Limited Use
Custom ObjectsTipos de objeto novos, definidos na interfaceNetBox Limited Use

O Prometheus SD é a forma honesta da ideia toda. O NetBox sabe o que existe, por isso deixa o NetBox dizê-lo ao sistema de monitorização, e deixa de manter uma segunda lista de hosts que se vai desviando.

Uma coisa a saber antes de construíres sobre as duas últimas linhas. O próprio NetBox é Apache 2.0 e é-o desde que a DigitalOcean o lançou em 2016, e o projeto é hoje gerido pela NetBox Labs em conjunto com uma equipa de mantenedores voluntários.21 O NetBox Branching e o NetBox Custom Objects não são: são distribuídos sob a NetBox Limited Use License 1.0, que concede o uso «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», e que não concede o direito de usar o software «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». Se instalaste o NetBox Community a partir do GitHub e o corres em nome de clientes, lê tu mesmo os termos antes de lhes pores um schema por trás.10 O próprio guia de instalação do NetBox recomenda os dois plugins sem o mencionar.11

Custom fields

Um custom field acrescenta um atributo a um modelo existente. Os valores são guardados como JSON junto a cada objeto, por isso não há migração nem reinício, e há treze tipos, incluindo referências de objeto e de vários objetos para outros registos do NetBox.

Página do equipamento mcr1-core-01 no NetBox com um painel Custom Fields que tem um grupo Asset com Warranty expires 2029-06-30 e Support contract JNPR-448120, ao lado do painel Device Type com Juniper MX204 e de um painel Dimensions com o peso total de 9,5 quilogramas

Dois campos ali, agrupados sob um título «Asset» que eu escolhi. Repara no painel Dimensions à direita deles: 9,5 kg, que ninguém escreveu neste equipamento. Veio do device type.

Os custom fields são validados, e vale a pena saber que o são, porque é uma diferença real em relação ao caminho mais abaixo. Dei ao campo do contrato uma expressão regular e a API impô-la:

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}$'"]}

Mudaram duas coisas na 4.7 que importam em escala. Criar um campo com um valor por omissão, ou apagar um campo, obriga a reescrever os dados guardados de cada objeto a que se aplica, por isso numa tabela grande esse trabalho é entregue a uma tarefa em segundo plano e o campo mostra «provisioning» ou «deleting» enquanto corre. Um campo só funciona enquanto estiver no estado ativo: durante qualquer das operações não aparece nos objetos, nos formulários, nos filtros nem em nenhuma das APIs. Isso precisa de um worker a correr, ou fica nesse estado indefinidamente.

Usa um custom field quando estás a acrescentar um facto sobre a própria coisa. Usa um config context quando o valor deve descer em cascata. Usa a secção seguinte quando a coisa de que precisas não existe.

Menus de seleção personalizados, e sobrepor o que vem de origem

Debaixo deste título vivem dois mecanismos diferentes e resolvem problemas diferentes. Um é para os teus próprios campos. O outro reescreve os do NetBox.

Um choice set, para o teu próprio campo de seleção

Um custom field do tipo «selection» vai buscar as suas opções a um choice set, que é um objeto que geres na interface como qualquer outro. Assim, o «nível de suporte» passa a ser uma lista pendente a sério em vez de texto livre que alguém vai escrever de três maneiras.

Choice set de custom field do NetBox chamado Support tier, descrito como aquilo que o cliente paga, com três escolhas: bronze para o dia útil seguinte, silver para 8 horas, e gold para 4 horas 24x7

É imposto, incluindo através da API:

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

Os choice sets são partilhados, por isso um conjunto pode servir de base ao mesmo campo em vários modelos, e mudar a lista num sítio muda-a em todo o lado.

FIELD_CHOICES, para os campos do próprio NetBox

Este é o que as pessoas não sabem que existe. Vários dos campos de escolha nativos do NetBox podem ser estendidos ou substituídos a partir do configuration.py, incluindo o estado do equipamento, o estado do site, o estado do bastidor, o estado do circuito e muitos mais.12

Acrescenta um sinal de mais para somar ao que vem de origem. Deixa-o de fora para substituir a lista por completo.

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'),
    ),
}

Pus exatamente isso nesta instância. O estado do equipamento voltou com os sete valores de origem e os meus dois:

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

e o estado do site voltou só com os meus, sem a lista de origem:

surveyed, building, active, closing

Uma escolha pode ser um simples tuplo de valor, rótulo e cor, ou um dicionário que também aceita uma descrição mostrada como subtítulo no formulário. E comportam-se como valores nativos em todo o lado, porque para o resto do NetBox são valores nativos:

Lista de equipamentos do NetBox com mcr1-hv-06 a mostrar um distintivo de estado Burn-in a ciano ao lado dos outros equipamentos com o estado de origem Active, com o mesmo estilo de qualquer estado nativo

Aquele distintivo é o meu estado, na minha cor, a ordenar e a filtrar como qualquer outro.

Três coisas que vale a pena saber antes de o usares.

Substituir apaga os valores de origem do menu, não da base de dados. Qualquer objeto que já tenha um deles mantém-no, mas o valor deixa de ser oferecido e não vai ser uma escolha válida da próxima vez que alguém editar esse objeto. Se substituíres uma lista, verifica se nada está assente num valor que acabaste de retirar.

Vive no ficheiro de configuração, por isso precisa de um reinício e não é uma coisa que um utilizador da interface consiga mudar. Para um prestador é assim que deve ser: o conjunto de estados que o teu negócio reconhece é uma decisão de governação, não uma decisão de terça-feira à tarde.

Estende antes de substituíres. Os valores de origem são o que todos os plugins, scripts e integrações esperam ver. Acrescentar não custa nada. Substituir é uma decisão que fica tua para sempre.

Custom objects

Aqui está uma lacuna real. O NetBox modela clusters, máquinas virtuais e discos virtuais. Não modela o datastore onde esses discos vivem de facto, e para quem corre Proxmox ou VMware esse é o objeto que liga o armazenamento que compraste à carga de trabalho que o usa.

O plugin Custom Objects deixa-te definir um novo tipo de objeto a partir da interface ou da API, sem escrever código nenhum. Assim:

Página do Custom Object Type Datastore no NetBox, versão 1.0.0, descrito como armazenamento partilhado onde um cluster põe os discos das VMs, com um separador Fields que mostra 7 e um painel Fields com Name como Text, Cluster como Object a apontar para Virtualization > Cluster, Provisioned by como Multiple objects a apontar para DCIM > Device, Backing como Text, Capacity (GB) como Integer, Thin provisioned como Boolean, e Customer como Object a apontar para Tenancy > Tenant

Sete campos, dois dos quais são o objetivo todo. cluster é uma referência a um único objeto, um cluster real do NetBox, definida como protect para que ninguém consiga apagar um cluster deixando o seu armazenamento sem chão. provisioned_by é uma referência a vários objetos, os equipamentos que de facto o servem.

Isso dá-te um objeto de primeira classe com a sua própria entrada de navegação, vista de lista, filtros, importação e exportação:

Lista de Datastores do NetBox com quatro linhas: ds-nvme-01 no cluster MCR1-PVE, fornecido por mcr1-hv-01, 02 e 03, assente num pool Ceph RBD NVMe com 40\u00a0960 GB e thin provisioned; ds-nvme-02; ds-archive-01 num pool de HDD com WAL em NVMe, com 196\u00a0608 GB e não thin provisioned; e ds-ravenscroft-01 com 8192 GB, atribuído ao tenant Ravenscroft Legal

E como as referências são reais, a relação também aparece do outro lado. Abre o cluster e os datastores estão listados nele.

Página do cluster MCR1-PVE no NetBox, um cluster Proxmox VE com âmbito Manchester DC1, com um separador Custom Objects que mostra os datastores que o referenciam

Um custom object type herda a maior parte do que faz de um objeto do NetBox um objeto do NetBox: vistas de lista e de detalhe, uma entrada de navegação, endpoints REST, pesquisa de texto integral, registo de alterações, journaling, tags, marcadores, importação e exportação, event rules e notificações. Nada disso teve de ser escrito.

Também não é um bloco de JSON a fingir que é uma tabela. O plugin emite DDL a sério, e o que aparece no PostgreSQL é uma tabela a sério com restrições a sério:

                    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

O protect que pedi passou a ser ON DELETE RESTRICT, e funciona: apagar aquele cluster devolve 409 a dizer o que depende dele.

Duas coisas a saber antes de confiares nele

A validação está no formulário, não na API. É esta que apanharia uma automação. Declarei required, uma expressão regular e limites numéricos nos campos de um custom object type, e depois escrevi neles através da API REST:

O que declareiO que envieiResultado
validation_regexum valor que não corresponde a nada201 Created
required: trueo campo omitido por completo201 Created
validation_minimum: 1um número negativo201 Created
unique: trueum duplicado400, rejeitado
on_delete_behavior: protectapagar o objeto referenciado409, rejeitado

As duas que aguentaram são as duas que se tornaram restrições na base de dados. As restantes só existem no formulário web, por isso uma pessoa a escrever fica limitada e uma sincronização noturna não. Compara isso com o custom field nativo mais acima, onde a mesma expressão regular foi imposta através da API. Até isso mudar, põe tudo aquilo de que uma fatura depende atrás de uma restrição a sério.

Apagar um tipo apaga uma tabela. Apagar um campo apaga uma coluna. Isso é DDL a partir de um formulário web, executado por quem tiver a permissão, e a documentação di-lo.13 Restringe quem pode apagar isto.

Quando escrever antes um plugin a sério

Se o objeto importa, se há automação a escrever nele, e se ficarias chateado por encontrar lá lixo, escreve tu o modelo. Um plugin NetBox mínimo é um PluginConfig, um modelo, um serializer, um viewset, uma tabela, um formulário, umas quantas vistas e um mapa de URLs, e fica abaixo das duzentas linhas, quase tudo declarações. Herdar de PrimaryModel dá-te de borla tags, custom fields, registo de alterações, journaling, export templates e propriedade, e cada restrição que puseres no modelo é imposta em todo o lado, porque é a própria maquinaria de serializers do NetBox que a corre.

Há um modelo cookiecutter e um tutorial de plugins completo mantidos pela comunidade. Começa por eles em vez de por um diretório vazio.

E fica com a licença que escolheres, que ninguém pode mudar mais tarde.

Validação personalizada, e classes de validação

Tudo o que está acima é sobre registar o que lá está. Isto é sobre recusar registar o que não devia lá estar.

O NetBox valida cada objeto antes de o escrever, e podes acrescentar regras tuas por cima. Há três mecanismos, todos vivem no configuration.py, e entre eles cobrem quase tudo aquilo de que um padrão da casa precisa.

Um: regras simples, sem código

Um validador pode ser um simples mapa de nomes de campos para condições. Sem Python, e é portável entre instalações porque é só dados.

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

As condições disponíveis são min, max, min_length, max_length, regex, required, prohibited, eq e neq. Podes chegar a um objeto relacionado com um caminho com pontos, por isso region.name num site é permitido, e podes fazer corresponder request.user.username, embora a documentação, com toda a razão, te diga para usares permissões para isso.

As duas regras disparam logo:

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.']"]}

Essa segunda é um padrão de nomes, imposto. Não escrito numa página de wiki, não na cabeça de alguém, não uma coisa pela qual o recém-chegado leva um raspanete numa revisão três semanas depois. A base de dados não a aceita.

Dois: uma classe de validador, quando a regra é uma frase

As regras simples verificam um campo contra uma constante. As verdadeiras regras da casa costumam ser condicionais: isto só importa quando aquilo. Para essas herdas de CustomValidator, sobrepões validate() e chamas fail().

Pus três num módulo em /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',
            )

e liguei-as pelo caminho com pontos:

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',
    ),
}

Repara que um modelo aceita um tuplo de validadores, regras simples e classes misturadas à vontade, e correm todos. Mesmo um único validador tem de ser passado como iterável, e é fácil perder cinco minutos com isso.

Depois as regras fazem o que dizem:

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

Como o fail() aceita um field, a mensagem aparece na caixa certa do formulário e não no topo da página, que é a diferença entre uma regra que as pessoas aprendem e uma regra de que as pessoas se ressentem.

Essa é também a resposta à lacuna da secção dos custom objects. Ali a validação só existia no formulário web. Um CustomValidator corre na camada do modelo, por isso aplica-se à interface, à API REST, às mutações GraphQL, às importações em massa e a tudo o que um script faça. Há um sítio para escrever a regra e não há maneira de a contornar.

Três: regras de proteção, para apagar

O CUSTOM_VALIDATORS guarda as escritas. O PROTECTION_RULES guarda as eliminações, e aceita exatamente as mesmas duas formas.

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

Isso diz que um equipamento só pode ser apagado quando está offline. O que dá:

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

Duas teclas de atrito entre uma pessoa e um equipamento em produção, e é o seguro mais barato de toda a aplicação. Faz do processo de abate a coisa que desbloqueia o botão de apagar.

A que te vai apanhar

Os dados existentes não são verificados até lhes voltares a mexer. Acrescentar uma regra não volta atrás para validar o que já lá está. Fica quieta até alguém gravar um objeto que a viole, e então essa pessoa recebe um erro sobre uma decisão com a qual não teve nada a ver.

Vi isso acontecer. O mcr1-hv-06 foi criado antes de eu escrever nada disto, como hipervisor sem tenant. Esteve lá perfeitamente tranquilo. Depois editei a descrição:

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

A edição não tinha nada a ver com o tenant. A regra disparou na mesma, porque a validação corre sobre o objeto inteiro.

É o comportamento correto e é também como uma regra nova se transforma num ticket de suporte. Antes de ligares uma, faz uma consulta aos objetos que a violariam e corrige-os primeiro. A API facilita isso: a regra é um filtro, por isso pede os equipamentos com essa role e sem tenant, e tens a tua lista.

Liga a regra depois. Aí ela só apanha erros novos, que é para isso que serve.

Conduzi-lo a partir do Ansible

Uma fonte de verdade que nada lê apodrece. A coleção netbox.netbox é como a maioria das pessoas evita que isso aconteça, e funciona nos dois sentidos: o NetBox diz ao Ansible o que existe, e o Ansible diz ao NetBox o que construiu.

Está na versão 3.23.0, com licença GPL-3.0, e foi descarregada do Galaxy mais de 13,4 milhões de vezes. Traz 91 módulos e um plugin de inventário.14 Tudo o que se segue foi corrido contra a mesma instância, a partir de um contentor que só tinha ansible-core 2.21.4, pynetbox 7.8.0 e a coleção.

O inventário é uma consulta, não um ficheiro

Esta é a metade que se paga na primeira tarde. O nb_inventory constrói o teu inventário Ansible diretamente a partir do NetBox:

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

Isso produz isto, sem ninguém a manter uma lista de hosts:

@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

Olha para a coluna da direita. Como a tenancy está definida nos equipamentos, recebes de borla um grupo por cliente, por isso --limit tenants_ravenscroft-legal corre um play contra o equipamento de exatamente um cliente. Acrescenta um equipamento no NetBox e está no grupo na execução seguinte. Abate um e desaparece. Ninguém edita nada.

Cada host chega com aquilo que o NetBox sabe sobre ele:

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"}

Vinte e duas chaves no total, e há uma que vale a pena notar antes que te surpreenda. O ansible_host é o endereço IPv6, porque aquele equipamento tem um v6 primário definido. Verifiquei contra outros dois que só têm v4 e vieram em v4, por isso a regra é que o plugin prefere o v6 onde existe um v6 primário. O que está correto, e é também o género de coisa que preferes descobrir agora do que enquanto te perguntas porque é que um play se está a ligar por um caminho em que não tinhas pensado.

Escrever de volta

Os módulos são o outro sentido, e o que vale a pena ter é a atribuição de IPs, porque o NetBox sabe o que está livre e o teu playbook não.

- 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

Repara no que não está lá. Nenhum endereço IP. Indicas o prefixo e o NetBox devolve-te o próximo livre:

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)"

E está lá na interface um segundo depois, ainda sem cabos mas montado, com tenant e endereçado:

Separador de interfaces do NetBox para mcr1-hv-07, um equipamento criado pelo playbook, com uma interface eno1 do tipo SFP28 25GE descrita como leaf-01 e com 10.20.22.1/24

A armadilha naquele playbook

Corre-o uma segunda vez sem mudar uma linha e acontece isto:

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

O equipamento e a interface são idempotentes. O endereço não é, e não é um bug. state: present quer dizer «põe isto com este aspeto». state: new quer dizer «dá-me um novo», sempre, e foi exatamente isso que fez: dois endereços numa interface depois de duas execuções.

Isso está bem quando estás genuinamente a provisionar uma coisa nova, e vai comer discretamente um prefixo se o puseres numa tarefa que corre todas as noites. Atribui uma vez e regista o resultado, ou usa state: present com o endereço que já tens. O módulo está a fazer o que pediste. A questão é se pediste o que querias dizer.

Não é só o Ansible

A coleção recebe a atenção porque o Ansible é onde a maioria das equipas de rede já está, mas o produto é a API e há muita coisa que a fala.

CoisaO que éLicença
pynetboxO cliente Python que a própria coleção usaApache 2.0
terraform-provider-netboxGerir objetos do NetBox como recursos Terraform, mantido ativamente pela e-breuningerMPL 2.0
nornir_netboxO NetBox como inventário Nornir, para quem faz Python em vez de YAMLApache 2.0
Prometheus SDDá ao Prometheus os seus alvos de scrape a partir do NetBoxMIT
go-netboxUm cliente Go, embora ninguém lhe mexa desde maio de 2025ver o repositório
DiodeO pipeline de ingestão da própria NetBox Labs para empurrar dados descobertos para dentroNetBox Limited Use

O do Terraform é a entrada interessante para quem já gere infraestrutura dessa maneira, porque deixa um único plano criar o recurso na cloud e o registo do NetBox que o documenta, em vez de deixar a segunda metade à memória de alguém.15

O Diode tem a mesma licença que o Branching e o Custom Objects, por isso aplica-se a mesma leitura antes de construíres sobre ele.

O que a tarde compra realmente

Tudo o que está acima levou-me um dia numa máquina, e a maior parte desse dia foi a semear dados para os ecrãs terem alguma coisa. A instalação são vinte minutos de qualquer das maneiras. As decisões são a parte que importa e são todas tomadas na primeira hora: tenants antes de tudo, device types antes de devices, os números nos tipos e não no equipamento.

O que recebes em troca não é documentação. É uma distinção que ninguém faz até ter tido as duas coisas: documentação é uma coisa que escreves e depois deixas de manter. O que recebes é uma base de dados que se recusa a guardar uma contradição: não te deixa pôr duas coisas numa unidade de bastidor, nem um bastidor numa location que pertence a outro site, nem um equipamento num tipo que não existe. Cada uma dessas recusas é uma discussão que não vais ter daqui a seis meses.

E vai dizer-te coisas que ninguém lhe perguntou. Aquele armário está 28,6% cheio de equipamento e 90,7% cheio de energia. Ninguém foi à procura disso. Saiu de se pôr uma potência num device type uma vez, e é a diferença entre montar a próxima encomenda ali e descobrir da pior maneira.

A ressalva honesta é a mesma que todas as fontes de verdade têm. Só vale aquilo que te custa mantê-la certa, e a única versão disto que sobrevive a um trimestre atarefado é aquela em que alguma coisa se parte à vista quando os dados estão errados. Liga a tua monitorização, o teu provisionamento ou as tuas regras de firewall para lerem a partir dela, e uma entrada errada deixa de ser um problema de documentação a que alguém há de chegar. Passa a ser uma falha às nove e meia de uma terça-feira, com um nome agarrado. Isso parece um custo. É o mecanismo todo.

Ninguém te vai agradecer por isso, também. Um registo correto aparece como a migração que levou quinze dias em vez de um trimestre, a auditoria que levou uma tarde, o cliente que recebeu uma resposta direta ao telefone. Nada disso aparece num relatório ao lado do teu nome.

Fá-lo na mesma. A alternativa é uma empresa que não se consegue descrever a si própria, e uma empresa que não se consegue descrever a si própria não está a ser gerida. Está a ser lembrada, por menos pessoas a cada ano que passa.


  1. NetBox, Introduction — «Today, the open source project is stewarded by NetBox Labs and a team of volunteer maintainers», e a origem na DigitalOcean em 2015, com o código aberto em junho de 2016. ↩︎ ↩︎ ↩︎ ↩︎ ↩︎ ↩︎

  2. NetBox, LICENSE.txt — Apache License 2.0, copyright DigitalOcean, LLC. Origem e gestão a partir da introdução. ↩︎ ↩︎

  3. Nautobot v1.0.0 release notes — «a divergent fork of NetBox 2.10», publicadas a 26 de abril de 2021, e a lista do que acrescentou em relação ao NetBox 2.10. ↩︎ ↩︎

  4. Network to Code, «Why Did Network to Code Fork NetBox?», 25 de fevereiro de 2021 — o raciocínio sobre SLA e suporte a longo prazo, a divergência de visão, e «the NetBox project team suggested that we should consider forking». ↩︎

  5. A NetBox Labs foi fundada em 2023 como spin-out da NS1 na sequência da sua compra pela IBM, cofundada pelo mantenedor principal do NetBox, Jeremy Stretch, e anunciou uma Série A de 20 milhões de dólares em abril de 2023: NetBox Labs, «Let’s Go: Announcing NetBox Labs» e o anúncio da Série A. ↩︎

  6. NetBox Labs, NetBox Enterprise — a edição comercial autogerida, com «24/7 expert assistance from the NetBox Labs team»; o NetBox Cloud é a oferta alojada. Os termos concretos do SLA não estão publicados nessa página. ↩︎

  7. Contagens de estrelas e forks, datas de lançamento e licenças dos dois projetos lidas na API do GitHub a 30 de setembro de 2026: netbox-community/netbox e nautobot/nautobot. As versões paralelas 3.2.x e 2.4.x do Nautobot têm ambas a data de 28 de setembro de 2026. ↩︎

  8. netbox-community/netbox-docker — a pilha de contentores da comunidade, Apache 2.0. ↩︎

  9. NetBox, Installation — a tabela das versões suportadas, e as notas da versão v4.7 para os mínimos de PostgreSQL e Redis subidos. Versão e edição lidas em netbox/release.yaml. ↩︎

  10. NetBox Limited Use License 1.0 — presente no netbox-custom-objects e, de forma idêntica, no netbox-branching. As duas cláusulas citadas são textuais. ↩︎

  11. NetBox, HTTP Server installation, «What’s Next?» — «Some of the most popular plugins include» NetBox Branching, NetBox Custom Objects, NetBox DNS e NetBox BGP, sem qualquer menção aos termos da licença. ↩︎

  12. NetBox, Data Validation configuration — FIELD_CHOICES, e o sufixo com sinal de mais que estende em vez de substituir: «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. netboxlabs/netbox-custom-objects documentation — «Deleting a Custom Object Type drops an entire database table and should be done with caution.» ↩︎

  14. netbox.netbox on Ansible Galaxy e netbox-community/ansible_modules — versão 3.23.0, GPL-3.0, 91 módulos mais o plugin de inventário nb_inventory. Número de downloads lido no Galaxy a 30 de setembro de 2026. Tudo o que se mostra foi corrido com ansible-core 2.21.4 e pynetbox 7.8.0. ↩︎

  15. Licenças, atividade e contagens de estrelas lidas em cada projeto a 30 de setembro de 2026: pynetbox (Apache 2.0), terraform-provider-netbox (MPL 2.0, v6.0.0-rc.1 no registo do Terraform), nornir_netbox (Apache 2.0), netbox-plugin-prometheus-sd (MIT), go-netbox (último commit a 9 de maio de 2025) e Diode, que tem a mesma NetBox Limited Use License 1.0 que o Branching e o Custom Objects. ↩︎