netbox
| Field |
Value |
| Service |
netbox |
| Purpose |
Source of truth for network infrastructure (IPAM, DCIM, virtualization) with the Proxbox plugin |
| Criticality |
Tier 2 |
| Owner |
Platform / Network owner |
| Clusters |
homelab |
| Namespace |
netbox |
| Exposure |
internal (Traefik IngressRoute behind Authelia) |
| Stateful |
yes |
| Backup class |
nightly pg_dump to the NAS; media/reports/scripts on NAS-backed PVCs |
| RPO / RTO |
24 hours, 1 to 2 hours to restore |
| Last reviewed |
2026-09-11 |
1. Service Overview
NetBox holds the inventory of the homelab network and virtual machines. The
Proxbox plugin and its proxbox-api backend sync Proxmox objects into it.
Summary
If NetBox fails, inventory lookups and Proxbox syncs stop. Nothing else in the
platform depends on it at runtime.
Dependencies
| Dependency |
Type |
Why it matters |
PostgreSQL 16 (postgres StatefulSet) |
database |
All NetBox data |
Valkey (redis, redis-cache) |
queue / cache |
RQ worker queues and cache |
truenas-nfs-apps |
storage |
Media, reports, scripts, Proxbox data and database dumps |
| Traefik + Authelia |
ingress / access control |
HTTPS routing and edge authentication |
2. Architecture Diagram
[Browser] -> [Traefik + Authelia] -> [netbox] -> [postgres (local-path)]
| -> [redis / redis-cache]
+-> [proxbox-api] -> [Proxmox]
[netbox-db-dump CronJob] -> [postgres] -> [NAS apps-data/netbox/db-dumps]
3. Deployment Specifications
| Item |
Value |
| Source path |
netbox/base and netbox/overlays/homelab |
| Deployment model |
Kustomize, applied manually (kubectl apply -k netbox/overlays/homelab) |
| Namespace |
netbox |
| Workload kind |
Deployments (netbox, netbox-worker, proxbox-api), StatefulSets (postgres, redis, redis-cache), CronJobs, Job |
| Chart or image version |
docker.io/netboxcommunity/netbox tag set in the overlay images: block |
| Config files |
base/kustomization.yaml, overlays/homelab/kustomization.yaml, fleet.yaml |
Cluster mapping
| Cluster |
Overlay path |
Notes |
| homelab |
netbox/overlays/homelab |
Not in the live homelab Fleet GitRepo paths; apply manually |
4. Configuration Guide
Environment variables
| Variable |
Source |
Purpose |
Secret? |
| NetBox runtime settings |
netbox-config from netbox-config.env |
Application behaviour |
no |
| Database, Redis, Proxbox and superuser credentials |
netbox-secrets from netbox-secrets.env |
Access and encryption keys |
yes |
ConfigMaps
| Resource |
Path |
Purpose |
netbox-config |
overlays/homelab/netbox-config.env |
NetBox settings |
netbox-plugin-files |
overlays/homelab |
Plugin list, requirements and bootstrap script |
netbox-proxbox-bootstrap, proxbox-api-bootstrap, proxbox-api-patches |
overlays/homelab |
Proxbox endpoint bootstrap and patches |
Secrets management
- Secret names:
netbox-secrets in namespace netbox
- Source of truth:
netbox/overlays/homelab/netbox-secrets.env (tracked secret
debt, see context/security-and-secrets.md)
- Rotation trigger: credential rotation or Proxbox token changes
- Recovery note:
SECRET_KEY and API_TOKEN_PEPPER_1 must match the database
being restored
5. Access Protocols
| Path |
URL or endpoint |
Audience |
Auth |
TLS terminates at |
| Internal |
netbox, proxbox-api Services in namespace netbox |
Cluster workloads |
NetBox API tokens |
Service |
| External |
https://netbox.home.mutana.fr |
Operators |
Authelia plus NetBox local users |
Traefik |
6. Operations and Observability
- Primary health indicators:
netbox and netbox-worker Ready, postgres
Ready, netbox-db-dump last run successful.
- Dashboards or alerts: shared cluster monitoring.
- Log locations: pod logs in namespace netbox (see netbox/README.md).
- Known failure modes: plugin bootstrap failures on image upgrade, Proxbox
token drift, local-path node loss.
7. Backup and Recovery Notes
- Backup method: the
netbox-db-dump CronJob (23:30 Europe/Paris) writes a
pg_dump to /mnt/SSD-zpool/apps-data/netbox/db-dumps on the NAS and keeps 7
days; NAS snapshots and replicas keep older dumps. Media, reports, scripts
and Proxbox data are on truenas-nfs-apps and share the same NAS protection.
- Restore prerequisites: the matching
netbox-secrets; procedure in
netbox/README.md (Backup section).
- Related runbook: not required for this internal Tier 2 service; the restore
procedure lives in the workload README.
8. Release and Change Notes
- Current deployed app version: see the overlay
images: block.
- Current chart version: N/A.
- Last significant change: nightly database dump to the NAS (2026-09-11).
- Rollback reference: previous overlay revision in Git.