Architecture

This document provides a high-level overview of Percona Operator for PostgreSQL architecture, explaining how the various components connect to create a production-ready PostgreSQL cluster on Kubernetes. See also How the Operator works.

Components

The Operator components are the following:

• Percona Distribution for PostgreSQL - a suite of open source software, tools and services required to deploy and maintain a reliable production cluster for PostgreSQL. It includes the set of extensions such as pgAudit for audit logging, pg_stat_monitor for query performance statistics and additional supplied modules and extensions . It also comes with LLVM library for JIT compilation.

• Patroni - a high-availability solution for PostgreSQL that automates replication and failover. It maintains the cluster state and coordinates leader election to ensure that a healthy primary node is always available. Patroni simplifies building and operating resilient PostgreSQL clusters by handling node monitoring, failover, and recovery automatically.

• pgBouncer is a lightweight connection pooler in front of PostgreSQL. It sits between client applications and the database server to manage and reuse connections efficiently. Instead of each client opening its own database connection, pgBouncer maintains a pool of connections and serves them to clients on demand, significantly reducing connection overhead and improving performance, especially for applications with many short-lived or concurrent connections.

• pgBackRest is a backup and restore tool. It handles full, incremental, and differential backups, compression and encryption, parallel processing, and point-in-time recovery using WAL archives.

• PMM Client for observability – The PMM Client is an optional, yet valuable, component that you can enable to gain deeper insights into your database performance. When monitoring is configured, the PMM Client is deployed as a sidecar container alongside PostgreSQL Pods, empowering you with detailed monitoring and management capabilities.

How components work together

This workflow shows how cluster components work together:

1. Your application connects through a Kubernetes Service that routes the traffic to pgBouncer.
2. pgBouncer accepts many client connections and forwards them through a smaller set of server connections to PostgreSQL Pods.
3. PostgreSQL executes queries. Writes go to the primary. Reads can target the primary or replicas.
4. Primary streams WAL to replicas via instance Services
5. Patroni monitors the cluster state and coordinates the leader elections if the primary node fails
6. pgBackRest makes backups according the schedule that you defined or when you manually create a backup object. pgBackRest saves backups to the backup storage your configured. To learn more about backups, their workflow and setup, refer to the About backups
7. PMM Client collects performance metrics and sends them to the PMM Server for you to see and analyze. See Monitor the database with PMM to learn more.

Default cluster configuration

The default Percona Distribution for PostgreSQL configuration includes:

• 3 PostgreSQL servers, one primary and two replicas.
• 3 pgBouncer instances.
• a pgBackRest repository host instance – a dedicated instance in your cluster that stores filesystem backups made with pgBackRest.
• (optional) a PMM client instance - a monitoring and management tool for PostgreSQL that provides a way to monitor your database health and performance. PMM Client is disabled by default and runs as a sidecar container in the database Pods when you configure monitoring

Primary, replicas, and high availability

Each PostgreSQL cluster has one primary instance that accepts read/write transactions. Replicas are standbys: they replicate from the primary and typically serve read-only traffic (depending on how you expose them).

The Operator provides high availability through multiple layers of protection:

Pod distribution

The Operator uses node affinity and anti-affinity to distribute PostgreSQL instances across separate worker nodes when possible. This prevents a single node failure from taking down multiple database instances.

Automatic recovery

If a node fails, Kubernetes automatically reschedules the affected Pod on another healthy node. Patroni handles which PostgreSQL instance is primary and ensures replication continuity. For more on HA behavior and operations, see High-availability.

Storage and persistent volumes

Stateful applications require their data to persist even if Pods are restarted or rescheduled. In Kubernetes, this is achieved through PersistentVolumeClaims (PVCs), which request storage resources. The cluster’s CSI driver provisions PersistentVolumes, and can reattach storage if a Pod moves to another node, thereby ensuring data continuity.

If a node fails, the expectation is that the volume can be mounted elsewhere and the Pod recreated, while Patroni and PostgreSQL recover the database layer. For storage troubleshooting, see Check storage.

Next steps

For a comparison of Percona’s approach with other deployment models, see Comparison with other solutions.

---

Last update: May 21, 2026
Created: July 12, 2022