Skip to main content

NetBox Enterprise Helm - External Database Configuration

Beta Notice: These Helm charts are currently in beta. While stable for testing and development environments, please thoroughly test in your specific environment before production deployment. For the most up-to-date information, please refer to the main documentation.

This guide provides detailed instructions for configuring NetBox Enterprise to use external databases (PostgreSQL and Redis) instead of the built-in containerized databases.

Need the basics first? See Installation Guide for standard installation steps, or Prerequisites for system requirements.

Overview​

Using external databases provides several advantages:

  • Improved Performance: Dedicated database resources
  • Better Backup/Recovery: Established database backup procedures
  • High Availability: Database clustering and failover
  • Scalability: Independent database scaling
  • Compliance: Meet organizational database requirements

Database Requirements​

PostgreSQL Requirements​

  • Version: PostgreSQL 12 or higher
  • Databases: NetBox Enterprise requires multiple databases:
    • netbox_db - Main NetBox database
    • diode_db - Diode service database
    • hydra_db - Authentication service database
  • Users: Separate users for each database (recommended)
  • Extensions: pg_trgm extension required

Redis Requirements​

  • Version: Redis 6.0 or higher
  • Memory: At least 512MB allocated
  • Persistence: RDB snapshots recommended
  • Configuration: Default configuration suitable for most deployments

PostgreSQL Setup​

Create Databases and Users​

-- Connect as PostgreSQL superuser
-- Create databases
CREATE DATABASE netbox_db;
CREATE DATABASE diode_db;
CREATE DATABASE hydra_db;

-- Create users
CREATE USER netbox_user WITH PASSWORD 'secure_password_1';
CREATE USER diode_user WITH PASSWORD 'secure_password_2';
CREATE USER hydra_user WITH PASSWORD 'secure_password_3';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE netbox_db TO netbox_user;
GRANT ALL PRIVILEGES ON DATABASE diode_db TO diode_user;
GRANT ALL PRIVILEGES ON DATABASE hydra_db TO hydra_user;

-- Enable required extensions
\c netbox_db
CREATE EXTENSION IF NOT EXISTS pg_trgm;

\c diode_db
CREATE EXTENSION IF NOT EXISTS pg_trgm;

\c hydra_db
CREATE EXTENSION IF NOT EXISTS pg_trgm;

Database Configuration​

For production deployments, optimize PostgreSQL settings:

# postgresql.conf
shared_buffers = 256MB
effective_cache_size = 1GB
work_mem = 4MB
maintenance_work_mem = 64MB
max_connections = 200
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100

Kubernetes Secret Configuration​

Multiple Database Secrets Creation​

Create separate secrets for each database:

# Create secrets for each database
kubectl create secret generic external-postgres-secret-netbox \
  --from-literal=uri="postgres://netbox_user:$(printf '%s' 'complex$password' | jq -sRr @uri)@postgres.example.com:5432/netbox_db"

kubectl create secret generic external-postgres-secret-diode \
  --from-literal=uri="postgres://diode_user:$(printf '%s' 'complex$password' | jq -sRr @uri)@postgres.example.com:5432/diode_db"

kubectl create secret generic external-postgres-secret-hydra \
  --from-literal=uri="postgres://hydra_user:$(printf '%s' 'complex$password' | jq -sRr @uri)@postgres.example.com:5432/hydra_db"

Password Encoding for Special Characters​

For passwords containing special characters:

# For passwords with special characters, use jq for URL encoding
PASSWORD='my$pecial@password!'
ENCODED_PASSWORD=$(printf '%s' "$PASSWORD" | jq -sRr @uri)
echo "Encoded password: $ENCODED_PASSWORD"

# Use encoded password in connection string
CONNECTION_STRING="postgres://username:${ENCODED_PASSWORD}@hostname:5432/database"

Alternative: Single Secret with Multiple Keys​

# Create a single secret with multiple database URIs
kubectl create secret generic external-databases \
  --from-literal=netbox-uri="postgres://netbox_user:password@postgres.example.com:5432/netbox_db" \
  --from-literal=diode-uri="postgres://diode_user:password@postgres.example.com:5432/diode_db" \
  --from-literal=hydra-uri="postgres://hydra_user:password@postgres.example.com:5432/hydra_db"

Redis Configuration​

Create Redis Secret​

# Create Redis secret
kubectl create secret generic external-redis-secret \
  --from-literal=password="redis-secure-password"

Redis Setup Example​

# Redis configuration for production
# /etc/redis/redis.conf
bind 0.0.0.0
port 6379
requirepass redis-secure-password
maxmemory 512mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000

Helm Values Configuration​

External Database Values​

Create a values-external-db.yaml file:

# values-external-db.yaml
# Disable built-in PostgreSQL
postgresql:
  enabled: false

# Configure external PostgreSQL
externalDatabase:
  netbox:
    existingSecret: "external-postgres-secret-netbox"
    existingSecretKey: "uri"
  
  diode:
    existingSecret: "external-postgres-secret-diode"
    existingSecretKey: "uri"
  
  hydra:
    existingSecret: "external-postgres-secret-hydra"
    existingSecretKey: "uri"

# Disable built-in Redis
redis:
  enabled: false

