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.
Run PostgreSQL on Kubernetes through OpenEverest, backed by CloudNativePG.
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
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.
| 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 |
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 |
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.
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 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_tableStateful 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 |
CNPG retention uses the Barman Cloud Plugin's native recovery window:
retention:
type: time
duration: 30dAll 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.
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: truewalStorage 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.
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.enabledandplugin-barman-cloud.enabledboth default totrue). Set either tofalseto use an externally managed install instead. - The chart registers an admission webhook, so an invalid
Instanceis rejected when it is written, bykubectl, 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; setadmission.certManager.enabled=trueto have cert-manager issue it, or supply one throughadmission.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-systemUninstalling the chart does not delete running Instance resources or their data.
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 whenreplicaCountis 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.
Verify that the provider registered itself:
kubectl get providers.core.openeverest.io provider-cloudnative-pgCreate 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: 5GiComponent 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.
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.
hostis<cluster>-rw.<namespace>.svc, the read-write Service. With theproxycomponent set,host,port, anduripoint at the pooler Service instead.host-randhost-rostay on the PostgreSQL Services.host-ris<cluster>-r.<namespace>.svc. That Service targets every ready instance, including the primary. It is omitted when the read Service is disabled.host-rois<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 andreplicasis at least 2.portis theportkey of the credential Secret. CloudNativePG writes5432there. A user-supplied basic-auth Secret may omit it, and then the port is5432. The PostgreSQL Service port is not configurable. With the pooler enabled,portis 5432 because PgBouncer'slisten_portis fixed.sslmodeisrequire, anduriincludes it. CloudNativePG always serves TLS, so this works whether or notrequireTLSis set. libpq's defaultpreferis 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.
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-stackThe 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.
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| 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.
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: transactionPgBouncer 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).
| 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.
- Chart values: charts/provider-cloudnative-pg/values.yaml
- Instance parameters: per-component and per-topology
parametersschemas, defined under definition/ and published on theProviderresource (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.
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, whichkubectlprints: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(oreverestctl instance create|update --dry-run=server) in CI to get the same errors and warnings without changing anything. - Objects the
Instancerelies on (the extension images in theClusterImageCatalog, the runningCluster) never block a write: at admission their problems are warnings, and theInstancereports them in itsReadycondition. - An update is blocked only by new errors: an
Instancewritten 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; theInstancethen reports the errors asReady=Falsewith reasonValidationFailed.
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 |
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
CHECKPOINTright 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'sspec.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 isFailed; 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 withspec.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.
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: requirednumbermust be lower thanreplicas(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. Setpostgresql.parameters.synchronous_committoremote_applyto also wait until the change is visible on them, orremote_writefor a weaker guarantee. Applications can lowersynchronous_commitper transaction, and those transactions are not covered by the guarantee. dataDurability: requiredstops writes when too few standbys are available.preferredfalls 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 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_feedbackandsync_replication_slotsunless they are set inpostgresql.parameters, and rejects them set tooff. - On PostgreSQL 14–16, use the
pg_failover_slotsextension from the standard images instead: set apg_failover_slots.*parameter (for examplepg_failover_slots.synchronize_slot_names) inpostgresql.parametersand 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 thefailoverargument ofpg_create_logical_replication_slot(). A slot is ready for failover oncepg_replication_slotson the standby shows itsyncedand nottemporary. 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.slotPrefixcannot 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.
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: trueThe 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.
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
pgHBAcan'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 arejectrecord, such ashost all all all reject. - With
requireTLS,hostnossl all all all rejectgoes before the records, so ahostrecord can't admit unencrypted clients. - Allowed:
host,hostsslandhostnosslrecords; an address that isall,samehost,samenet, a CIDR range, an IP address and netmask, or a host name; the methodsscram-sha-256,md5,cert(hostsslonly),ldap,radiusandreject, withNAME=VALUEoptions. The provider refuses the Instance otherwise:trustandpassword(cleartext),localrecords,includedirectives and@filereferences are not allowed. - CloudNativePG applies changes with a configuration reload, without a restart.
- Connections through the
proxycomponent 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.
pgHBAreplacespostgresql.pg_hba, the raw CloudNativePG passthrough; setting both is refused.
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-downTo 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/Tiltfilemake 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.
| 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 |
- 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 throughpsql;extensions/pgcron-pgrepackruns two instances to check that pg_cron jobs resume after a switchover.extensions/imagevolumeandextensions/pgcron-pgrepackneed Kubernetes ImageVolume (1.35+ with containerd 2.1+); the dev and CI k3d cluster (dev/k3d_config.yaml) runs k3s 1.36, somake test-integrationcovers 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, needsjq) grows the WAL volume. On a StorageClass without expansion, such as k3d'slocal-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 bymake install-openeverest, plus this provider.backup-restorewrites data, takes a Backup, restores it into a new Instance throughspec.dataSource, and checks the data.backup-deletionchecks that schedule retention reaches the Barman ObjectStore, that deleting aRetainBackup keeps its objects in the object store, and that deleting aDeleteBackup removes them. Run withmake 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 atEVEREST_URL(defaulthttp://localhost:8080, e.g.kubectl -n everest-system port-forward svc/everest 8080:8080); the test namespace defaults toe2e-ui(E2E_NAMESPACE) and must exist. SetE2E_SKIP_KUBECTL=trueif 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.
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 |
Issues and pull requests are welcome. See PROVIDER_DEVELOPMENT.md and the OpenEverest Code of Conduct.
Report vulnerabilities per the OpenEverest security policy. Please do not open public issues for security reports.
Apache License 2.0 — see LICENSE for details.