Skip to content

About

OpenEverest provider that provisions PostgreSQL HA clusters on Kubernetes via CloudNativePG.

Topics

Resources

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Repository files navigation

CloudNativePG Provider

Warning

Pre-alpha. OpenEverest v2 and this provider are under active development. CRD schemas, chart values and defaults change frequently, including in breaking ways, and there is no supported upgrade path between versions yet. Not for production use.

Status CI Release Go Reference License

Run PostgreSQL on Kubernetes through OpenEverest, backed by CloudNativePG.

What this is

OpenEverest providers translate a single, technology-agnostic Instance custom resource into the native custom resources of an upstream Kubernetes operator — for databases, but equally for caches, message queues, object storage, or model-serving runtimes. This repository is the provider for PostgreSQL via CloudNativePG: it owns the technology-specific knowledge — topologies, versions, parameters, backup wiring — so that users, the API server, and the UI stay technology-agnostic.

Important

This provider is not standalone. It requires an OpenEverest installation (core CRDs and controller) in the cluster. Installing this chart on its own does nothing. See Install OpenEverest.

flowchart LR
    U([User / API / UI]) -->|creates| I["Instance<br/>core.openeverest.io"]
    I --> P["provider-cloudnative-pg<br/>(this repository)"]
    P -->|reconciles into| O["Cluster<br/>postgresql.cnpg.io/v1"]
    O --> W["CloudNativePG"]
    W --> R[("Pods, Services,<br/>Secrets, PVCs")]
    P -->|status, endpoints,<br/>credentials| I
Loading

The provider watches Instance resources whose spec.providerRef.name is provider-cloudnative-pg, and reports workload health back onto Instance.status. It never manages pods directly — all lifecycle work is delegated to the operator.

Compatibility

