CloudNative-PG

Kubernetes operator for managing PostgreSQL clusters natively.

CloudNative-PG (CNPG) is a CNCF project that manages the full lifecycle of PostgreSQL clusters on Kubernetes via a Cluster CRD. It handles primary/replica streaming replication, automatic failover, point-in-time recovery, and scheduled backups. It is used in this cluster as the standard PostgreSQL provider — all apps that need a relational database deploy a CNPG Cluster rather than a standalone StatefulSet.

Alternatives considered

Self Hosted

Tool	Open Source	Full Features	Notes
Zalando Postgres Operator	Yes	Yes	Alternative k8s Postgres operator with Patroni
KubeDB	Partial	Yes	Multi-database operator; commercial for full features
Bitnami PostgreSQL chart	Yes	Partial	Simple StatefulSet; no operator-level HA

Installation

Architecture

HelmRelease cloudnative-pg in namespace cnpg-system, consuming the chart through chartRef from an OCIRepository at oci://ghcr.io/cloudnative-pg/charts/cloudnative-pg. CRDs installed via crds.create: true. Cluster-wide operator (config.clusterWide: true). Manages Cluster, Backup, ScheduledBackup, Pooler, and Database CRDs across all namespaces.

Security

Pod and container securityContext hardened: runAsNonRoot: true, runAsUser/Group: 10001, fsGroup: 10001, seccompProfile: RuntimeDefault, allowPrivilegeEscalation: false, capabilities: drop: ALL, readOnlyRootFilesystem: true. Webhook failurePolicy: Ignore set as a temporary workaround for a known upstream issue (#6271). RBAC is cluster-wide.

Updates

Managed by Renovate, which bumps the OCIRepository tag. Flux verifies the chart artifact with cosign keyless (verify.provider: cosign) before it is unpacked: the signature must come from the GitHub Actions OIDC issuer with the cloudnative-pg/charts release-publish.yml workflow as subject, so a tampered or re-published chart is rejected at the source, not at install time.

Usage

Applications deploy a Cluster resource to request a PostgreSQL cluster. CNPG provisions primary and replica pods, a read-write service, a read-only service, and manages credentials via Secrets. Backups are configured with ScheduledBackup resources pointing to an S3-compatible store. Apps annotate their CNPG clusters with k8up.io/backupcommand for logical dump backups via k8up.

Cluster-specific deviations from the above live in the per-cluster README — see k8s/platform/cloudnative-pg/talos/README.md.

Cluster Deployment

Talos

Used by on this cluster

• baserow
• bubbles
• cairn
• gatus
• gitea
• immich
• ironscan
• keycloak
• loupe
• memos
• miniflux
• n8n
• nextcloud
• outline
• paperless
• prefect
• romm
• tandoor
• vaultwarden
• vikunja
• voyage

CloudNative-PG — Talos cluster

Kubernetes Metadata

• HelmRelease: cloudnative-pg@0.29.1
• HelmRepo: cloudnative-pg (oci://ghcr.io/cloudnative-pg/charts/cloudnative-pg)

Rendered manifests (kustomize build)

apiVersion: v1
data:
  values.yaml: |
    crds:
      create: true
    config:
      clusterWide: true
      data:
    #    INHERITED_ANNOTATIONS: k8up.io/*
    # -- Operator resources
    resources:
      limits:
        memory: 200Mi
      requests:
        cpu: 10m
        memory: 200Mi
    # temporary fix for https://github.com/cloudnative-pg/cloudnative-pg/issues/6271
    webhook:
      mutating:
        failurePolicy: Ignore
      validating:
        failurePolicy: Ignore
kind: ConfigMap
metadata:
  name: cnpg-values-gmdfmdb872
  namespace: cnpg-system

Edge

Used by on this cluster

• openbeehive
• seitenraum

CloudNative-PG — Edge cluster

Deviations from defaults

None. The edge overlay is a byte-for-byte copy of the Talos one apart from comments — same base OCIRepository and HelmRelease, same cnpg-values.yaml (cluster-wide operator, CRDs from the chart, failurePolicy: Ignore on both webhooks, identical operator resources).

Kubernetes Metadata

• HelmRelease: cloudnative-pg@0.29.1
• HelmRepo: cloudnative-pg (oci://ghcr.io/cloudnative-pg/charts/cloudnative-pg)

Rendered manifests (kustomize build)

apiVersion: v1
data:
  values.yaml: |
    crds:
      create: true
    config:
      clusterWide: true
      data:
    resources:
      limits:
        memory: 200Mi
      requests:
        cpu: 10m
        memory: 200Mi
    # temporary fix for https://github.com/cloudnative-pg/cloudnative-pg/issues/6271
    webhook:
      mutating:
        failurePolicy: Ignore
      validating:
        failurePolicy: Ignore
kind: ConfigMap
metadata:
  name: cnpg-values-gh892b95gh
  namespace: cnpg-system