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 Percona Distribution for PostgreSQL on Kubernetes through OpenEverest, backed by the Percona Operator for PostgreSQL.
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: 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-percona-postgresql<br/>(this repository)"]
P -->|reconciles into| O["PerconaPGCluster<br/>pgv2.percona.com/v2"]
O --> W["Percona Operator for PostgreSQL"]
W --> R[("Workloads, Services,<br/>Secrets, PVCs")]
P -->|status, endpoints,<br/>credentials| I
The provider watches Instance resources whose spec.providerRef.name is
provider-percona-postgresql, and reports workload health back onto Instance.status. It
never manages pods directly — all lifecycle work is delegated to the operator.
| provider-percona-postgresql | OpenEverest | Percona Operator for PostgreSQL | Kubernetes |
|---|---|---|---|
0.6.x |
2.0.0-dev.4 |
3.0.x |
1.30 – 1.34 |
0.5.x |
2.0.0-dev.4 |
3.0.x |
1.30 – 1.34 |
0.4.x |
2.0.0-dev.4 |
3.0.x |
1.30 – 1.34 |
0.3.x |
2.0.0-dev.3 |
3.0.x |
1.30 – 1.34 |
0.2.x |
2.0.0-dev.3 |
3.0.x |
1.30 – 1.34 |
0.1.x |
2.0.0-dev.2 |
3.0.x |
1.30 – 1.34 |
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.<name>.replicas |
| Vertical scaling (CPU / memory) | ✅ | spec.components.<name>.resources |
| Version upgrades | ✅ | of the deployed PostgreSQL version — change spec.version; see Versions |
| Custom configuration | ✅ | spec.components.engine.parameters.configuration — see Custom PostgreSQL configuration |
| Exposure | ✅ | spec.components.proxy.service.serviceType: ClusterIP (default), LoadBalancer or NodePort; applies to pgBouncer, so it needs proxy.replicas ≥ 1 |
| Monitoring | ✅ | PMM 3, via a spec.monitoring.destinations entry naming a MonitoringDestination of a pmm class |
| TLS | ✅ | on by default; generated, or your own certificates — see TLS |
| Client access rules (pg_hba) | ✅ | spec.components.engine.parameters.pgHBA — which clients may connect to which databases as which users; see Client access rules |
Stateful workloads additionally report:
| Capability | Status | Notes |
|---|---|---|
| Persistent storage | ✅ | spec.components.engine.storage |
| Storage expansion | ✅ | when the StorageClass allows volume expansion |
| Backups (on demand) | ✅ | via the Backup API |
| Backups (scheduled) | ✅ | via spec.backup.schedules on the Instance |
| Point-in-time recovery | ✅ | via the Restore API (dataSource.pointInTime) |
| Restore | ✅ | via the Restore API (dataSource.backup or dataSource.pointInTime) |
The provider chart is published as an OCI artifact to GitHub Container Registry:
helm install provider-percona-postgresql \
oci://ghcr.io/openeverest/charts/provider-percona-postgresql \
--version 0.6.0 \
--namespace everest-system- The Percona Operator for PostgreSQL is bundled as a chart dependency and installed by
default. Set
pg-operator.enabled=falsewhen the cluster already runs it. - The chart registers an admission webhook, so an invalid
Instanceis rejected when it is written, with every error and its field path. 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. If the provider is down, writes are admitted and theInstancereports the errors in itsReadycondition. A missing object theInstancenames, such as its user Secret, is never a reason to reject it:kubectlprints a warning, and theInstancereports it once created.
To install from a checkout instead, make helm-install builds the chart dependencies
and installs it against your current kube context.
Upgrade and uninstall:
helm upgrade provider-percona-postgresql \
oci://ghcr.io/openeverest/charts/provider-percona-postgresql --version 0.6.0
helm uninstall provider-percona-postgresql --namespace everest-systemUninstalling the chart does not delete running Instance resources or their data.
Verify that the provider registered itself:
kubectl get providers.core.openeverest.io provider-percona-postgresqlCreate an instance:
apiVersion: core.openeverest.io/v1alpha1
kind: Instance
metadata:
name: my-instance
spec:
providerRef:
name: provider-percona-postgresql
components:
engine:
type: postgresql
replicas: 3
resources:
requests:
cpu: 500m
memory: 2G
storage:
size: 10Gi
proxy:
type: pgbouncer
replicas: 2Component names are defined by this provider — see definition/provider.yaml.
proxy is required in the cluster topology and its replicas must be set explicitly; use
replicas: 0 to run without pgBouncer.
spec.version and spec.topology are optional; the provider defaults apply.
More examples live in examples/.
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}'Connection details are in the Secret named by .status.connectionSecretRef.name. It has the keys host, port, username, password and uri.
| Topology | Default | Description |
|---|---|---|
cluster |
✅ | Primary plus replicas (2 engine instances by default), fronted by 2 pgBouncer proxy replicas |
| Version bundle | Default | postgresql | pgbouncer |
|---|---|---|---|
18.4-1 |
✅ | 18.4-1 |
1.25.2-1 |
18.3-1 |
18.3-1 |
1.25.2-1 |
|
18.1-3 |
18.1-3 |
1.25.2-1 |
|
17.10-1 |
17.10-1 |
1.25.2-1 |
|
17.9-1 |
17.9-1 |
1.25.2-1 |
|
17.7-2 |
17.7-2 |
1.25.2-1 |
|
16.14-1 |
16.14-1 |
1.25.2-1 |
|
16.13-1 |
16.13-1 |
1.25.2-1 |
|
16.11-2 |
16.11-2 |
1.25.2-1 |
|
15.18-1 |
15.18-1 |
1.25.2-1 |
|
15.17-1 |
15.17-1 |
1.25.2-1 |
|
15.15-2 |
15.15-2 |
1.25.2-1 |
|
14.23-1 |
14.23-1 |
1.25.2-1 |
|
14.22-1 |
14.22-1 |
1.25.2-1 |
|
14.20-2 |
14.20-2 |
1.25.2-1 |
Source of truth: definition/versions.yaml.
PostgreSQL major-version upgrades require a dump/restore or the operator's upgrade job — they
are not a simple spec.version bump. Minor upgrades within a major version are rolling.
- Chart values: charts/provider-percona-postgresql/values.yaml
- Instance parameters: per-component and per-topology
parametersschemas, defined under definition/ and published on theProviderresource (kubectl get provider provider-percona-postgresql -o yaml). The provider rejects an Instance that does not match them, and the UI checks the form against them as you type.
This provider currently exposes one technology-specific parameter beyond the shared
component fields (replicas, resources, storage): engine.parameters.configuration,
covered in Custom PostgreSQL configuration.
When the instance sends to a PMM destination, its PostgreSQL metrics in PMM carry namespace
and core_openeverest_io_instance labels, so they can be queried per instance. The
destination's and the entry's parameters are decoded with the pmm contract module
(github.com/openeverest/monitoring-pmm/api): a parameter it does not know, or a url with a
path, fails rendering (the binding reports Configured RenderFailed) instead of being ignored.
TLS is on by default. Configure it with the instance-wide tls parameter:
spec:
parameters:
tls:
mode: requireTLS # preferTLS (default) | requireTLS
# Bring your own certificates, or leave empty to have the operator issue them:
certificateSecretName: my-tls # tls.crt, tls.key and ca.crt
replicationCertificateSecretName: my-tls-repl # same ca.crt, for members
# Or bring your own CA instead, and let the operator issue certificates
# signed by it (mutually exclusive with certificateSecretName):
# rootCASecretName: my-ca # root.crt and root.key-
preferTLS(default) lets clients connect to PostgreSQL directly with or without TLS. pgBouncer always requires TLS from clients regardless of mode, so most deployments — which go through pgBouncer — are unaffected by this setting.requireTLSrejects any non-TLS connection, direct or through pgBouncer. -
Certificates are, in order of precedence:
- your secrets:
certificateSecretNameandreplicationCertificateSecretName, which must share the sameca.crt. Their subject alternative names must cover the instance's service and pod names. The operator never replaces these secrets with its own; - a CA you provide (
rootCASecretName): the operator issues certificates signed by it; - otherwise the operator issues them: through cert-manager when it is installed, or else from a CA it generates once.
The certificate source can't be changed after creation, as a new CA would stop existing clients and members from trusting the instance.
- your secrets:
-
Clients need only the CA to verify the instance: the connection secret (
.status.connectionSecretRef.name) carries it asca.crt, and itsurisetssslmodeto match the mode and how clients reach the instance.
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. The operator's own records
come first (local superuser, certificate-authenticated replication,
pgBouncer's and monitoring's users), so
pgHBAcan't lock the operator out. The default record,hostssl all all all scram-sha-256, comes last: anything no record matches is still let in over TLS with a password. To allow only what is listed, end with arejectrecord, such ashost all all all reject. - With
tls.mode: 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. The operator mirrorsldaprecords to pgBouncer. - The records go to the operator's
spec.authentication.rules; Patroni applies changes with a configuration reload, without a restart. - Connections through pgBouncer 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.
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
make test-unit
make test-integration # chainsaw suites
make test-e2e-cluster # chainsaw suites that need a running PG operator (test/e2e-cluster)
make dev-downmake 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, RBAC markers |
internal/common/ |
Component name constants |
definition/ |
Provider identity, component types, versions, topologies |
charts/provider-percona-postgresql/ |
Helm chart (generated/ is produced by make generate) |
config/rbac/role.yaml |
Generated ClusterRole — do not edit |
examples/ |
Example Instance resources |
dev/ |
Tilt dev environment, .env configuration, k3d cluster config |
.github/workflows/ |
CI: lint, build, unit, integration and e2e-cluster tests, release |
- Unit tests —
make test-unit. - Integration tests —
make test-integrationruns the chainsaw suites. - E2E cluster tests —
make test-e2e-clusterruns chainsaw suites that need a running PG operator (test/e2e-cluster). - CI — .github/workflows/ci.yaml runs lint, build, unit tests, generated-file verification, Helm lint, integration suites, and the e2e-cluster backup datasource suite on every pull request.
kubectl logs -n everest-system deploy/provider-percona-postgresql -f| Symptom | Where to look |
|---|---|
Instance stuck in Creating |
kubectl describe instance <name> conditions, then the provider logs |
Instance in Phase: Failed |
kubectl describe instance <name> Events (look for ValidationFailed), 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-percona-postgresql |
PerconaPGCluster created but no pods |
Inspect the PerconaPGCluster status — the failure is upstream in the operator |
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.