Skip to content

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Percona Distribution for PostgreSQL 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 Go Reference License

Run Percona Distribution for PostgreSQL on Kubernetes through OpenEverest, backed by the Percona Operator for PostgreSQL.

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: 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
Loading

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.

Compatibility

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

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.<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)

Installation

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=false when the cluster already runs it.
  • The chart registers an admission webhook, so an invalid Instance is rejected when it is written, with every error and its field path. 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. If the provider is down, writes are admitted and the Instance reports the errors in its Ready condition. A missing object the Instance names, such as its user Secret, is never a reason to reject it: kubectl prints a warning, and the Instance reports 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-system

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

Usage

Verify that the provider registered itself:

kubectl get providers.core.openeverest.io provider-percona-postgresql

Create 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: 2

Component 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.

Topologies

Topology Default Description
cluster ✅ Primary plus replicas (2 engine instances by default), fronted by 2 pgBouncer proxy replicas

Versions

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.

Configuration

  • Chart values: charts/provider-percona-postgresql/values.yaml
  • Instance parameters: per-component and per-topology parameters schemas, defined under definition/ and published on the Provider resource (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

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. requireTLS rejects any non-TLS connection, direct or through pgBouncer.

  • Certificates are, in order of precedence:

    1. your secrets: certificateSecretName and replicationCertificateSecretName, which must share the same ca.crt. Their subject alternative names must cover the instance's service and pod names. The operator never replaces these secrets with its own;
    2. a CA you provide (rootCASecretName): the operator issues certificates signed by it;
    3. 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.

  • Clients need only the CA to verify the instance: the connection secret (.status.connectionSecretRef.name) carries it as ca.crt, and its uri sets sslmode to match the mode and how clients reach the instance.

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. The operator's own records come first (local superuser, certificate-authenticated replication, pgBouncer's and monitoring's users), so pgHBA can'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 a reject record, such as host all all all reject.
  • With tls.mode: 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. The operator mirrors ldap records 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.

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
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-down

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, 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

Testing

  • Unit tests — make test-unit.
  • Integration tests — make test-integration runs the chainsaw suites.
  • E2E cluster tests — make test-e2e-cluster runs 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.

Troubleshooting

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

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

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages