External Database Guide

This guide walks through connecting NetBox Enterprise to an externally managed PostgreSQL instance instead of the default PGO-managed database.

Prerequisites

• PostgreSQL 14 or later (PostgreSQL 18 recommended)
• Network connectivity from the Kubernetes cluster to the PostgreSQL host
• A database user with appropriate permissions

Step 1: Prepare the External Database

Create the required databases and users on your PostgreSQL instance:

-- Create databases
CREATE DATABASE netbox;
CREATE DATABASE diode;   -- Only if Diode is enabled
CREATE DATABASE hydra;   -- Only if Diode is enabled

-- Create users
CREATE USER netbox WITH PASSWORD 'secure-password';
CREATE USER diode WITH PASSWORD 'secure-password';   -- Only if Diode is enabled
CREATE USER hydra WITH PASSWORD 'secure-password';   -- Only if Diode is enabled

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE netbox TO netbox;
GRANT ALL PRIVILEGES ON DATABASE diode TO diode;
GRANT ALL PRIVILEGES ON DATABASE hydra TO hydra;

Step 2: Create Kubernetes Secrets

Store database credentials in Kubernetes secrets:

kubectl -n netbox create secret generic netbox-db-credentials \
  --from-literal=password='secure-password'

# Only if Diode is enabled:
kubectl -n netbox create secret generic diode-db-credentials \
  --from-literal=password='secure-password'

kubectl -n netbox create secret generic hydra-db-credentials \
  --from-literal=password='secure-password'

Step 3: Configure Values

Create your values file with external PostgreSQL configuration. Connection details (host, port) are specified once in a postgresqlProfiles entry and referenced by all components:

# Disable PGO since we're using an external database
pgo:
  enabled: false

netboxEnterprise:
  enabled: true
  spec:
    # Shared PostgreSQL connection profile
    postgresqlProfiles:
      netbox:
        host: "postgres.example.com"
        port: 5432

    postgresql:
      external: true
      postgresqlProfile: netbox

    netbox:
      config:
        postgres:
          database: "netbox"
          user: "netbox"
          password:
            name: netbox-db-credentials
            key: password

Step 4: Configure TLS (Recommended)

For production environments, enable TLS for database connections.

CA-Only Verification

netboxEnterprise:
  spec:
    postgresqlProfiles:
      netbox:
        host: "postgres.example.com"
        port: 5432
        tlsConfig:
          sslmode: verify-ca
          keychainCaCertificates:
            - postgres-ca

    postgresql:
      external: true
      postgresqlProfile: netbox

    tlsKeychain:
      caCertificateSecrets:
        - name: postgres-ca
          secret: postgres-ca-cert
          key: ca.crt

Create the CA certificate secret:

kubectl -n netbox create secret generic postgres-ca-cert \
  --from-file=ca.crt=path/to/ca-certificate.crt

Full Verification with Client Certificates (mTLS)

netboxEnterprise:
  spec:
    postgresqlProfiles:
      netbox:
        host: "postgres.example.com"
        port: 5432
        tlsConfig:
          sslmode: verify-full
          keychainCaCertificates:
            - postgres-ca
          keychainClientCertificate: postgres-client

    postgresql:
      external: true
      postgresqlProfile: netbox

    tlsKeychain:
      caCertificateSecrets:
        - name: postgres-ca
          secret: postgres-ca-cert
          key: ca.crt
      clientCertificateSecrets:
        - name: postgres-client
          secret: postgres-client-cert
          certKey: tls.crt
          privateKey: tls.key

Create the client certificate secret:

kubectl -n netbox create secret tls postgres-client-cert \
  --cert=path/to/client.crt \
  --key=path/to/client.key

Step 5: Install or Upgrade

helm upgrade --install netbox-enterprise \
  oci://registry.enterprise.netboxlabs.com/library/nbe-operator \
  --namespace netbox \
  --values netbox-values.yaml

Step 6: Verify Connectivity

Check the operator logs for successful database connection:

kubectl -n netbox logs -l app.kubernetes.io/name=nbe-operator --tail=50

Check the NetBoxEnterprise status:

kubectl -n netbox get netboxenterprises -o wide
kubectl -n netbox describe netboxenterprise netbox

The PostgreSQL component status should show ready: true.

SSL Mode Reference

Mode	Certificate Required	Description
disable	No	No SSL
allow	No	Try non-SSL first, fall back to SSL
prefer	No	Try SSL first, fall back to non-SSL
require	No	SSL required, no verification
verify-ca	CA cert	SSL required, verify server certificate
verify-full	CA cert	SSL required, verify certificate and hostname

note

When CA certificates are configured via keychainCaCertificates, libpq verifies the server certificate even with sslmode: require. See PostgreSQL TLS for details.

Next Steps

• PostgreSQL Configuration — Full reference
• Security — TLS best practices