StackGres 1.6: A Private‑Deployable Cloud‑Native PostgreSQL Platform

StackGres Overview

StackGres is a full‑stack PostgreSQL distribution for Kubernetes packaged as a single deployment unit. It bundles PostgreSQL with a curated set of open‑source components to provide an enterprise‑grade stack.

Operator

The StackGres Operator packages, deploys, and manages the StackGres stack using custom resources. It reconciles the desired state defined in YAML with the actual state of the cluster.

Kubernetes operator is a method for packaging, deploying, and managing Kubernetes‑based applications; database workloads need extra knowledge to maintain state and integrate components.

Stack components

PostgreSQL – core relational database (https://www.postgresql.org/)

Patroni – HA solution based on Kubernetes distributed consensus (https://github.com/zalando/patroni)

WAL‑G – archive and restore tool (https://github.com/wal-g/wal-g)

PgBouncer – lightweight connection pool (http://www.pgbouncer.org/)

PostgreSQL Server Exporter – Prometheus metrics exporter (https://github.com/wrouesnel/postgres_exporter)

Envoy – cloud‑native edge and service proxy (https://www.envoyproxy.io/)

Key concepts

Production‑grade database management

StackGres supports declarative management of common and uncommon database operations while minimizing application and user disruption, acting as a DBA‑style controller via the Kubernetes API.

Kubernetes‑centric design

All functionality is tightly integrated with Kubernetes; users define the desired state in YAML custom resources and the operator reconciles the actual state.

Single point of access – multiple methods

PostgreSQL clusters can be accessed via kubectl, a REST API, or the web UI. All methods see a consistent state, allowing different users to perform the same operations using their preferred interface.

Sidecar architecture

Sidecar containers run alongside the primary PostgreSQL container to provide connection pooling, metrics export, edge proxy, logging, and utility functions. All sidecar images are built on RedHat UBI 8.

Cluster definition

A StackGres cluster is defined by the custom resource SGCluster and is implemented as a StatefulSet, ensuring each pod has a dedicated persistent volume.

Architecture diagrams

UDS: Unix Domain Socket

Stack component details

Core container

The primary container uses a minimal UBI 8 image with PostgreSQL installed and attaches persistent storage via a StorageClass. Sidecar containers are co‑deployed to provide auxiliary functions.

Configuration

StackGres ships with tuned defaults that improve performance over PostgreSQL’s conservative defaults. Users can override any parameter. Reference documentation includes the official PostgreSQL docs and community guides.

Connection pooling

Direct connections spawn a process per client; when max_connections (default 100) is reached, additional connections are rejected, leading to CPU contention and scheduling overhead. A benchmark image (not shown) illustrates latency rising sharply as connections increase.

Three common PostgreSQL connection‑pool solutions are listed:

PgPool (https://www.pgpool.net)

PgBouncer (https://www.pgbouncer.org)

Odyssey (https://github.com/yandex/odyssey)

StackGres selects PgBouncer because it is simple and stable. Its limitation is single‑threaded operation, which can cause CPU saturation under very high connection counts; Odyssey is noted as a potential future replacement.

High availability

Failover requires promoting a healthy replica to primary without manual intervention. StackGres evaluates several HA projects (PgPool, Repmgr, Patroni, pg_autofailover, PAF, Stolon) and chooses Patroni because it uses a distributed consensus algorithm that integrates directly with Kubernetes, avoiding external services.

Backup and disaster recovery

Multiple backup tools exist (Barman, pgBackRest, Wal‑e/Wal‑g, pg_probackup). StackGres defaults to Wal‑g, which supports incremental and full backups, can store data on ReadWriteMany volumes or cloud storage (AWS S3, GCS, Azure Blob), and allows bandwidth or disk‑usage configuration.

Logging

Logs from all containers are centralized for analysis. Options mentioned include Fluentd, Loki, and TimescaleDB, though a custom solution is required for full PostgreSQL integration.

Proxy

Envoy serves as an edge and service proxy, capable of exposing PostgreSQL metrics in Prometheus format and handling TLS termination. Documentation links include the Envoy proxy filter for PostgreSQL.

Monitoring

StackGres officially supports Prometheus with the PostgreSQL Server Exporter (https://github.com/wrouesnel/postgres_exporter). The Prometheus Operator can be deployed alongside StackGres via Helm (https://github.com/prometheus-operator/prometheus-operator). Prometheus is an external dependency; StackGres can optionally install it as part of its Helm chart.

Grafana integration

Two integration paths are provided:

Automatic integration using the Prometheus Operator Helm chart (https://stackgres.io/doc/latest/install/prerequisites/#integrating-pre-existing-grafanas)

Manual integration requiring additional steps (https://stackgres.io/doc/latest/install/prerequisites/#manual-integration)

Web UI and CLI

StackGres offers a web and CLI UI for cluster management, enabling listing, creating, updating, deleting clusters, as well as performing failover and backup/restore operations.