Feat: Allow certs for PostgreSQL connections

CHANGELOG.md

@@ -4,11 +4,13 @@
 
 ### Security
 - **Bumped CloudNative-PG dependency from chart 0.27.0 (app 1.28.0) to 0.28.1 (app 1.29.1)** to pick up the fix for [CVE-2026-44477 / GHSA-423p-g724-fr39](https://github.com/cloudnative-pg/cloudnative-pg/security/advisories/GHSA-423p-g724-fr39): a privilege-escalation vulnerability in the CNPG metrics exporter that could allow a low-privilege PostgreSQL user to escalate to superuser and execute arbitrary commands in the database pod. Operators upgrading via `helm upgrade` will get the patched CNPG operator automatically.
+- **Hardened PostgreSQL `pg_hba` rules**: The operator no longer emits the permissive `host all all 0.0.0.0/0 trust` / `host all all ::0/0 trust` rules that allowed passwordless PostgreSQL connections from any address. Non-replication access is now limited to `host all all localhost trust` (the gateway sidecar, which connects over the shared pod loopback), and cross-instance/cross-region replication uses `hostssl replication streaming_replica all cert`. Clients that previously relied on unauthenticated direct PostgreSQL access over the pod network will be rejected after upgrade; use the DocumentDB gateway (SCRAM-SHA-256) for application traffic. In multi-region deployments where `spec.tls.postgres` is not set, replication falls back to `host replication streaming_replica all trust`, which relies entirely on network-layer security (e.g. an Istio/service-mesh mTLS boundary) — provide `spec.tls.postgres` certificates to require TLS client certificates for replication instead.
 
 ### Major Features
 - **io_uring opt-in feature gate**: A new `IOUring` feature gate (`spec.featureGates.IOUring: true`) enables PostgreSQL 18 asynchronous I/O (`io_method=io_uring`). Because the container runtime's default seccomp profile strips the `io_uring_setup/enter/register` syscalls, the operator also relaxes the postgres container seccomp profile — pointing the pods at a hardened Localhost profile that re-allows only those three syscalls — when the gate is on, so no external Kyverno policy is needed. It is **opt-in** (default off) since io_uring relaxes the sandbox. The Localhost profile path is operator-level config via the Helm value `operator.ioUring.seccompProfile` (default `profiles/documentdb-iouring.json`). See [io_uring documentation](docs/operator-public-documentation/io-uring.md) and the [feature playground](documentdb-playground/io-uring-feature/).
 - **Gateway OTLP metrics in the per-pod sidecar**: when `spec.monitoring.enabled=true`, the OTel Collector sidecar now exposes an OTLP/gRPC receiver on `127.0.0.1:4317` and the documentdb-gateway is configured (via `OTEL_EXPORTER_OTLP_ENDPOINT` and `OTEL_METRICS_ENABLED`) to push its `db_client_*` metrics there. The sidecar's existing prometheus exporter re-exports them alongside the existing `documentdb.postgres.up` sqlquery output, with per-pod attribution added by the collector's resource processor. No new CRD fields; this turns on automatically wherever monitoring was already enabled.
 - **Two-Phase Extension Upgrade**: New `spec.schemaVersion` field separates binary upgrades (`spec.documentDBVersion`) from irreversible schema migrations (`ALTER EXTENSION UPDATE`). The default behavior gives you a rollback-safe window — update the binary first, validate, then finalize the schema. Set `schemaVersion: "auto"` for single-step upgrades in development environments. See the [upgrade guide](docs/operator-public-documentation/preview/operations/upgrades.md) for details.
+- **PostgreSQL/replication TLS via `spec.tls.postgres`**: A new `spec.tls.postgres` field (backed by CloudNative-PG's `CertificatesConfiguration`) lets you supply your own CA and certificate Secrets for PostgreSQL server and replication connections instead of the CloudNative-PG self-signed defaults. Supported keys are `serverTLSSecret` + `serverCASecret` (server certificate) and `replicationTLSSecret` + `clientCASecret` (the `streaming_replica` client certificate). A CEL validation rule enforces the pairing invariants: server and replication secrets must each be provided together, and `serverTLSSecret` requires `replicationTLSSecret`. When client certificates are provided, cross-region `externalClusters` connect with `sslmode=require` (or `verify-full` when a server CA is present) and present the replication client certificate. See the [TLS configuration guide](docs/operator-public-documentation/preview/configuration/tls.md).
 
 ### Breaking Changes
 - **CRD restructure into domain-grouped stanzas**: image, postgres and plugin fields have moved into dedicated groups. Migrate as follows: `spec.documentDBImage` → `spec.image.documentDB`, `spec.gatewayImage` → `spec.image.gateway`, `spec.postgresImage` → `spec.image.postgres`, `spec.sidecarInjectorPluginName` → `spec.plugins.sidecarInjectorName`. A new `spec.postgres` group exposes `uid`, `gid` and `postInitSQL` (the operator's mandatory bootstrap statements always run first; user statements are appended after). A new root-level `spec.imagePullSecrets` is propagated to the underlying CNPG cluster.

docs/crd-ref-docs-config.yaml

@@ -22,3 +22,6 @@ render:
     - name: AffinityConfiguration
       package: github.com/cloudnative-pg/cloudnative-pg/api/v1
       link: https://pkg.go.dev/github.com/cloudnative-pg/cloudnative-pg/api/v1#AffinityConfiguration
+    - name: CertificatesConfiguration
+      package: github.com/cloudnative-pg/cloudnative-pg/api/v1
+      link: https://pkg.go.dev/github.com/cloudnative-pg/cloudnative-pg/api/v1#CertificatesConfiguration

docs/operator-public-documentation/preview/api-reference.md

@@ -376,19 +376,7 @@ _Appears in:_
 | `uid` _integer_ | UID is the numeric user ID under which the PostgreSQL server process runs.<br />When set, GID must also be set. |  | Optional: \{\} <br /> |
 | `gid` _integer_ | GID is the numeric group ID under which the PostgreSQL server process runs.<br />When set, UID must also be set. |  | Optional: \{\} <br /> |
 | `postInitSQL` _string array_ | PostInitSQL is an ordered list of SQL statements executed after the<br />cluster is initialized. These statements run AFTER the operator's<br />mandatory bootstrap (CREATE EXTENSION documentdb, CREATE ROLE<br />documentdb, ALTER ROLE documentdb), so they can safely reference the<br />documentdb extension and role. |  | Optional: \{\} <br /> |
-
-
-#### PostgresTLS
-
-
-
-PostgresTLS acts as a placeholder for future Postgres TLS settings.
-
-
-
-_Appears in:_
-- [TLSConfiguration](#tlsconfiguration)
-
+| `parameters` _object (keys:string, values:string)_ | Parameters allows users to override PostgreSQL configuration parameters<br />(postgresql.conf settings) passed through to the underlying CNPG Cluster.<br />The operator applies memory-aware defaults (shared_buffers, effective_cache_size,<br />work_mem, maintenance_work_mem) computed from the pod memory limit, plus static<br />best-practice defaults for autovacuum, IO, WAL, and connection settings.<br />Values specified here override computed and static defaults.<br />Protected parameters (cron.database_name, max_replication_slots, max_wal_senders,<br />max_prepared_transactions) cannot be overridden. |  | Optional: \{\} <br /> |
 
 
 #### PrometheusExporterSpec
@@ -454,6 +442,8 @@ _Appears in:_
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
 | `storage` _[StorageConfiguration](#storageconfiguration)_ | Storage configuration for DocumentDB persistent volumes. |  |  |
+| `memory` _string_ | Memory specifies the memory limit for each DocumentDB instance pod.<br />This value is passed to the CNPG Cluster's spec.resources.limits.memory<br />and spec.resources.requests.memory (Guaranteed QoS).<br />Memory-aware PostgreSQL parameters (shared_buffers, effective_cache_size, etc.)<br />are auto-computed from this value.<br />If not specified or set to "0", no memory limit is applied and static<br />defaults are used for memory-aware parameters.<br />Examples: "2Gi", "4Gi", "8Gi" |  | Optional: \{\} <br /> |
+| `cpu` _string_ | CPU specifies the CPU limit for each DocumentDB instance pod.<br />This value is passed to the CNPG Cluster's spec.resources.limits.cpu<br />and spec.resources.requests.cpu (Guaranteed QoS).<br />If not specified or set to "0", no CPU limit is applied.<br />Examples: "2", "4", "500m" |  | Optional: \{\} <br /> |
 
 
 #### ScheduledBackup
@@ -524,7 +514,7 @@ _Appears in:_
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
 | `gateway` _[GatewayTLS](#gatewaytls)_ | Gateway configures TLS for the gateway sidecar (Phase 1: certificate provisioning only). |  |  |
-| `postgres` _[PostgresTLS](#postgrestls)_ | Postgres configures TLS for the Postgres server (placeholder for future phases). |  |  |
+| `postgres` _[CertificatesConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/cloudnative-pg/api/v1#CertificatesConfiguration)_ | Postgres configures TLS for the Postgres server. |  |  |
 | `globalEndpoints` _[GlobalEndpointsTLS](#globalendpointstls)_ | GlobalEndpoints configures TLS for global endpoints (placeholder for future phases). |  |  |
 
 

docs/operator-public-documentation/preview/architecture/overview.md

@@ -309,7 +309,7 @@ flowchart LR
     NEW_PVC --> NEW_CLUSTER
 ```
 
-For backup configuration, see [Backup and Restore](../backup-and-restore.md).
+For backup configuration, see [Backup and Restore](../operations/backup-and-restore.md).
 
 ## Dependencies
 

docs/operator-public-documentation/preview/configuration/tls.md

@@ -1,13 +1,13 @@
 ---
-title: TLS Configuration
-description: Configure TLS certificate management for DocumentDB gateway connections — SelfSigned, CertManager, and Provided modes, private CA guidance, certificate rotation, and troubleshooting.
+title: TLS configuration
+description: Configure TLS certificate management for DocumentDB gateway and PostgreSQL connections, including SelfSigned, CertManager, and Provided modes, private CA guidance, certificate rotation, and troubleshooting.
 tags:
   - configuration
   - tls
   - security
 ---
 
-# TLS Configuration
+# TLS configuration
 
 !!! warning "Breaking change in this release"
     The `Disabled` TLS mode has been removed. If you previously set `spec.tls.gateway.mode: Disabled`, update it to `SelfSigned` (or remove the field — `SelfSigned` is now the default). See the [CHANGELOG](https://github.com/documentdb/documentdb-kubernetes-operator/blob/main/CHANGELOG.md) for details.
@@ -259,6 +259,94 @@ Example TLS status output:
 }
 ```
 
+## PostgreSQL certificates
+
+The `spec.tls.gateway` settings above secure client connections to the DocumentDB gateway. A separate field, `spec.tls.postgres`, configures the certificates that CloudNative-PG uses for PostgreSQL server and replication connections.
+
+In a single-region deployment, CloudNative-PG provisions self-signed certificates automatically. You don't need to set `spec.tls.postgres` unless you want PostgreSQL inter-pod, intra-Kubernetes-cluster connections to use certificate material from your own CA instead of the CloudNative-PG generated self-signed certificates.
+
+When you provide PostgreSQL certificate Secrets, the operator passes them to the underlying CloudNative-PG `Cluster`. This changes the certificates used between DocumentDB instance pods inside the same Kubernetes cluster; it doesn't change how clients connect to the DocumentDB gateway.
+
+```yaml title="documentdb-postgres-provided-certs.yaml"
+apiVersion: documentdb.io/preview
+kind: DocumentDB
+metadata:
+  name: my-documentdb
+  namespace: default
+spec:
+  nodeCount: 1
+  instancesPerNode: 3
+  resource:
+    storage:
+      pvcSize: 100Gi
+  tls:
+    postgres:
+      replicationTLSSecret: postgres-replication-cert
+      clientCASecret: postgres-replication-cert
+      serverTLSSecret: postgres-server-cert
+      serverCASecret: postgres-server-cert
+```
+
+!!! note
+    `replicationTLSSecret` and `clientCASecret` must be provided together. `serverTLSSecret` and `serverCASecret` must be provided together, and `serverTLSSecret` requires `replicationTLSSecret`.
+
+### Replication client certificate name
+
+The PostgreSQL replication client certificate referenced by `replicationTLSSecret` must authenticate as the `streaming_replica` PostgreSQL role. The Kubernetes Secret name can be any name that you reference from `spec.tls.postgres.replicationTLSSecret`, but the certificate identity must use `streaming_replica` as the common name.
+
+If you create the client certificate with cert-manager, set `spec.commonName` to `streaming_replica` and include the `client auth` usage:
+
+```yaml title="postgres-replication-certificate.yaml"
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: postgres-replication-cert
+  namespace: default
+spec:
+  secretName: postgres-replication-cert
+  usages:
+    - client auth
+  commonName: streaming_replica
+  issuerRef:
+    name: my-ca-issuer
+    kind: Issuer
+    group: cert-manager.io
+```
+
+### Server certificate SANs
+
+The PostgreSQL server certificate referenced by `serverTLSSecret` must include the CloudNative-PG read-write Service names for the DocumentDB object as Subject Alternative Names (SANs). In a single-region deployment, the operator uses the DocumentDB object name as the CloudNative-PG cluster name.
+
+For a DocumentDB object named `my-documentdb` in the `default` namespace, include all three service-name forms:
+
+- `my-documentdb-rw`
+- `my-documentdb-rw.default`
+- `my-documentdb-rw.default.svc`
+
+If you create the server certificate with cert-manager, put these names in `spec.dnsNames`:
+
+```yaml title="postgres-server-certificate.yaml"
+apiVersion: cert-manager.io/v1
+kind: Certificate
+metadata:
+  name: postgres-server-cert
+  namespace: default
+spec:
+  secretName: postgres-server-cert
+  usages:
+    - server auth
+  dnsNames:
+    - my-documentdb-rw
+    - my-documentdb-rw.default
+    - my-documentdb-rw.default.svc
+  issuerRef:
+    name: my-ca-issuer
+    kind: Issuer
+    group: cert-manager.io
+```
+
+For cross-Kubernetes-cluster replication, see [Replication TLS (PostgreSQL)](../multi-region-deployment/setup.md#replication-tls-postgresql).
+
 ## Additional resources
 
 The [`documentdb-playground/tls/`](https://github.com/documentdb/documentdb-kubernetes-operator/tree/main/documentdb-playground/tls) directory provides automated scripts and end-to-end guides for TLS setup on AKS:

docs/operator-public-documentation/preview/getting-started/deploy-on-aks.md

@@ -72,7 +72,7 @@ For available classes, see
 
 - [AKS storage classes](https://learn.microsoft.com/azure/aks/concepts-storage#storage-classes)
 - [Azure Disk CSI driver on AKS](https://learn.microsoft.com/azure/aks/azure-disk-csi)
-- [DocumentDB storage configuration](../advanced-configuration/README.md#storage-configuration)
+- [DocumentDB storage configuration](../configuration/storage.md)
 
 ## Monitoring and troubleshooting
 
@@ -111,7 +111,7 @@ kubectl get pods -n kube-system | grep csi-azuredisk
   enabled
 - [Encryption at rest](https://learn.microsoft.com/azure/aks/enable-host-encryption)
   on managed disks
-- [TLS configuration](../advanced-configuration/README.md#tls-configuration)
+- [TLS configuration](../configuration/tls.md)
   for database traffic
 - [Azure RBAC integration](https://learn.microsoft.com/azure/aks/manage-azure-rbac)
 

docs/operator-public-documentation/preview/multi-region-deployment/overview.md

@@ -156,7 +156,14 @@ an equal or greater volume of available storage compared to the primary.
 Enable TLS for all connections:
 
 - **Client-to-gateway:** Encrypt application connections (see [TLS configuration](../configuration/tls.md))
-- **Replication traffic:** PostgreSQL SSL for inter-cluster replication
+- **Replication traffic:** Cross-Kubernetes-cluster streaming replication supports
+  two TLS paths. Path 1 uses `spec.tls.postgres.replicationTLSSecret` and
+  `clientCASecret` with `sslmode=require`.
+  Path 2 adds `serverTLSSecret` and `serverCASecret` and uses
+  `sslmode=verify-full` for server identity verification and mutual TLS (mTLS).
+  Configure shared certificate Secrets across all member Kubernetes clusters.
+  See [Replication TLS (PostgreSQL)](setup.md#replication-tls-postgresql) for
+  the complete setup.
 - **Service mesh:** mTLS for cross-cluster service communication
 
 ### Authentication and authorization