# Configure external Redis
externalRedis:
  host: "redis.example.com"
  port: 6379
  existingSecret: "external-redis-secret"
  existingSecretPasswordKey: "password"

Alternative Configuration Format​

# values-external-db-detailed.yaml
postgresql:
  enabled: false

externalDatabase:
  type: postgresql
  
  # NetBox database
  netbox:
    host: postgres.example.com
    port: 5432
    database: netbox_db
    username: netbox_user
    existingSecret: external-postgres-secret-netbox
    existingSecretPasswordKey: password
  
  # Diode database
  diode:
    host: postgres.example.com
    port: 5432
    database: diode_db
    username: diode_user
    existingSecret: external-postgres-secret-diode
    existingSecretPasswordKey: password
  
  # Hydra database
  hydra:
    host: postgres.example.com
    port: 5432
    database: hydra_db
    username: hydra_user
    existingSecret: external-postgres-secret-hydra
    existingSecretPasswordKey: password

redis:
  enabled: false

externalRedis:
  host: redis.example.com
  port: 6379
  database: 0
  existingSecret: external-redis-secret
  existingSecretPasswordKey: password

Installation with External Databases​

Deploy NetBox Enterprise​

# Install with external database configuration
helm install netbox-enterprise \
  oci://registry.replicated.com/netbox-enterprise/beta/netbox-enterprise \
  --version 1.11.4 \
  --values values-external-db.yaml

Verify Database Connectivity​

# Check pod logs for database connections
kubectl logs -l app=netbox-enterprise -c netbox

# Test database connectivity from within the cluster
kubectl run -it --rm debug --image=postgres:13 --restart=Never -- \
  psql postgres://netbox_user:password@postgres.example.com:5432/netbox_db -c "SELECT version();"

Cloud Provider Examples​

AWS RDS Configuration​

# values-rds.yaml
postgresql:
  enabled: false

externalDatabase:
  netbox:
    host: netbox-cluster.cluster-xyz.us-east-1.rds.amazonaws.com
    port: 5432
    database: netbox
    username: netbox_user
    existingSecret: rds-secret
    existingSecretPasswordKey: password

redis:
  enabled: false

externalRedis:
  host: netbox-redis.xyz.cache.amazonaws.com
  port: 6379
  existingSecret: elasticache-secret
  existingSecretPasswordKey: password

Azure Database Configuration​

# values-azure-db.yaml
postgresql:
  enabled: false

externalDatabase:
  netbox:
    host: netbox-server.postgres.database.azure.com
    port: 5432
    database: netbox
    username: netbox_user@netbox-server
    existingSecret: azure-db-secret
    existingSecretPasswordKey: password

redis:
  enabled: false

externalRedis:
  host: netbox-redis.redis.cache.windows.net
  port: 6380
  ssl: true
  existingSecret: azure-redis-secret
  existingSecretPasswordKey: password

Google Cloud SQL Configuration​

# values-gcp-sql.yaml
postgresql:
  enabled: false

externalDatabase:
  netbox:
    host: 127.0.0.1  # Using Cloud SQL Proxy
    port: 5432
    database: netbox
    username: netbox_user
    existingSecret: gcp-sql-secret
    existingSecretPasswordKey: password

# Cloud SQL Proxy sidecar
cloudSqlProxy:
  enabled: true
  connectionName: project-id:region:instance-name
  serviceAccountKey: gcp-sa-key

Backup and Recovery​

PostgreSQL Backup​

# Create backup script
#!/bin/bash
# backup-netbox-db.sh
DATE=$(date +%Y%m%d_%H%M%S)
pg_dump -h postgres.example.com -U netbox_user -d netbox_db > netbox_backup_${DATE}.sql
pg_dump -h postgres.example.com -U diode_user -d diode_db > diode_backup_${DATE}.sql
pg_dump -h postgres.example.com -U hydra_user -d hydra_db > hydra_backup_${DATE}.sql

Redis Backup​

# Redis backup
redis-cli -h redis.example.com -p 6379 -a redis-password BGSAVE
scp redis.example.com:/var/lib/redis/dump.rdb backup_$(date +%Y%m%d).rdb

Troubleshooting​

Common Issues​

Connection Refused:

# Check database connectivity
telnet postgres.example.com 5432
nslookup postgres.example.com

Authentication Failures:

# Test database credentials
psql postgres://netbox_user:password@postgres.example.com:5432/netbox_db -c "SELECT 1;"

SSL/TLS Issues:

# Add SSL configuration
externalDatabase:
  netbox:
    host: postgres.example.com
    port: 5432
    database: netbox_db
    username: netbox_user
    existingSecret: postgres-secret
    existingSecretPasswordKey: password
    sslmode: require

Monitoring Scripts​

#!/bin/bash
# monitor-external-db.sh
echo "Checking PostgreSQL connectivity..."
kubectl exec -it deployment/netbox-enterprise -- \
  psql $DATABASE_URL -c "SELECT version();"

echo "Checking Redis connectivity..."
kubectl exec -it deployment/netbox-enterprise -- \
  redis-cli -h $REDIS_HOST -p $REDIS_PORT ping

Next Steps​

Related Topics
NetBoxConfigurationOperations