Configure TLS certificates for PostgreSQL connections

PGO requires TLS for every PostgreSQL connection — there is no option to run a cluster in plaintext mode. By default, PGO manages the full certificate lifecycle for you: it generates a self-signed root CA, a server certificate, and a replication client certificate, and rotates them automatically before they expire. If your organization requires certificates issued by an external authority, you can supply them via the customTLSSecret and customReplicationTLSSecret fields.

How PGO-managed PKI works

When no custom secret is provided, PGO creates and maintains three X.509 artifacts per cluster namespace:

Secret key	Content
`ca.crt`	Self-signed root CA certificate
`tls.crt`	Server leaf certificate signed by the root CA
`tls.key`	ECDSA private key for the server certificate

The root CA is stored in a namespace-scoped Secret named postgres-operator-ca-secret. Each PostgresCluster gets its own leaf certificate (in a separate Secret) with DNS SANs covering the cluster’s primary and replica Services. PGO checks the leaf certificate on every reconciliation and regenerates it when it reaches one-third of its remaining validity period.

One root CA secret is created per namespace. Multiple PostgresCluster resources in the same namespace share that CA, but each cluster gets its own leaf certificate.

Bring your own TLS certificates

To use certificates issued by your own CA, set spec.customTLSSecret on the PostgresCluster. This field is a Kubernetes SecretProjection, which lets you reference a Secret (and optionally remap key names) that PGO will mount at /pgconf/tls inside each PostgreSQL container.

If you set customTLSSecret, you must also set customReplicationTLSSecret. Both secrets must share the same CA certificate in their ca.crt key, or replication will fail to establish a TLS connection.

Required secret keys

Your secret must contain exactly these three keys:

Key	Content
`tls.crt`	PEM-encoded server certificate (may include the full chain)
`tls.key`	PEM-encoded private key for the server certificate
`ca.crt`	PEM-encoded CA certificate that signed both `tls.crt` and the replication client certificate

Creating the TLS secret

Generate or obtain your certificates

Produce a server certificate whose Subject Alternative Names include the cluster’s Service DNS names. For a cluster named hippo in the postgres-operator namespace, the primary Service DNS name follows the pattern:

hippo-primary.postgres-operator.svc
hippo-primary.postgres-operator.svc.cluster.local

You also need a separate client certificate for replication.

Create the Kubernetes Secrets

kubectl create secret generic hippo-server-tls \
  --from-file=tls.crt=server.crt \
  --from-file=tls.key=server.key \
  --from-file=ca.crt=ca.crt \
  --namespace postgres-operator

kubectl create secret generic hippo-replication-tls \
  --from-file=tls.crt=replication-client.crt \
  --from-file=tls.key=replication-client.key \
  --from-file=ca.crt=ca.crt \
  --namespace postgres-operator

Reference the secrets in your PostgresCluster

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PostgresCluster
metadata:
  name: hippo
  namespace: postgres-operator
spec:
  postgresVersion: 16
  customTLSSecret:
    name: hippo-server-tls
  customReplicationTLSSecret:
    name: hippo-replication-tls
  instances:
    - name: instance1
      replicas: 3
      dataVolumeClaimSpec:
        accessModes:
          - ReadWriteOnce
        resources:
          requests:
            storage: 1Gi

Using SecretProjection to remap keys

If your existing secret uses different key names, use the items field of the SecretProjection to remap them without modifying the secret itself:

spec:
  customTLSSecret:
    name: my-org-postgres-cert
    items:
      - key: server.crt
        path: tls.crt
      - key: server.key
        path: tls.key
      - key: root-ca.pem
        path: ca.crt
  customReplicationTLSSecret:
    name: my-org-replication-cert
    items:
      - key: client.crt
        path: tls.crt
      - key: client.key
        path: tls.key
      - key: root-ca.pem
        path: ca.crt

The path values in the items list must always be tls.crt, tls.key, and ca.crt — those are the file names that PostgreSQL is configured to read from /pgconf/tls.

Rotating certificates

PGO-managed PKI
Custom certificates

No action is required. PGO automatically generates a new leaf certificate when the existing one reaches one-third of its remaining lifetime and applies it without cluster downtime.

Update the Secret contents with the new certificate and key material. Kubernetes will propagate the change to mounted volumes within the kubelet sync period (default 60 seconds). PostgreSQL reloads its TLS configuration on SIGHUP without requiring a full restart.

kubectl create secret generic hippo-server-tls \
  --from-file=tls.crt=new-server.crt \
  --from-file=tls.key=new-server.key \
  --from-file=ca.crt=ca.crt \
  --namespace postgres-operator \
  --dry-run=client -o yaml | kubectl apply -f -

Create a cluster — end-to-end example including TLS configuration
PostgresCluster reference — full spec field documentation
Authentication — configuring pg_hba.conf rules that enforce hostssl

Get Started

Installation

Core Operations

Day-Two Operations

Security

Configure TLS certificates for PostgreSQL connections

How PGO-managed PKI works

Bring your own TLS certificates

Required secret keys

Creating the TLS secret

Using SecretProjection to remap keys

Rotating certificates

​How PGO-managed PKI works

​Bring your own TLS certificates

​Required secret keys

​Creating the TLS secret

​Using SecretProjection to remap keys

​Rotating certificates

​Related pages

How PGO-managed PKI works

Bring your own TLS certificates

Required secret keys

Creating the TLS secret

Using SecretProjection to remap keys

Rotating certificates

Related pages