Manual de uso de NetBox

Qué es NetBox

NetBox es la fuente de verdad de inventario y contexto estructurado de iort.

No es:

• el sistema de despliegue;
• el gestor de secretos;
• el monitor de estado vivo;
• un sustituto de Git, Pulumi o Grafana;
• un “contenedor genérico” donde pegar cualquier dato.

Sí es:

• el mapa estructurado de sitios, redes, equipos, VMs, robots, ownership, tenancy, direccionamiento y servicios;
• la capa que mejor puede consultar una persona o una IA cuando necesita saber “qué hay”, “quién es responsable”, “dónde vive” y “con qué se relaciona”.

A quién va dirigido

Este manual está pensado para:

• técnicos de sistemas y redes;
• desarrolladores de software;
• ingenieros robóticos y de edge;
• operadores que necesiten consultar o mantener el inventario.

Si trabajas con un LLM

Patrón recomendado:

• usar MCP para leer el inventario y localizar el objeto correcto;
• usar REST API con token v2 para crear o editar;
• verificar después de escribir;
• dejar journal cuando cambie el inventario.

Guía específica de alta y edición:

• Cómo documentar y mantener sistemas en NetBox

Principio rector

La documentación útil para personas y agentes no es la más larga, sino la más estructurada.

En iort, la prioridad es esta:

1. identidad estable del recurso;
2. relaciones claras;
3. owner, tenant y contacto correctos;
4. estado y clasificación coherentes;
5. trazabilidad de cambios;
6. enlaces externos a la fuente operativa real.

Fuentes autoritativas

El diseño correcto para iort es federado. No usamos NetBox como “fuente de verdad de todo”.

NetBox

Usa NetBox para:

• regiones, sites, locations, racks y dispositivos físicos;
• clusters y máquinas virtuales;
• IPAM: prefijos, IPs, VLANs, VRFs y direccionamiento operativo;
• ownership, contacts y tenancy;
• servicios expuestos y endpoints relevantes;
• contexto estructurado, tags controladas, journal y changelog.

Pulumi

Usa Pulumi para:

• infraestructura declarada;
• ciclo de vida por IaC;
• outputs de despliegue;
• importación y normalización de recursos;
• drift detection y políticas.

NetBox debe enlazar a Pulumi, no sustituirlo.

Google Secret Manager

Usa Google Secret Manager para:

• secretos;
• versiones y rotación;
• IAM y control de acceso;
• claves de servicios y credenciales.

NetBox nunca debe almacenar valores secretos.

Git y CI/CD

Usa GitHub y CI/CD para:

• código;
• historial de cambios;
• PRs;
• revisiones y aprobaciones;
• trazabilidad de despliegue.

NetBox debe enlazar a repos, stacks, tickets y runbooks, no duplicar ese historial.

Observabilidad y fleet management

Usa Grafana, logs, telemetría, fleet manager o sistemas equivalentes para:

• estado vivo;
• salud;
• métricas;
• posición o telemetría de robots;
• alarmas;
• ejecución actual.

NetBox no es el sistema de monitoring.

Regla de modelado

En iort se aplica esta jerarquía:

1. modelo nativo;
2. relación;
3. custom field;
4. tag;
5. texto libre.

Si un dato ya tiene sitio en NetBox, úsalo ahí primero. Solo baja al siguiente nivel si el anterior no encaja.

Qué usar para cada cosa

owner

Usa owner para el equipo interno responsable de operar el recurso.

Ejemplo:

• IORT Platform

tenant

Usa tenant para el consumidor del recurso:

• cliente;
• línea de negocio;
• dominio interno;
• unidad organizativa.

No lo uses para representar al equipo técnico responsable.

contacts

Usa contacts para personas o grupos de contacto concretos:

• operativo;
• administrativo;
• emergencia;
• proveedor.

No mezcles contacto con owner ni con tenant.

region, site group, site

Usa:

• region para geografía;
• site group para agrupación funcional o de proveedor;
• site para la huella operativa real.

Para cloud/VPS:

• sí modelar site;
• no inventar rack o location si no existen físicamente para vosotros.

cluster

Usa cluster para agrupar un dominio operativo común:

• proveedor;
• virtualización;
• grupo de VPS;
• dominio edge.

virtual machine

Usa VirtualMachine para VPS e instancias virtuales reales.

No crees VMs ficticias para representar funciones serverless o APIs abstractas.

device

Usa Device para:

• hardware físico propio;
• robot con identidad operativa real;
• Jetson, Raspberry Pi u otro nodo edge con hostname, IP y ciclo de vida propio;
• periféricos con identidad operativa real y lifecycle propio.

inventory item

Usa Inventory Item para componentes sin identidad operativa propia:

• batería;
• cámara sin gestión independiente;
• sensor reemplazable sin hostname/IP;
• accesorios internos del robot.

platform

Usa Platform para el software base del recurso:

• Ubuntu 24.04 LTS;
• Raspberry Pi OS;
• JetPack;
• Debian;
• RouterOS;
• etc.

