Skip to content

netbox.md

Latest commit

 

History

History
215 lines (152 loc) · 5.46 KB

netbox.md

File metadata and controls

215 lines (152 loc) · 5.46 KB

NetBox Service

NetBox is a network infrastructure management platform providing IP address management (IPAM), data center infrastructure management (DCIM), and network documentation capabilities.

Overview

  • Namespace: infra
  • Custom Image: localhost/netbox-custom:latest (built in-cluster)
  • Access: VPN-only via HTTPS
  • Storage: PostgreSQL database (external or in-cluster)
  • Authentication: LDAP via FreeIPA (optional)

Custom Image Build

NetBox in Charon uses a custom Docker image with community plugins pre-installed. This is built in-cluster using the DaemonSet pattern with Buildah.

Included Plugins

The custom image includes the following NetBox community plugins:

  1. netbox-topology-views - Network topology visualization
  2. netbox-prometheus-sd - Prometheus service discovery integration
  3. netbox-lists - Enhanced list views and filtering

Build Process

The image build is managed by terraform/netbox-image-build.tf:

  1. ConfigMap contains the Dockerfile and plugin_requirements.txt
  2. DaemonSet runs on all nodes with privileged Buildah container
  3. Build happens in init container using Buildah
  4. Save to hostPath at /var/lib/netbox-custom-image.tar
  5. Import into containerd using ctr -n k8s.io images import

Key Build Considerations

  • Pip bootstrap required: NetBox venv doesn't include pip by default
    • Solution: Use curl -sS https://bootstrap.pypa.io/get-pip.py | /opt/netbox/venv/bin/python
  • Django SECRET_KEY length: Must be 50+ characters for collectstatic
  • Fully qualified image names: Use docker.io/netboxcommunity/netbox:latest to avoid Buildah short-name resolution errors

Testing Locally

The custom image Dockerfile is maintained in a separate repository.

Before deploying, test the custom image build locally:

git clone https://github.com/your-org/netbox-plugins-bundled.git
cd netbox-plugins-bundled/

# Build the image
docker build -t localhost/netbox-custom:latest .

# Verify plugins installed
docker run --rm localhost/netbox-custom:latest \
  /opt/netbox/venv/bin/pip list | grep netbox

# Expected output:
# netbox-topology-views    4.4.0
# netbox-prometheus-sd     0.5
# netbox-lists             4.0.3

Configuration

NetBox is configured via environment variables and a ConfigMap containing plugins_config.py:

Plugin Configuration

PLUGINS = [
    'netbox_topology_views',
    'netbox_prometheus_sd',
    'netbox_lists',
]

PLUGINS_CONFIG = {
    'netbox_topology_views': {
        'static_image_directory': 'netbox_topology_views/img',
        'allow_coordinates_saving': True,
    },
    'netbox_prometheus_sd': {
        'device_role': True,
        'device_type': True,
        'manufacturer': True,
        'platform': True,
        'region': True,
        'site': True,
        'tag': True,
    },
    'netbox_lists': {},
}

Deployment

Enable NetBox

In terraform.tfvars:

netbox_enabled = true

Apply Configuration

cd terraform
terraform apply

This will:

  1. Create the image builder DaemonSet (builds on all nodes)
  2. Deploy NetBox StatefulSet with the custom image
  3. Configure DNS and TLS certificates
  4. Set up ingress and VPN access

Verify Deployment

# Check image builder status
kubectl get daemonset -n infra netbox-image-builder

# View build logs
kubectl logs -n infra -l app=netbox-image-builder -c build-and-import

# Check NetBox pod
kubectl get pods -n infra -l app=netbox

# Verify plugins loaded
kubectl logs -n infra netbox-0 -c netbox | grep -i plugin

Troubleshooting

Image Build Failures

Symptom: DaemonSet init container fails

# View detailed build logs
kubectl logs -n infra netbox-image-builder-xxxxx -c build-and-import

# Common issues:
# - Pip not found: Check that get-pip.py bootstrap is included
# - SECRET_KEY too short: Must be 50+ characters
# - Short-name resolution: Use fully qualified image names (docker.io/...)

Plugins Not Visible

Symptom: Plugins installed but not showing in NetBox UI

# Exec into NetBox container
kubectl exec -n infra netbox-0 -c netbox -it -- /bin/bash

# Verify plugins installed
/opt/netbox/venv/bin/pip list | grep netbox

# Check static files collected
ls -la /opt/netbox/netbox/static/

# Verify plugin configuration
cat /etc/netbox/config/plugins_config.py

Resolution: Ensure collectstatic ran during build and plugins are listed in PLUGINS array.

Database Connection Issues

# Check database connectivity
kubectl logs -n infra netbox-0 -c netbox

# Test database connection
kubectl exec -n infra netbox-0 -c netbox -it -- \
  /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py dbshell

Access

After deployment, access NetBox via VPN:

# Connect to VPN first
tailscale up --login-server https://vpn.example.com

# Access NetBox
open https://netbox.example.com

Related Documentation

pattern

References

Navigation: Documentation Index | Services | Home