PostgreSQL Kubernetes Operator

A Kubernetes operator for managing PostgreSQL clusters with high availability using Patroni.

Features

• High Availability: Automatic failover using Patroni with Kubernetes-native leader election
• Declarative Configuration: Manage PostgreSQL clusters using Kubernetes custom resources
• Automatic Scaling: Scale replicas up or down with automatic replication setup
• In-Place Resource Resizing: CPU/memory changes without pod restarts (Kubernetes 1.35+)
• Connection Pooling: Optional PgBouncer sidecar for connection pooling
• TLS by Default: Encrypted connections with automatic cert-manager integration
• Cloud Backups: Continuous WAL archiving and scheduled base backups to S3 or S3-compatible storage with point-in-time recovery (PITR)
• Major Version Upgrades: Near-zero downtime upgrades using blue-green deployment with logical replication
• Metrics: Prometheus-compatible metrics endpoint
• Zero-Downtime Updates: Rolling updates with PodDisruptionBudgets

Prerequisites

• Kubernetes 1.35+
• kubectl configured to access your cluster
• cert-manager v1.0+ (required for TLS certificate management)

Installation

Install the Operator

# Install CRD and RBAC
make install

# Deploy the operator
make deploy

Create a PostgreSQL Cluster

apiVersion: postgres-operator.smoketurner.com/v1alpha1
kind: PostgresCluster
metadata:
  name: my-postgres
spec:
  version: "16"
  replicas: 3
  storage:
    size: 10Gi
    storageClass: standard
  tls:
    issuerRef:
      name: selfsigned-issuer
      kind: ClusterIssuer

kubectl apply -f my-postgres.yaml

Check Status

kubectl get postgresclusters
kubectl describe pgc my-postgres

Connect to PostgreSQL

# Primary (read-write)
kubectl run psql --rm -it --image=postgres:16 -- \
  psql -h my-postgres-primary -U postgres

# Get credentials
kubectl get secret my-postgres-credentials -o jsonpath='{.data.password}' | base64 -d

Uninstallation

# Remove the operator
make undeploy

# Remove CRD and RBAC
make uninstall

Documentation

For detailed documentation, see the docs/ directory:

• API Reference - Complete CRD field reference
• Architecture - Design decisions, state machine, HA patterns
• Backup & Restore - Cloud backup configuration, PITR, restore procedures
• Development - Building, testing, contributing
• Operations - Day-2 operations, scaling, troubleshooting, maintenance
• Upgrades - Major version upgrades using blue-green deployment

Sample configurations are available in config/samples/.

Support

This project is maintained on a best-effort basis. For questions, bug reports, or feature requests, please open an issue on GitHub.

License

MIT License - see LICENSE.md