---
doc_id: doc:netbox:manual-de-uso
title: Manual de uso de NetBox
project: netbox
area: docs
kind: guide
lang: es
visibility: public
tags:
  - project:netbox
  - area:docs
---

# 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](como-documentar-en-netbox.md)

## 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:
   - nombre estable
   - status
   - platform
   - role
   - cluster
4. Crea interfaces e IPs.
5. Marca la IP primaria correcta.
6. Añade tags controladas.
7. Añade custom fields obligatorios.
8. Añade custom links a Pulumi, GSM, dashboards y runbooks.
9. 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. Poco a poco.

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](index.md)
- `../docs/netbox/information-model.md`
- `../docs/netbox/secrets.md`
- `../docs/netbox/deploy.md`
- `../docs/netbox/mcp-access.md`
- `../docs/netbox/validation.md`