Enterprise

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 PostgreSQL databases instead of the built-in containerized database.

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

Configuration Template

Here's the external-database-values.yaml template for connecting to external PostgreSQL databases:

# NetBox Enterprise - External Database Configuration
# For connecting to external PostgreSQL databases

netbox:
  # External database configuration
  externalDatabase:
    enabled: true
    type: postgresql
    host: 'your-postgres-host.example.com'
    port: 5432
    database: 'netbox'
    username: 'netbox'
    # Password should be provided via secret
    existingSecret: 'netbox-db-secret'
    existingSecretPasswordKey: 'password'

  # Database connection pool settings
  database:
    options:
      MAX_CONNS: 20
      CONN_MAX_AGE: 300

# Disable internal PostgreSQL
postgresql:
  enabled: false

# Redis configuration (can be internal or external)
redis:
  enabled: true
  architecture: standalone
  auth:
    enabled: false
# External Redis (uncomment if using external Redis)
# externalRedis:
#   host: "your-redis-host.example.com"
#   port: 6379
#   database: 0

# Database secret creation (run this separately):
# kubectl create secret generic netbox-db-secret \
#   --from-literal=password='your-database-password' \
#   --namespace=netbox-enterprise

# Example for AWS RDS:
# netbox:
#   externalDatabase:
#     host: "netbox-prod.cluster-xyz.us-east-1.rds.amazonaws.com"
#     port: 5432
#     database: "netbox"
#     username: "netbox_user"
#     existingSecret: "netbox-db-secret"

# Example for Google Cloud SQL:
# netbox:
#   externalDatabase:
#     host: "10.1.0.3"  # Private IP
#     port: 5432
#     database: "netbox"
#     username: "netbox_user"
#     existingSecret: "netbox-db-secret"

Overview

Using external PostgreSQL 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

⚠️ Redis Recommendation: We strongly recommend using the built-in Redis instance rather than external Redis. Redis contains only ephemeral cache data, so external Redis provides no backup/recovery benefits while likely impacting performance due to network latency. The built-in Redis is optimized for NetBox Enterprise's caching patterns.

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

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

⚠️ Optimization Notice: The following PostgreSQL settings are suggestions only. You must test and validate these settings in your specific environment. Optimal values depend on your hardware, scale, and usage patterns.

# postgresql.conf - SUGGESTIONS ONLY - Test before using in production
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"

Helm Values Configuration

Create your external database values file using the complete template provided below:

# Copy the complete external-database-values.yaml template from below
# and save it as values-external-db.yaml, then customize as needed
vim values-external-db.yaml

The template contains configuration for external PostgreSQL databases while keeping the built-in Redis (recommended):

# NetBox Enterprise - External Database Configuration
# For connecting to external PostgreSQL databases

netbox:
  # External database configuration
  externalDatabase:
    enabled: true
    type: postgresql
    host: 'your-postgres-host.example.com'
    port: 5432
    database: 'netbox'
    username: 'netbox'
    # Password should be provided via secret
    existingSecret: 'netbox-db-secret'
    existingSecretPasswordKey: 'password'

# Disable internal PostgreSQL
postgresql:
  enabled: false

# Redis configuration (internal recommended)
redis:
  enabled: true  # Always keep this true (recommended)

Installation with External Databases

Deploy NetBox Enterprise

# Install with external database configuration
helm install netbox-enterprise \
  oci://registry.enterprise.netboxlabs.com/netbox-enterprise/beta/netbox-enterprise \
  --values netbox-enterprise-values.yaml \
  --values values-external-db.yaml \
  ${CHART_VERSION:+--version $CHART_VERSION} \
  --create-namespace \
  --namespace netbox-enterprise

Note: Use both the base values file (contains license) and the external database configuration file.

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

# Keep built-in Redis (recommended)
redis:
  enabled: true

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

# Keep built-in Redis (recommended)
redis:
  enabled: true

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

# Keep built-in Redis (recommended)
redis:
  enabled: true

Backup and Recovery

When using external databases, backup responsibilities are split:

Your Organization's Responsibility:

External PostgreSQL database backups using your established procedures
Database infrastructure maintenance and disaster recovery
Ensuring database availability and performance

NetBox Enterprise Handles:

Application-level data consistency
Redis cache data (internal Redis recommended)
Static files and media uploads

For NetBox Enterprise application-level backup procedures, refer to the NetBox Enterprise Backup Documentation.

Next Steps

Configure High Availability for production environments
Set up CI/CD Pipeline for automated deployments
Configure Private Registry if using private container registries
Validate your deployment to ensure everything is working correctly

Configuration Template​

Overview​

Database Requirements​

PostgreSQL Requirements​

PostgreSQL Setup​

Create Databases and Users​

Database Configuration​

Kubernetes Secret Configuration​

Multiple Database Secrets Creation​

Password Encoding for Special Characters​

Alternative: Single Secret with Multiple Keys​

Helm Values Configuration​

Installation with External Databases​

Deploy NetBox Enterprise​

Verify Database Connectivity​

Cloud Provider Examples​

AWS RDS Configuration​

Azure Database Configuration​

Google Cloud SQL Configuration​

Backup and Recovery​

Next Steps​

Related Documentation​