No lo uses para representar el hardware.

device type

Usa Device Type para el hardware real:

• robot base;
• Jetson Orin;
• Raspberry Pi 5;
• switch;
• firewall;
• servidor físico.

service

Usa Service para puertos, endpoints y capacidades expuestas sobre un device o VM:

• SSH;
• HTTPS;
• MQTT;
• ROS bridge;
• API interna;
• MCP;
• bases de datos internas si tienen valor operativo.

custom fields

Usa custom fields para metadata estructurada propia de iort que:

• no existe en el modelo nativo;
• debe ser consistente;
• se quiere explotar en filtros, automatización o auditoría.

En este repo ya están consolidados varios, entre ellos:

• sot_system
• iac_stack
• pulumi_stack_url
• gsm_secret_project
• gsm_secret_prefix
• backup_policy
• access_model
• runbook_ref
• service_tier

tags

Usa tags solo para dimensiones transversales y controladas.

Buenas tags:

• managed-by-pulumi
• access-tailscale
• backup-restic
• secret-ref-gsm
• service-netbox

Taxonomía recomendada a futuro:

• env-prod
• env-staging
• runtime-robot
• runtime-serverless
• exposure-public
• exposure-private
• criticality-tier1

No uses tags para:

• estado;
• owner;
• tenant;
• descripciones largas;
• datos que ya tienen campo nativo.

description, comments, journal, changelog

Usa:

• description para un resumen corto;
• comments para contexto operativo persistente;
• journal para bitácora humana;
• changelog para explicar por qué cambió algo.

No metas secretos, contraseñas ni datos efímeros en ninguno de esos campos.

Reglas por tipo de usuario

Técnicos de sistemas y redes

Debéis documentar en NetBox:

• sites y regiones;
• equipos físicos y VMs;
• interfaces e IPs;
• prefijos y redes;
• servicios relevantes;
• ownership y contactos;
• cambios operativos importantes en journal o changelog.

No debéis usar NetBox para:

• guardar configuraciones completas;
• pegar contraseñas;
• pegar outputs enteros de CLI;
• usar tags como sustituto de IPAM o platform.

Desarrolladores de software

Debéis documentar en NetBox:

• servicios expuestos de forma estable;
• endpoints internos y públicos relevantes;
• ownership técnico;
• relación con tenant o dominio de negocio;
• links a repo, Pulumi, dashboards y runbooks;
• metadatos de integración con custom fields.

No debéis:

• modelar cada función serverless como una VM falsa;
• usar NetBox como catálogo duplicado del repo;
• meter secretos de apps en comments o custom fields.

Para serverless y APIs:

• documentad lo estable y operativo;
• si una entidad es de primer nivel y el modelo actual la deforma, plantead plugin o catálogo separado;
• hasta entonces, modelad contexto, ownership, endpoints, conectividad y dependencias, no una infraestructura ficticia.

Ingenieros robóticos y de edge

Debéis distinguir entre:

• activo físico;
• nodo de cómputo;
• periférico.

Modelo recomendado:

• robot con identidad operativa: Device
• Jetson / Raspberry / IPC con OS e IP: Device
• sensor o periférico sin identidad operativa propia: Inventory Item

Documentad:

• hardware real con Device Type;
• software base con Platform;
• hostname, IP, conectividad y servicios con Interfaces, IP Addresses y Services;
• owner, tenant y criticidad;
• journal para sustituciones, recalibraciones, cambios de módem o incidencias.

No debéis:

• representar robots enteros como texto libre en comments;
• esconder IMEI, ICCID, robot ID o ROS distro en notas si son datos que luego filtraréis;
• mezclar identidad física y software en un único campo.

Flujos de trabajo recomendados

Alta de una VM o VPS

1. Identifica region, site group, site y cluster.
2. Crea o reutiliza tenant, owner y contacts.
3. Crea la VirtualMachine con:
4. nombre estable
5. status
6. platform
7. role
8. cluster
9. Crea interfaces e IPs.
10. Marca la IP primaria correcta.
11. Añade tags controladas.
12. Añade custom fields obligatorios.
13. Añade custom links a Pulumi, GSM, dashboards y runbooks.
14. Escribe un changelog_message claro si el alta viene de automatización.

Alta de un robot o nodo edge

1. Decide si es Device o Inventory Item.
2. Usa Device Type para el hardware y Platform para el software.
3. Asigna site, tenant, owner y contacts.
4. Documenta interfaces, IPs y servicios.
5. Añade custom fields como robot_id, ros_distro, jetpack_version, imei, iccid cuando sean relevantes y estén modelados.
6. Usa journal para eventos de mantenimiento.

Alta de un servicio o endpoint

1. Decide primero si debe colgar de una VM o Device real.
2. Crea Service sobre ese objeto si tiene valor operativo.
3. Añade Custom Links a repo, Pulumi, runbook o dashboard.
4. Si el endpoint es lo importante y el recurso subyacente no encaja bien en NetBox, documenta el contexto sin inventar un host falso.

Qué hacer y qué no hacer

Haz esto

• usa el modelo nativo siempre que exista;
• separa owner, tenant y contacts;
• usa pocas tags y muy controladas;
• usa custom fields para IDs externos y metadata validable;
• enlaza NetBox con Pulumi, Git, GSM y observabilidad;
• escribe journal y changelog útiles;
• mantén una nomenclatura estable;
• documenta el acceso y la criticidad;
• verifica calidad del dato de forma periódica.

No hagas esto

• no pegues secretos en NetBox;
• no conviertas cada workload abstracto en una VM falsa;
• no uses tags para sustituir a campos estructurados;
• no escondas datos importantes en texto libre si luego necesitan filtrado;
• no dupliques en NetBox lo que ya vive mejor en Pulumi, Git o GSM;
• no mezcles estado vivo con inventario estructurado;
• no hagas cambios masivos sin trazabilidad.

Integración con Pulumi

La integración correcta es:

• Pulumi crea o actualiza infraestructura;
• Pulumi emite metadata y outputs normalizados;
• una integración hace upsert en NetBox;
• NetBox guarda el inventario estructurado y enlaza al stack;
• el changelog explica el motivo del cambio.

Patrón recomendado:

• managed-by-pulumi como tag;
• iac_stack y pulumi_stack_url como custom fields;
• source_system o sot_system para indicar procedencia;
• managed-by-manual cuando un activo aún no esté regularizado por IaC.

Secretos

Regla obligatoria:

• NetBox guarda referencias a secretos, nunca valores.

Patrón actual de iort:

• gsm_secret_project=iort-secrets
• gsm_secret_prefix=iort-netbox-prod-

Si alguien necesita un secreto:

1. identifica el recurso en NetBox;
2. mira proyecto y prefijo de secretos;
3. usa el runbook o Google Secret Manager;
4. no escribas el valor de vuelta en NetBox.

IA, chat y MCP

Política correcta para agentes:

• lectura por defecto;
• propuesta de cambio separada;
• escritura efectiva solo por canal controlado.

Estado actual de este repo:

• el MCP oficial de NetBox está conectado a LibreChat;
• ese MCP es de solo lectura;
• sirve para consulta estructurada de inventario;
• no debe usarse como canal de escritura en producción.

Si se necesita escritura vía IA:

• debe hacerse con un canal distinto;
• con permisos separados;
• con validación y revisión humana;
• con trazabilidad completa.

Seguridad

Tailscale

Tailscale es la capa de acceso privado, no la única política de seguridad.

Buenas prácticas:

• grants explícitos;
• deny-by-default;
• posture cuando aplique;
• Tailnet Lock si el nivel de control lo requiere;
• no asumir que “estar en la tailnet” basta por sí solo.

NetBox

Buenas prácticas:

• SSO para humanos cuando proceda;
• tokens separados por propósito;
• permisos object-based;
• tokens de lectura y escritura distintos;
• expiración y rotación de credenciales.

Google Secret Manager

Buenas prácticas:

• IAM mínimo;
• rotación controlada;
• versiones claras;
• no depender ciegamente de latest en procesos sensibles si se necesita rollout o rollback ordenado.

Convención concreta para iort

Baseline actual ya sembrado:

• región: Europe > Spain > Madrid
• site group: Cloud > Scaleway / Dedibox
• site: ES-MAD-SCW-01
• cluster: es-mad-scw-vps-01
• VM principal: iort-netbox

Tags de baseline ya existentes:

• managed-by-pulumi
• access-tailscale
• backup-restic
• secret-ref-gsm
• service-netbox

Ejemplo real de tags aplicadas en iort-netbox:

• iort
• netbox
• infra
• managed-by-pulumi
• access-tailscale
• backup-restic
• secret-ref-gsm
• service-netbox

Procedimiento mínimo de calidad

Todo objeto de producción debería tener:

• status
• owner
• tenant si aplica
• description
• comments útiles
• tags solo si aportan valor transversal
• sot_system
• iac_stack o equivalente
• runbook_ref

Además:

• una VM debe tener platform, role, IP primaria correcta e interfaz de acceso identificada;
• un robot debe tener hardware, software, conectividad y lifecycle claros;
• un servicio debe estar ligado a un host o contexto real, no inventado.

Qué hacer durante las primeras semanas

No intentéis modelarlo todo a la vez.

Orden recomendado:

1. sites, regions, tenants, owners y contacts;
2. devices, VMs, clusters e IPAM;
3. tags controladas y custom fields mínimos;
4. links a Pulumi, GSM, dashboards y runbooks;
5. automatización Pulumi → NetBox;
6. auditoría de calidad del dato;
7. solo después, valorar plugins si el modelo nativo ya no da más de sí.

Enlaces del repo

• README del proyecto NetBox
• ../docs/netbox/information-model.md
• ../docs/netbox/secrets.md
• ../docs/netbox/deploy.md
• ../docs/netbox/mcp-access.md
• ../docs/netbox/validation.md