provider-cloudnative-pg OpenEverest CloudNativePG Kubernetes
0.2.x 2.0.0-dev.2 1.29.x 1.30 – 1.34
main main after 2.0.0-dev.4 (admission webhook, openeverest/openeverest#3362) 1.30.x 1.34 – 1.36

Capabilities

What you can do to a running instance through the Instance API. Upgrading the provider itself is covered under Installation.

Capability Status Notes
Provisioning ✅
Horizontal scaling ✅ spec.components.engine.replicas
Vertical scaling (CPU / memory) ✅ spec.components.engine.resources
Version upgrades ✅ of the deployed PostgreSQL version — change spec.version; see Versions
Custom configuration ✅ PostgreSQL GUCs via spec.components.engine.parameters.postgresql
Bootstrap (initdb) ✅ database name, owner, and credentials secret
Bootstrap from a VolumeSnapshot ✅ bootstrap.volumeSnapshot.name: start from a snapshot of another instance's volume; see Start from a volume snapshot
Managed roles ✅ CloudNativePG managed roles with readiness gating in Status()
Synchronous replication ✅ parameters.postgresql.synchronous; see Synchronous replication
Logical replication slot failover ✅ parameters.replicationSlots.highAvailability.synchronizeLogicalDecoding (PostgreSQL 17+); see Logical replication slot failover
TLS-only connections ✅ parameters.requireTLS: true rejects unencrypted client connections; see Require TLS
Client access rules (pg_hba) ✅ parameters.pgHBA declares which clients may connect to which databases as which users; see Client access rules
Connection pooling ✅ optional proxy component → CloudNativePG Pooler (PgBouncer, type rw); see Connection pooling
Pod scheduling ✅ spec.components.engine.schedulingPolicy (all fields), or parameters.affinity — not both
Pod priority ✅ parameters.priorityClassName → CloudNativePG spec.priorityClassName; the PriorityClass must exist, and changing it rolls the instance pods
Monitoring ✅ Prometheus: a PodMonitor for the instance pods via spec.topology.parameters.monitoring.prometheus; requires the Prometheus Operator. See Scrape metrics with Prometheus

Extensions

First-class toggles under spec.components.engine.parameters.extensions.<name>.enabled. The provider runs CREATE EXTENSION for each enabled one in the application database through a single CNPG Database resource (<instance>-extensions). Extensions not in the standard operand images are mounted as image volumes: these need PostgreSQL 18 and Kubernetes ImageVolume (1.35+, or 1.33/1.34 + feature gate), and adding one restarts the instances.

The image-volume images come from a CloudNativePG ClusterImageCatalog that the chart renders from extensionCatalog in its values (default: the official CloudNativePG trixie builds plus AGE, TimescaleDB Community, pg_cron and pg_repack from solanicaio/postgresql-extensions). The provider copies the catalog entry of each enabled extension (image, paths, env) into the Cluster and passes the sqlVersion value to CREATE EXTENSION, so admins can bump or mirror images with helm upgrade, or set extensionCatalog.create=false and point extensionCatalog.name at a catalog they manage (the SQL versions go in sql-version.extensions.openeverest.io/<major>.<name> annotations), without upgrading the provider. A new image restarts the instances that use it.

PostgreSQL minor releases can break the extension ABI (18.7 did), so one extension can have several builds per major. Give each one a minVersion (inclusive) and/or maxVersion (exclusive) PostgreSQL release, and set extension on entries whose name differs from the extension they provide:

- name: pg-cron                # PostgreSQL 18.7+
  minVersion: "18.7"
  image: {reference: ghcr.io/solanicaio/pg-cron:<18.7 build>}
- name: pg-cron-pre-18-7       # older 18.x
  extension: pg-cron
  maxVersion: "18.7"
  image: {reference: ghcr.io/solanicaio/pg-cron:<older build>}

The provider mounts the one entry that covers the instance's version under the extension's name, so a minor upgrade swaps the PostgreSQL and extension images in one rollout. No match, or more than one, is a validation error. In a self-managed catalog these go in the extension., min-version. and max-version.extensions.openeverest.io/<major>.<name> annotations.

Extension Toggle Status Enable on a running instance Disable Notes
pgvector pgvector ✅ ✅ no restart ❌ PG 14–18, bundled in the standard images: no image change. See examples/instance-pgvector.yaml
pgAudit pgaudit ✅ ✅ restarts ✅ the operator drops it PG 14–18, bundled; sets pgaudit.log: "ddl, role" unless a value is set in postgresql.parameters, and the operator then preloads it and creates it in every database
pg_stat_statements pgStatStatements ✅ on by default ✅ restarts ✅ restarts, the operator drops it PG 14–18, bundled; on for new instances and exported as metrics. See Query statistics
TimescaleDB OSS timescaledb ✅ ❌ creation only ¹ ❌ Image volume, preloaded. See examples/instance-timescaledb.yaml
TimescaleDB Community ³ timescaledbCommunity ✅ ❌ creation only ¹ ❌ Image volume from solanicaio/postgresql-extensions, preloaded; PostgreSQL 18.6+; not together with timescaledb. See examples/instance-timescaledb-community.yaml
PostGIS postgis ✅ ✅ restarts ❌ Image volume
pgRouting pgrouting ✅ ✅ restarts ❌ Image volume; requires postgis
pg_ivm pgivm ✅ ❌ creation only ¹ ❌ Image volume, preloaded
wal2json wal2json ✅ ✅ restarts ✅ restarts Image volume; a logical decoding output plugin (no CREATE EXTENSION) — drop the replication slots that use it before disabling
Apache AGE age ✅ ❌ creation only ² ❌ Image volume from solanicaio/postgresql-extensions, preloaded. Run SET search_path = ag_catalog, "$user", public before using it
pg_cron pgcron ✅ ❌ creation only ¹ ² ❌ Image volume from solanicaio/postgresql-extensions, preloaded. See pg_cron
pg_repack pgrepack ✅ ✅ restarts ❌ Image volume from solanicaio/postgresql-extensions. See pg_repack

Extensions that are created in the database (everything but pgAudit and wal2json) cannot be disabled: dropping them would fail or destroy data, so the provider rejects it.

¹ Enforced by the provider: CloudNativePG advises against rolling out a new extension image and a shared_preload_libraries change together, and enabling them on a running instance does exactly that.

² Enforced by the provider: the application owner gets USAGE on ag_catalog (AGE) or cron (pg_cron) through default privileges set in postInitApplicationSQL, which only runs at bootstrap. Default privileges on schemas cannot be limited to one schema, so the owner also gets USAGE on any other schema the postgres superuser creates later in the application database.

³ TimescaleDB Community adds the features licensed under the Timescale License (TSL): columnstore compression, continuous aggregates, and compression, retention and refresh policies. The TSL is not open source: use it only for internal use or if you hold a license from Timescale. It prohibits offering TimescaleDB to third parties as a database service. Enabling the toggle is your acceptance of the TSL; the provider itself remains Apache-2.0. Timescale builds these binaries against the latest PostgreSQL minor, so they need PostgreSQL 18.6 or later. The editions use different binaries, so an instance cannot switch between them.

pg_cron

The provider sets cron.database_name to the application database, where it creates the extension, and cron.use_background_workers: "on": otherwise pg_cron opens libpq connections to localhost, which the CloudNativePG pg_hba rules reject without a password. Setting cron.database_name to another database is rejected. The application owner schedules jobs, which run as the user who scheduled them:

SELECT cron.schedule('nightly-vacuum', '0 3 * * *', 'VACUUM ANALYZE');
SELECT * FROM cron.job_run_details ORDER BY start_time DESC LIMIT 10;
SELECT cron.unschedule('nightly-vacuum');

Schedules use GMT unless cron.timezone is set. Jobs run only on the primary. Their definitions are rows in the database, not part of the Instance spec, so they are replicated, kept in backups, and resume on the new primary after a switchover or failover. Each running job uses a background worker, shared with parallel queries and logical replication through max_worker_processes (default 8). Raise it in postgresql.parameters if many jobs run at once.

pg_repack

pg_repack rebuilds bloated tables and indexes online, holding an exclusive lock only briefly. The provider creates the extension in the application database. Run the client as the postgres superuser in the primary's pod, where the image is mounted (tables need a primary key or a unique index on NOT NULL columns):

PRIMARY=$(kubectl get cluster <instance> -o jsonpath='{.status.currentPrimary}')
kubectl exec -it "$PRIMARY" -c postgres -- \
  /extensions/pg-repack/bin/pg_repack --dbname=app --table=public.my_table

Stateful workloads additionally report:

Capability Status Notes
Persistent storage ✅ spec.components.engine.storage
Storage expansion ✅ when the StorageClass allows volume expansion (resizeInUseVolumes)
Separate WAL volume ✅ spec.components.engine.parameters.walStorage maps directly to CNPG spec.walStorage
Backups (on demand) ✅ operator-native (executionMode: ProviderManaged) via the Barman Cloud Plugin; one backup storage per Instance (CNPG supports a single WAL archive)
Restore ✅ from a succeeded Backup via Barman
Scheduled backups ✅ spec.backup.storages[].schedules → CNPG ScheduledBackup; mirrored as OpenEverest Backup CRs
Schedule retention ✅ time-based recovery windows are delegated to CNPG/Barman via ObjectStore retentionPolicy; count-based retention is rejected
Backup deletion ✅ deletionPolicy: Delete removes the Barman base backup; Retain removes only the CNPG Backup resource
PITR ✅ restore to a point in time via spec.dataSource

Backup retention and deletion

CNPG retention uses the Barman Cloud Plugin's native recovery window:

retention:
  type: time
  duration: 30d

All schedules targeting the same storage, including disabled schedules, must specify the same duration or all omit retention (keep all). The window applies to that cluster's entire Barman archive, including on-demand backups and WAL, not independently to each schedule. Barman preserves the base backup needed to recover from the beginning of the window. Count retention is not supported. Instances in one namespace that use the same backup storage share its ObjectStore, so they must also agree on retention. An Instance whose retention would change the policy already stored is refused with a BackupRetentionConflict on its BackupConfigured condition. The OpenEverest dev.4 schedule form edits only count retention ("retention copies"), which this provider rejects. Leave copies at 0 and set time retention through the API or CLI. deletionPolicy: Retain skips explicit data deletion; it does not exempt a backup from Barman's archive-wide retention policy. If CNPG removes a backup resource during native catalog cleanup, its Everest record is reported as failed/unavailable rather than starting a replacement backup.

deletionPolicy: Delete runs a one-off barman-cloud-backup-delete Job (delete-backup-<name>) for the backup's Barman ID. The Job meets the restricted Pod Security Standard. Backups that never received a Barman ID (not started, or failed early) have no data to delete. If the Job fails, inspect its logs and delete the Job to retry. Data deletion runs only while the source Instance exists; delete Backups before deleting their Instance.

The backup integration and e2e suites check native policy configuration and per-backup deletion in the object store, not the passage of a multi-day recovery window.

Separate WAL volume

Configure WAL independently of the data volume:

In the UI, the Resources section exposes a Separate WAL storage toggle (OpenEverest dev.4 or later). It is off by default for new instances, keeping the single-volume layout. Enabling it reveals a required WAL disk size and an optional WAL storage class (selectable when WAL storage is first added, then fixed). Existing WAL settings turn the toggle on automatically. Dev.4 cannot lock the switch in edit mode, so validation blocks saving with the toggle off once separate WAL storage is configured.

spec:
  components:
    engine:
      storage:
        size: 20Gi
      parameters:
        walStorage:
          size: 5Gi
          storageClass: fast-storage
          resizeInUseVolumes: true

walStorage uses CNPG's native storage configuration, including optional pvcTemplate. Omit it to keep WAL on the data volume. Each PostgreSQL instance gets its own WAL PVC. Set a positive size (or a pvcTemplate storage request, as CNPG allows); omit storageClass to use the default StorageClass. The data-volume storage class is not inherited.

CNPG manages provisioning, migration when adding a WAL volume, and expansion. Once configured, WAL storage cannot be removed. CNPG validates updates and rejects shrinking volumes; expansion requires a StorageClass/CSI driver that supports it (allowVolumeExpansion: true). Adding a volume to an existing cluster can restart instances; follow CNPG's storage lifecycle guidance. This setting provisions storage, not a WAL disk-usage alert or monitoring policy.

Installation

The provider chart is published as an OCI artifact:

helm install provider-cloudnative-pg \
  oci://ghcr.io/openeverest/charts/provider-cloudnative-pg \
  --version 0.3.4 \
  --namespace everest-system
  • The CloudNativePG operator and the Barman Cloud Plugin (and their CRDs) are bundled as chart dependencies and are installed automatically (cloudnative-pg.enabled and plugin-barman-cloud.enabled both default to true). Set either to false to use an externally managed install instead.
  • The chart registers an admission webhook, so an invalid Instance is rejected when it is written, by kubectl, GitOps or the API, with every error and its field path; see Validation. Its serving certificate is generated by the chart and kept across upgrades; set admission.certManager.enabled=true to have cert-manager issue it, or supply one through admission.certs.

Important

Backups need the Barman Cloud Plugin. The plugin subchart is enabled by default and its admission webhooks require cert-manager in the cluster before installing this chart. Without the plugin (or its ObjectStore CRD), Instances report BackupConfigured=False with reason BarmanPluginMissing, and new Backups fail with that message instead of an opaque operator error.

Upgrade and uninstall:

helm upgrade provider-cloudnative-pg \
  oci://ghcr.io/openeverest/charts/provider-cloudnative-pg --version 0.3.4
helm uninstall provider-cloudnative-pg --namespace everest-system

Uninstalling the chart does not delete running Instance resources or their data.

Operator high availability

CloudNativePG performs PostgreSQL failover from the operator, so a primary that fails while no operator is running stays down until one returns. It also serves the admission webhooks for Cluster changes. The chart therefore runs the bundled operator highly available by default:

  • cloudnative-pg.replicaCount: 2. The replicas use leader election; when the leader disappears, the standby takes over once the lease expires (15 seconds by default, sooner if the leader shuts down gracefully) and then carries out any pending failover. Every replica serves the webhooks.
  • Preferred pod anti-affinity across nodes and a preferred spread across zones (cloudnative-pg.affinity, cloudnative-pg.topologySpreadConstraints). Neither is required, so single-node clusters still schedule both replicas.
  • A PodDisruptionBudget with minAvailable: 1, so node drains keep one operator running (cnpgOperatorPodDisruptionBudget; rendered only when replicaCount is above 1).

Set cloudnative-pg.replicaCount=1 to go back to a single operator, for example on development clusters. When you manage the operator yourself (cloudnative-pg.enabled=false), apply the same settings there.

Usage

Verify that the provider registered itself:

kubectl get providers.core.openeverest.io provider-cloudnative-pg

Create an instance:

apiVersion: core.openeverest.io/v1alpha1
kind: Instance
metadata:
  name: my-instance
spec:
  providerRef:
    name: provider-cloudnative-pg
  version: "18.7"
  components:
    engine:
      type: postgresql
      replicas: 3
      resources:
        requests:
          cpu: "1"
          memory: 1Gi
        limits:
          cpu: "1"
          memory: 1Gi
      storage:
        size: 5Gi

Component names are defined by this provider — see definition/provider.yaml. spec.version and spec.topology are optional; the provider defaults apply. More examples live in examples/, including TimescaleDB, pgvector, backups and schedules, on-demand backup, restore, PITR, pooler, and service exposure.

Connection details

Watch it come up and read the connection details:

kubectl get instance my-instance -w
kubectl get instance my-instance -o jsonpath='{.status.connectionSecretRef.name}'

The credentials (host, port, username, password, uri, sslmode, host-r, host-ro) live in the connection Secret named by .status.connectionSecretRef.name.

  • host is <cluster>-rw.<namespace>.svc, the read-write Service. With the proxy component set, host, port, and uri point at the pooler Service instead. host-r and host-ro stay on the PostgreSQL Services.
  • host-r is <cluster>-r.<namespace>.svc. That Service targets every ready instance, including the primary. It is omitted when the read Service is disabled.
  • host-ro is <cluster>-ro.<namespace>.svc. That Service targets ready replicas and excludes the primary, so it is published only when the read-only Service is enabled and replicas is at least 2.
  • port is the port key of the credential Secret. CloudNativePG writes 5432 there. A user-supplied basic-auth Secret may omit it, and then the port is 5432. The PostgreSQL Service port is not configurable. With the pooler enabled, port is 5432 because PgBouncer's listen_port is fixed.
  • sslmode is require, and uri includes it. CloudNativePG always serves TLS, so this works whether or not requireTLS is set. libpq's default prefer is not published.

node-postgres (pg-connection-string 2.7 and later) treats sslmode=prefer, require, and verify-ca as verify-full (ssl: true). That check fails for CloudNativePG's operator-managed server certificate. The CA certificate is the ca.crt key in the <cluster>-ca Secret, or in the Secret named by certificates.serverCASecret when you bring your own. Use that file as sslrootcert with sslmode=verify-full to authenticate the server. pg-connection-string also accepts sslmode=no-verify, which encrypts without checking the certificate. That value is not a libpq sslmode.

Scrape metrics with Prometheus

Every CloudNativePG instance pod serves its metrics exporter on port metrics (9187). With the Prometheus Operator in the cluster, enable Prometheus (the Monitoring → Prometheus toggle in the UI) to get a PodMonitor (<instance>-metrics) that scrapes it, over HTTPS when spec.components.engine.parameters.monitoring.tls.enabled is set. podMonitorLabels lets your Prometheus podMonitorSelector pick it up. Turning it off removes the PodMonitor.

spec:
  topology:
    type: replicaSet
    parameters:
      monitoring:
        prometheus:
          enabled: true
          podMonitorLabels:
            release: kube-prometheus-stack

The PodMonitor carries app.kubernetes.io/managed-by=everest and app.kubernetes.io/instance=<instance>, which the OpenEverest metrics plugin uses to find it. Don't combine it with CloudNativePG's deprecated monitoring.enablePodMonitor, which would scrape every pod twice; the provider rejects that combination.

Query statistics

New instances run pg_stat_statements: the provider sets pg_stat_statements.track: top, and the operator then preloads the extension and creates it in every database. Query it in SQL, for example the statements that took the most time:

SELECT queryid, calls, round(total_exec_time) AS total_ms, round(mean_exec_time, 2) AS mean_ms, query
FROM pg_stat_statements ORDER BY total_exec_time DESC LIMIT 10;

The provider also adds exporter queries (ConfigMap <instance>-pg-stat-statements, through monitoring.customQueriesConfigMap), so the statistics are scraped with the other metrics:

Metric Labels Content
cnpg_pg_stat_statements_top_{calls,exec_seconds,rows,shared_blks_hit,shared_blks_read,temp_blks_written} datname, username, queryid the 20 statements with the most execution time on each instance
cnpg_pg_stat_statements_database_{statements,calls,exec_seconds,rows} datname totals per database
cnpg_pg_stat_statements_info_{dealloc,stats_reset_time} statements evicted for lack of room, and the last reset

Statement metrics carry the queryid, never the query text; look a statement up with SELECT query FROM pg_stat_statements WHERE queryid = <queryid>. Each instance (primary and replicas) tracks the statements it runs.

The overhead is small for most workloads. The extension keeps up to pg_stat_statements.max statements (default 5000) in shared memory; when cnpg_pg_stat_statements_info_dealloc grows, less frequent statements are being evicted, and raising the limit keeps them at the cost of more shared memory. pg_stat_statements.track: all also tracks statements inside functions. Set these in spec.components.engine.parameters.postgresql.parameters; changing pg_stat_statements.max restarts the instances.

Instances created before the provider enabled it by default keep running without it, so an upgrade does not restart them, unless they set pg_stat_statements.* parameters. To turn it on for one of them, or off for any instance, set extensions.pgStatStatements.enabled (both restart the instances). While it is set to false, the provider rejects pg_stat_statements.* parameters, which would turn it back on.

The UI writes the toggle explicitly when it creates an instance. When editing an instance whose spec doesn't set it, the UI shows it off, as it is on instances created before the default, and saving the Extensions section writes false. For an instance created from Git or kubectl without the toggle (which runs the extension), set enabled: true in its spec before editing that section in the UI.

spec:
  components:
    engine:
      parameters:
        extensions:
          pgStatStatements:
            enabled: false

Topologies

Topology Default Description
replicaSet ✅ A CloudNativePG primary + standby cluster built from the engine component (default 3 instances)

The backupAgent and proxy components are optional. Prometheus scraping is a topology parameter (spec.topology.parameters.monitoring.prometheus), not a component.

Connection pooling

The proxy component (type pgbouncer) creates one CloudNativePG Pooler named <instance>-pooler. The operator refuses a Pooler whose name matches a Cluster, so the name carries that suffix. The Pooler's Service uses the same name and listens on port 5432 (listen_port is fixed by the operator).

The Pooler is type rw: PgBouncer forwards to the primary Service (<instance>-rw). poolMode is session or transaction (the operator default is session; it has no statement mode). The component's replicas is the Pooler's spec.instances (default 1). resources are set on the pgbouncer container. The operator selects the PgBouncer image. Auth stays on the operator's automated integration, which creates the cnpg_pooler_pgbouncer role, so clients keep using the application username and password.

While the component is set, host and uri in the connection Secret are the pooler (<instance>-pooler.<namespace>.svc). Removing the component deletes the Pooler and points host back at <instance>-rw.

The Instance is Ready only once the Pooler is active and its Deployment has replicas ready PgBouncer pods. Adding the component to a running instance returns it to Provisioning until then.

spec:
  components:
    proxy:
      type: pgbouncer
      replicas: 2
      resources:
        requests:
          cpu: 100m
          memory: 128Mi
        limits:
          cpu: 100m
          memory: 128Mi
      parameters:
        poolMode: transaction

PgBouncer presents the cluster's server certificate. sslmode=require works; verify-full checks a name that certificate is not issued for. See Connection details. With requireTLS the Pooler also refuses unencrypted clients (client_tls_sslmode=require).

Versions

Version bundle Default postgresql
18.7 ✅ 18.7 (ghcr.io/cloudnative-pg/postgresql:18.7-standard-trixie)
18.6 18.6
18.4 18.4
17.10 17.10
16.14 16.14
15.18 15.18
14.23 14.23

Source of truth: definition/versions.yaml.

Images follow CloudNativePG recommended practice (official CNPG operands, standard image type on Debian trixie). The operator must already support the target version — upgrade the provider chart first.

Configuration

  • Chart values: charts/provider-cloudnative-pg/values.yaml
  • Instance parameters: per-component and per-topology parameters schemas, defined under definition/ and published on the Provider resource (kubectl get provider provider-cloudnative-pg -o yaml). The provider rejects an Instance that does not match them (see Validation), and the UI checks the form against them as you type.

Validation

The provider validates an Instance when it is written, through its admission webhook, and again before every reconcile:

$ kubectl apply -f instance.yaml
The Instance "orders" is invalid: spec.components[engine].parameters.postgresql.synchronous: Invalid value: postgresql.synchronous.number (2) must be lower than the number of replicas (2) plus listed standby names
  • Checked at admission: the published parameter schemas, the version catalog and the provider's rules (resources, synchronous replication, extensions and the PostgreSQL version they need, scheduling, proxy, backup schedules and retention, the data source, Prometheus). Rules about changes are checked against the stored Instance: an extension created in the database cannot be turned off, and creation-only extensions cannot be turned on later.
  • Warnings: changes that restart the instances, such as turning on an image-volume or preloaded extension or changing priorityClassName, are admitted with a warning, which kubectl prints: Warning: spec.components[engine].parameters.extensions.pgaudit.enabled: Enabling pgaudit restarts the instances.
  • In a pull request: run kubectl apply --dry-run=server -f <instance>.yaml (or everestctl instance create|update --dry-run=server) in CI to get the same errors and warnings without changing anything.
  • Objects the Instance relies on (the extension images in the ClusterImageCatalog, the running Cluster) never block a write: at admission their problems are warnings, and the Instance reports them in its Ready condition.
  • An update is blocked only by new errors: an Instance written under an older provider release, or while the provider was down, stays editable.
  • Provider down: the webhook is skipped (failurePolicy: Ignore) so it can never block writes; the Instance then reports the errors as Ready=False with reason ValidationFailed.

The technology-specific knobs worth knowing about:

Parameter Applies to Purpose
bootstrap.initdb engine Initial database name, owner, and optional credentials Secret
bootstrap.volumeSnapshot.name engine Start from a VolumeSnapshot instead of an empty database; see Start from a volume snapshot
postgresql engine Full CloudNativePG PostgresConfiguration (GUCs, sync replicas, …)
extensions.* engine First-class extensions; see Extensions. TimescaleDB (both editions) also defaults timescaledb.telemetry_level=off and max_locks_per_transaction=128 unless set in postgresql.parameters
affinity engine CloudNativePG AffinityConfiguration; rejected together with schedulingPolicy affinity, nodeSelector or tolerations
managed engine Managed PostgreSQL roles
resizeInUseVolumes engine Allow PVC expansion on running instances
priorityClassName engine Kubernetes PriorityClass of the instance pods
certificates engine TLS certificate configuration passthrough
requireTLS engine Reject unencrypted client connections; see Require TLS
replicationSlots engine CloudNativePG ReplicationSlotsConfiguration (HA slots, user slot synchronization, logical slot failover); see Logical replication slot failover
pgHBA engine pg_hba.conf records, one per line; see Client access rules
monitoring engine CloudNativePG monitoring configuration (custom queries, metrics TLS, …)
monitoring.prometheus topology Create a PodMonitor for the instance; see Scrape metrics with Prometheus

Start from a volume snapshot

bootstrap.volumeSnapshot.name starts a new instance from a VolumeSnapshot of another instance's data volume, in the same namespace, instead of an empty database. The provider renders CloudNativePG's bootstrap.recovery.volumeSnapshots with no WAL source: PostgreSQL recovers the snapshot from its own pg_wal, as after a crash, so a crash-consistent snapshot of a running instance is enough and no WAL archive is needed. bootstrap.initdb's database and owner name the existing application database and owner, and the new instance gets its own credentials.

spec:
  components:
    engine:
      replicas: 1
      storage:
        size: 20Gi                  # the snapshot's size: some drivers can't resize clones
        storageClass: openebs-zfspv
      parameters:
        bootstrap:
          volumeSnapshot:
            name: orders-snapshot-1   # annotated bootstrap-instance: <this instance>
  • On storage whose snapshots are copy-on-write clones, such as OpenEBS ZFS LocalPV, the instance starts in seconds whatever the size. Take a CHECKPOINT right before the snapshot to keep recovery short.
  • The snapshot must be annotated provider-cloudnative-pg.openeverest.io/bootstrap-instance: <instance name>. Everest checks that a user may read an Instance's spec.dataSource, not its engine parameters: the annotation, which Everest users can't set, is what lets an Instance start from a snapshot. Until it's there, nothing is created and the Instance is Failed; the provider retries, so it starts once the snapshot is annotated.
  • The snapshot must hold PGDATA and WAL: it can't be combined with walStorage, nor with spec.dataSource. It's only read at creation and can't be changed afterwards.
  • Replicas of the new instance are made with pg_basebackup, a full copy.

The Branching plugin uses it to make instance branches.

Synchronous replication

Replication is asynchronous by default. To make each commit wait for standbys, set CloudNativePG's synchronous configuration (the UI exposes it as the Synchronous replication toggle under Resources):

spec:
  components:
    engine:
      replicas: 3
      parameters:
        postgresql:
          synchronous:
            method: any           # any = quorum, first = priority order
            number: 1             # standbys that must confirm each commit
            dataDurability: required
  • number must be lower than replicas (plus any listed standby names); the provider rejects other values before applying the Cluster.
  • With the default synchronous_commit = on, a commit returns once the required standbys have flushed its WAL to durable storage. Set postgresql.parameters.synchronous_commit to remote_apply to also wait until the change is visible on them, or remote_write for a weaker guarantee. Applications can lower synchronous_commit per transaction, and those transactions are not covered by the guarantee.
  • dataDurability: required stops writes when too few standbys are available. preferred falls back to asynchronous replication and restores synchronous replication when standbys return. The provider does not alert on that fallback; watch the replication metrics.

Logical replication slot failover

Logical replication slots (used by subscriptions and change data capture tools) live on the primary. Without synchronization, a failover promotes a standby that has no slots, and consumers lose their position. Set CloudNativePG's replicationSlots configuration to keep them on the standbys (the UI exposes it as the Logical replication slot failover toggle under Resources):

spec:
  components:
    engine:
      replicas: 2
      parameters:
        replicationSlots:
          highAvailability:
            synchronizeLogicalDecoding: true
  • Requires PostgreSQL 17 or later, which synchronizes slots natively. The provider turns on hot_standby_feedback and sync_replication_slots unless they are set in postgresql.parameters, and rejects them set to off.
  • On PostgreSQL 14–16, use the pg_failover_slots extension from the standard images instead: set a pg_failover_slots.* parameter (for example pg_failover_slots.synchronize_slot_names) in postgresql.parameters and the operator preloads it. The provider then leaves the other settings to you.
  • Only slots created with failover enabled are synchronized: CREATE SUBSCRIPTION ... WITH (failover = true), or the failover argument of pg_create_logical_replication_slot(). A slot is ready for failover once pg_replication_slots on the standby shows it synced and not temporary. A new slot stays temporary there until its consumer has advanced on the primary; temporary slots are dropped when the standby is promoted.
  • HA replication slots (highAvailability.enabled, on by default) must stay on. highAvailability.slotPrefix cannot change while they are enabled; the provider rejects such a change, including removing a custom prefix.
  • On PostgreSQL 17+, CloudNativePG also manages synchronized_standby_slots: logical consumers only receive changes the standbys have already flushed, so a consumer never gets ahead of what survives a failover. While no standby is streaming, logical replication waits.
  • A slot whose consumer stops keeps WAL on the primary until the volume fills. Bound it with postgresql.parameters.max_slot_wal_keep_size, and drop slots you no longer use.

The rest of replicationSlots is passed through as well, for example synchronizeReplicas.excludePatterns to keep user-defined physical slots off the standbys.

Require TLS

CloudNativePG always serves TLS, but its default pg_hba.conf also accepts unencrypted connections. Set requireTLS: true to refuse them:

spec:
  components:
    engine:
      parameters:
        requireTLS: true

The provider places hostnossl all all all reject before any rules in postgresql.pg_hba. CloudNativePG applies it with a configuration reload, so instances are not restarted. Replication and local connections are unaffected: CloudNativePG's own rules for them come first and use TLS or the local socket. With the proxy component, the provider also sets PgBouncer's client_tls_sslmode to require, so the pooler refuses unencrypted clients as well.

Clients must connect with TLS. libpq's default sslmode=prefer does; sslmode=disable is refused. Use sslmode=verify-full with the cluster CA to also authenticate the server. The CA certificate is the ca.crt key in the <cluster>-ca Secret, or in the Secret named by certificates.serverCASecret when you bring your own. The connection Secret's uri uses sslmode=require; see Connection details for how node-postgres treats that value.

The UI enables this by default for new instances. Unset means off, so existing instances keep accepting unencrypted clients until you turn it on. When editing an instance, the UI shows the value in its spec, off when unset, so saving the section doesn't turn it on.

Client access rules (pg_hba)

pgHBA declares which clients may connect to which databases as which users, as pg_hba.conf records, one per line (the UI has it under Advanced configuration). Who may do what inside a database is granted with roles, for example by the user-management plugin.

spec:
  components:
    engine:
      parameters:
        pgHBA: |
          # orders: only the orders service, only from the application network
          hostssl orders orders_app 10.42.0.0/16 scram-sha-256
          host    orders all        all          reject
  • Records are checked in order, first match wins. CloudNativePG's own rules come first (local connections, and certificate authentication for replication and the pooler), so pgHBA can't lock the operator out. Its default rule, host all all all scram-sha-256, comes last: anything no record matches is still let in with a password. To allow only what is listed, end with a reject record, such as host all all all reject.
  • With requireTLS, hostnossl all all all reject goes before the records, so a host record can't admit unencrypted clients.
  • Allowed: host, hostssl and hostnossl records; an address that is all, samehost, samenet, a CIDR range, an IP address and netmask, or a host name; the methods scram-sha-256, md5, cert (hostssl only), ldap, radius and reject, with NAME=VALUE options. The provider refuses the Instance otherwise: trust and password (cleartext), local records, include directives and @file references are not allowed.
  • CloudNativePG applies changes with a configuration reload, without a restart.
  • Connections through the proxy component reach PostgreSQL from the PgBouncer pods, so address ranges must include them.
  • Components that connect over the network, such as the user-management plugin (as the superuser and as database owners), are subject to the records too: don't reject them.
  • pgHBA replaces postgresql.pg_hba, the raw CloudNativePG passthrough; setting both is refused.

Development

Requires Go (see go.mod), Docker, Helm, kubectl, and a Kubernetes cluster you can reach. dev/README.md covers the environment end to end: the recommended local k3d setup, running against a cluster you already have, and every dev/.env setting.

make dev-up             # local cluster + Tilt dev environment (see dev/README.md)
make generate           # RBAC, provider spec, Helm chart sync
make run                # run the provider locally against the cluster (without the admission webhook)
make test               # unit tests
make test-integration   # chainsaw suites under test/integration/
make test-integration-backup # backup integration suite against S3Mock
make dev-down

To work against a cluster you already have — kind, GKE, a shared OpenEverest Tilt cluster — skip make dev-up and point Tilt at it:

cp dev/.env.example dev/.env   # set K8S_CONTEXT, and DOCKER_REGISTRY_URL for a remote registry
tilt up -f dev/Tiltfile

make help lists every target. make verify fails when generated files are stale — run make generate and commit the result.

The provider contract (Validate / Sync / Status / Cleanup), RBAC markers, watches, code generation, and the backup/restore interfaces are documented once for all providers in PROVIDER_DEVELOPMENT.md.

Layout

Path Purpose
cmd/provider/ Entry point
internal/provider/ ProviderInterface implementation, backup mirror, RBAC markers
internal/cnpg/ CloudNativePG helpers — TimescaleDB, roles; barman/ for backup, restore, and schedules
internal/common/ Component name constants
definition/ Provider identity, component types, versions, topologies, backup classes
charts/provider-cloudnative-pg/ Helm chart (generated/ is produced by make generate)
config/rbac/role.yaml Generated ClusterRole — do not edit
test/integration/ Chainsaw suites: core/admission, core/replicaset, backup, extensions/bundled, extensions/imagevolume, extensions/pg-stat-statements, extensions/pgcron-pgrepack, tls-only, wal-storage
test/e2e-cluster/ Chainsaw e2e suites on the full OpenEverest platform: backup-restore, backup-deletion
test/testdata/ Fixtures shared by the suites (S3Mock object store)
test/e2e/ Playwright UI tests against the OpenEverest UI
test/vars.sh Pinned versions used by tests
examples/ Example Instance resources
dev/ Tilt dev environment, .env configuration, k3d cluster config
.github/workflows/ CI: lint, build, unit and integration tests, release

Testing

  • Unit tests — make test.
  • Integration tests — chainsaw suites under test/integration/. Individual suites are also exposed as make targets (make test-integration-core, make test-integration-backup, make test-integration-core-replicaset, make test-integration-extensions, …). The extension suites run a one-instance PostgreSQL and use each extension through psql; extensions/pgcron-pgrepack runs two instances to check that pg_cron jobs resume after a switchover. extensions/imagevolume and extensions/pgcron-pgrepack need Kubernetes ImageVolume (1.35+ with containerd 2.1+); the dev and CI k3d cluster (dev/k3d_config.yaml) runs k3s 1.36, so make test-integration covers them (alone: make test-integration-imagevolume). core/admission (make test-integration-core-admission) checks the admission webhook and scales the provider down, so it runs alone. wal-storage (make test-integration-wal, needs jq) grows the WAL volume. On a StorageClass without expansion, such as k3d's local-path, it uses an expandable copy and checks that the resize request reaches the WAL PVC; the physical resize is checked only where the default StorageClass expands volumes (e.g. a CSI driver with a resizer).
  • E2E cluster tests — chainsaw suites under test/e2e-cluster/ that run user journeys on the full platform: the released OpenEverest core (server, controller and CRDs, at the version pinned in go.mod) installed by make install-openeverest, plus this provider. backup-restore writes data, takes a Backup, restores it into a new Instance through spec.dataSource, and checks the data. backup-deletion checks that schedule retention reaches the Barman ObjectStore, that deleting a Retain Backup keeps its objects in the object store, and that deleting a Delete Backup removes them. Run with make test-e2e-cluster.
  • E2E UI tests — Playwright tests under test/e2e/ drive the OpenEverest UI: they create a PostgreSQL instance through the provider's generated form, wait for it to be Ready, and delete it; a second test turns on Separate WAL storage and checks the WAL volume. Run with make test-e2e (installs Chromium for Playwright) against a UI at EVEREST_URL (default http://localhost:8080, e.g. kubectl -n everest-system port-forward svc/everest 8080:8080); the test namespace defaults to e2e-ui (E2E_NAMESPACE) and must exist. Set E2E_SKIP_KUBECTL=true if the test host cannot reach the cluster API: the CNPG Cluster checks are then reported as skipped, and an instance left by a failed test is not deleted.
  • CI — .github/workflows/build.yaml runs lint, build, unit tests, generated-file verification, and Helm lint; .github/workflows/test.yaml runs the integration suites; .github/workflows/e2e-cluster.yaml runs the e2e cluster suites on every pull request; .github/workflows/e2e.yaml runs the UI tests nightly, on demand, and on pull requests labelled test/e2e.

Troubleshooting

kubectl logs -n everest-system deploy/provider-cloudnative-pg -f
Symptom Where to look
Instance stuck in Creating kubectl describe instance <name> conditions, then the provider logs
No Provider resource in the cluster Is the chart installed? Check the provider deployment logs
Instance ignored entirely spec.providerRef.name must be provider-cloudnative-pg
Cluster created but not reconciled Confirm CloudNativePG is running; for Barman, confirm cert-manager is installed
Cluster created but no pods Inspect the CloudNativePG Cluster status — the failure is upstream in the operator
BackupConfigured=False / reason BarmanPluginMissing Install cert-manager, then install/upgrade with plugin-barman-cloud.enabled=true (the chart default)
Backup / restore stuck Check Barman plugin pods, ObjectStore / Backup CRs, and BackupStorage credentials

Contributing

Issues and pull requests are welcome. See PROVIDER_DEVELOPMENT.md and the OpenEverest Code of Conduct.

Security

Report vulnerabilities per the OpenEverest security policy. Please do not open public issues for security reports.

License

Apache License 2.0 — see LICENSE for details.

About

OpenEverest provider that provisions PostgreSQL HA clusters on Kubernetes via CloudNativePG.

Topics

Resources

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages