External Database

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

Prerequisites

PostgreSQL 15 or later (PostgreSQL 18 recommended). From NetBox Enterprise 2.4.0, the database migration stops on PostgreSQL 14 or earlier.
The ltree extension. The NetBox database role must be able to run CREATE EXTENSION ltree. NetBox 4.7 stores hierarchies, such as regions and locations, in an ltree column. ltree is a trusted extension, so the role does not need superuser permission, but without it the upgrade to 2.4.0 fails.
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;

GRANT ALL PRIVILEGES ON DATABASE includes the CREATE privilege. The netbox role needs it to create the trusted ltree extension. If your policy does not give that privilege, connect to the netbox database as an administrator and run CREATE EXTENSION IF NOT EXISTS ltree; before you install or upgrade.

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/netbox-enterprise/stable-v2/netbox-enterprise \
  --version 2.4.0 \
  --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

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

On this page