PostgreSQL Configuration

NetBox Enterprise supports two PostgreSQL deployment modes:

• Internal (default): Managed by the Crunchy Postgres Operator (PGO), installed as a chart dependency
• External: Connect to an existing PostgreSQL instance you manage

Internal PostgreSQL (Default)

When postgresql.external: false (the default), the operator deploys a PostgresCluster resource that PGO manages.

Key	Type	Default	Description
postgresql.external	bool	false	Use internal PostgreSQL
postgresql.instances	uint8	1	Number of PostgreSQL replicas for redundancy (0–255)
postgresql.version	string	18	PostgreSQL major version
postgresql.storageSize	string	4Gi	Storage size for each PostgreSQL instance
postgresql.storageClassName	string	—	Storage class (uses cluster default if not set)
postgresql.registry	string	—	Container registry override for PGO images

Example with redundancy:

netboxEnterprise:
  spec:
    postgresql:
      external: false
      instances: 2
      version: "18"
      storageSize: "20Gi"

PGO automatically handles:

• Database creation (netbox, diode, hydra databases)
• User management and credential rotation
• Replication between primary and replica instances
• Failover and recovery

The operator detects PGO password rotations automatically using resourceVersion-based change detection and triggers rolling updates without reading sensitive secret data.

External PostgreSQL

Set postgresql.external: true to use an externally managed PostgreSQL instance.

netboxEnterprise:
  spec:
    postgresql:
      external: true

When using an external database, you must provide connection details through netbox.config.postgres:

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

Host and port are configured via postgresqlProfiles (see below).

You can disable PGO entirely when using an external database:

pgo:
  enabled: false

See the External Database Guide for a complete step-by-step walkthrough.

PostgreSQL Profiles

When multiple components (NetBox, Diode, Hydra) connect to the same PostgreSQL server, define a named profile in postgresqlProfiles so connection details and TLS settings are specified once:

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

    postgresql:
      external: true
      postgresqlProfile: netbox

    diode:
      config:
        reconciler:
          postgres:
            postgresqlProfile: netbox
            password:
              name: diode-db-credentials
              key: password
      hydra:
        postgresqlProfile: netbox

Each component references the profile by name and provides only its own password secret. See the NetBoxEnterprise CRD for the full profile field reference.

TLS Configuration

TLS for PostgreSQL connections is configured through postgresqlProfiles:

Key	Type	Default	Description
postgresqlProfiles.<name>.tlsConfig.sslmode	enum	prefer	SSL mode for connections
postgresqlProfiles.<name>.tlsConfig.insecureSkipVerify	bool	false	Skip TLS verification (dev only)
postgresqlProfiles.<name>.tlsConfig.keychainCaCertificates	list	—	CA certificate names from tlsKeychain
postgresqlProfiles.<name>.tlsConfig.keychainClientCertificate	string	—	Client certificate name from tlsKeychain

SSL Modes

Mode	Description
disable	No SSL
allow	Try non-SSL first, then SSL
prefer	Try SSL first, then non-SSL (default)
require	SSL required, no certificate verification
verify-ca	SSL required, verify server CA
verify-full	SSL required, verify CA and hostname

note

When CA certificates are configured via keychainCaCertificates, libpq verifies the server certificate even with sslmode: require (effectively upgrading it to verify-ca behavior). This is because the operator sets PGSSLROOTCERT when CA certificates are provided. Ensure the CA certificate matches the server, or omit it to use require without verification.

TLS with CA Verification

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

    postgresql:
      external: true
      postgresqlProfile: netbox

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

TLS with Client Certificates (mTLS)

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

    postgresql:
      external: true
      postgresqlProfile: netbox

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

Database Users

When using internal PostgreSQL, PGO creates the following database users by default:

User	Database	Purpose
netbox	netbox	NetBox application
diode	diode	Diode reconciler (if Diode enabled)
hydra	hydra	Hydra OIDC server (if Diode enabled)

Next Steps

• External Database Guide — Full walkthrough
• Redis — Cache and queue configuration
• Security — TLS best practices