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.

Example with redundancy and resource limits:

netboxEnterprise:
  spec:
    postgresql:
      external: false
      instances: 2
      version: "18"
      storageSize: "20Gi"
      resources:
        cpu: 500
        memory: 1024
      limits:
        cpu: 2000
        memory: 2048

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.

Backups

From 2.3.0, pgBackRest makes PostgreSQL backups of the internal database. PGO runs pgBackRest for the operator. PostgreSQL backups are on by default, and they run on a schedule. They stay in the cluster, so you also need disaster recovery backups with Velero. See Backups for disaster recovery backups, and PostgreSQL Backups and Disaster Recovery for the terms, the schedule, the retention, and the restore procedure.

netboxEnterprise:
  spec:
    postgresql:
      backups:
        enabled: true
        repoStorageSize: 16Gi
        retentionFull: 4
        fullSchedule: "0 1 * * 0"
        incrementalSchedule: "0 1 * * 1-6"

The repository PVC is separate from the PostgreSQL data PVC, and it is larger by default. To size it, see Repository size and retention. For the default size of each volume, the result of a size change, and how to measure the usage, see Volume sizes and disk space.

The operator ignores this section when postgresql.external is true. An external database has no repository.

External PostgreSQL

Set postgresql.external: true to use an externally managed PostgreSQL instance. It must be PostgreSQL 15 or later. 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.

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:

SSL Modes

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:

Next Steps

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