CloudNativePG · Architecture
The operator chart runs in cnpg-system, while managed clusters run in application namespaces. Most clusters here have two instances on separate workers and separate OpenEBS LocalPV volumes. PostgreSQL replication supplies redundancy; OpenEBS does not replicate those volumes.
Component boundaries
- Declare
- Application Cluster resource
- Owner Secret / storage settings
- Manage
- CNPG operator
- Primary selection / repair
- Database
- Primary + standby / rw Service
- Separate local PVs / app backups
State and recovery contract
Database data and backups belong to each managed cluster. The operator chart is reconstructable from Git. Preserve database credentials, backup credentials, WAL/base backups where configured, and the sealing key.
Availability and failure behavior
Availability classification: Redundant operator management with leader election; managed database availability remains service-specific.
This is an interpretation of the checked-in configuration, assuming the declared replicas are healthy, separated as intended, and their required dependencies are reachable. It is not a live-health result or a completed failure drill.
What supplies redundancy
| Component | Declared layout | Mechanism |
|---|---|---|
| Operator | 2 replicas; required hostname anti-affinity; quorum toleration | The pinned chart enables leader election; a surviving replica can acquire leadership. A one-available PDB protects voluntary eviction. |
| Managed databases | Usually 2 instances per application | PostgreSQL primary/standby replication runs in each application namespace. |
| Client routing | Per-cluster read/write Service | Must be directed to the correct elected/promoted writer. |
| Storage | Separate LocalPV volumes | The operator does not make one local volume portable or replicated. |
How a failure is handled
If only the operator is lost, an existing primary and its standby can continue their PostgreSQL work. If a database primary is also lost, automatic promotion requires the relevant controller/API path to function. A database standby is useful but is not an independently complete failover controller.
Failure scenarios
| Failure | Expected behavior and remaining dependency |
|---|---|
| One main worker | Database serving depends on whether the lost worker held the primary and/or operator. If the operator leader and primary are lost together, the surviving operator must acquire leadership and promote the surviving database instance. Replacement operators remain on the general workers; the surviving elected operator handles promotion. |
| RTX worker only | No operator-specific vote is declared. Whole-host API loss is especially significant because cluster observation and Service updates depend on it. |
| A second failure before recovery | Outside the stated single-failure envelope; assess remaining data copies, quorum, endpoints, and capacity before further maintenance. |
An RTX worker VM failure is not the same as an RTX Proxmox host failure. The latter also removes its control-plane VM and the configured API address. Read the physical failure-domain explanation before making a whole-host HA claim.
Upgrades and voluntary maintenance
Operator restarts and CRD upgrades can pause management while databases keep serving. Perform application database upgrades according to each cluster’s policy, not by treating the operator rollout as the database rollout.
What prevents a stronger HA claim
Operator leader takeover and promotion require a reachable Kubernetes API and sufficient eligible scheduling capacity. Most databases have only one standby; after one member fails there is no second replica to absorb another loss.
What would improve the availability contract
Protect API access and measure primary loss with simultaneous operator leader loss. Keep backup policy per database.
These are operational/design requirements, not changes made to the deployment by this documentation. The shared availability reference explains election, replication, durability, recovery time, and shared dependencies; the manifest links below identify this service’s source.
Configuration ownership
apps/cnpg-operator/ owns this service’s Kubernetes resources. Hostnames, addresses, versions, node names, and volume sizes belong in apps/variables.yaml. Runtime settings stored in a product database need that product’s backup and administration procedure.
Continue
Read the deployment guide for dependency order, initial credentials, and integration work. The official documentation explains the upstream product; the topology above describes this repository.