- Go 97.7%
- Shell 1.9%
- Makefile 0.3%
| .devcontainer | ||
| .github | ||
| api/v1 | ||
| cmd | ||
| config | ||
| contribute | ||
| docs | ||
| hack | ||
| internal | ||
| licenses/go-licenses | ||
| pkg | ||
| releases | ||
| tests | ||
| .dockerignore | ||
| .gitignore | ||
| .golangci.yml | ||
| .goreleaser.yml | ||
| .snyk | ||
| .spellcheck.yaml | ||
| .woke.yaml | ||
| .wokeignore | ||
| .wordlist-en-custom.txt | ||
| ADOPTERS.md | ||
| CODE_OF_CONDUCT.md | ||
| CODEOWNERS | ||
| CONTRIBUTING.md | ||
| DEPENDENCIES.md | ||
| docker-bake.hcl | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| GOVERNANCE.md | ||
| LICENSE | ||
| MAINTAINERS.md | ||
| Makefile | ||
| PROJECT | ||
| README.md | ||
| ROADMAP.md | ||
| SECURITY-INSIGHTS.yml | ||
| SECURITY.md | ||
| SUPPORT.md | ||
Welcome to the CloudNativePG Project!
CloudNativePG (CNPG) is an open-source platform designed to seamlessly manage PostgreSQL databases in Kubernetes environments. It covers the entire operational lifecycle—from deployment to ongoing maintenance—through its core component, the CloudNativePG operator.
Table of Contents
Getting Started
The best way to get started is the Quickstart Guide.
Scope
Mission
CloudNativePG aims to increase PostgreSQL adoption within Kubernetes by making it an integral part of the development process and GitOps-driven CI/CD automation.
Core Principles & Features
Designed by PostgreSQL experts for Kubernetes administrators, CloudNativePG follows a Kubernetes-native approach to PostgreSQL primary/standby cluster management. Instead of relying on external high-availability tools (like Patroni, repmgr, or Stolon), it integrates directly with the Kubernetes API to automate database operations that a skilled DBA would perform manually.
Key design decisions include:
- Direct integration with Kubernetes API: The PostgreSQL cluster’s status is
available directly in the
Clusterresource, allowing users to inspect it via the Kubernetes API. - Operator pattern: The operator ensures that the desired PostgreSQL state is reconciled automatically, following Kubernetes best practices.
- Immutable application containers: Updates follow an immutable infrastructure model, as explained in "Why EDB Chose Immutable Application Containers".
How CloudNativePG Works
The operator continuously monitors and updates the PostgreSQL cluster state. Examples of automated actions include:
- Failover management: If the primary instance fails, the operator elects a new primary, updates the cluster status, and orchestrates the transition.
- Scaling read replicas: When the number of desired replicas changes, the operator provisions or removes resources such as persistent volumes, secrets, and config maps while managing streaming replication.
- Service updates: Kubernetes remains the single source of truth, ensuring that PostgreSQL service endpoints are always up to date.
- Rolling updates: When an image is updated, the operator follows a rolling strategy—first updating replica pods before performing a controlled switchover for the primary.
CloudNativePG manages additional Kubernetes resources to enhance PostgreSQL
management, including: Backup, ClusterImageCatalog, Database,
ImageCatalog, Pooler, Publication, ScheduledBackup, and Subscription.
Out of Scope
- Kubernetes only: CloudNativePG is dedicated to vanilla Kubernetes maintained by the Cloud Native Computing Foundation (CNCF).
- PostgreSQL only: CloudNativePG is dedicated to vanilla PostgreSQL maintained by the PostgreSQL Global Development Group (PGDG).
- No support for forks: Features from PostgreSQL forks will only be considered if they can be integrated as extensions or pluggable frameworks.
- Not a general-purpose database operator: CloudNativePG does not support other databases (e.g., MariaDB).
CloudNativePG can be extended via the CNPG-I plugin interface.
Communications
- Github Discussions
- Slack (join the CNCF Slack Workspace).
- Mastodon
- Bluesky
Resources
Adopters
A list of publicly known users of the CloudNativePG operator is in ADOPTERS.md. Help us grow our community and CloudNativePG by adding yourself and your organization to this list!
CloudNativePG at KubeCon
- November 10, 2025, KubeCon North America 2025 in Atlanta: "Project Lightning Talk: CloudNativePG: Running Postgres The Kubernetes Way" - Gabriele Bartolini, EDB
- November 11, 2025, KubeCon North America 2025 in Atlanta: "Modern PostgreSQL Authorization With Keycloak: Cloud Native Identity Meets Database Security" - Yoshiyuki Tabata, Hitachi, Ltd. & Gabriele Bartolini, EDB
- November 13, 2025, KubeCon North America 2025 in Atlanta: "Quorum-Based Consistency for Cluster Changes With CloudNativePG Operator" - Jeremy Schneider, GEICO Tech & Gabriele Bartolini, EDB
- April 4, 2025, KubeCon Europe in London: "Consistent Volume Group Snapshots, Unraveling the Magic" - Leonardo Cecchi (EDB) and Xing Yang (VMware)
- November 11, 2024, Cloud Native Rejekts NA 2024: "Maximising Microservice Databases with Kubernetes, Postgres, and CloudNativePG" - Gabriele Bartolini (EDB) and Leonardo Cecchi (EDB)
- March 21, 2024, KubeCon Europe 2024 in Paris: "Scaling Heights: Mastering Postgres Database Vertical Scalability with Kubernetes Storage Magic" - Gari Singh, Google & Gabriele Bartolini, EDB
- March 19, 2024, Data on Kubernetes Day at KubeCon Europe 2024 in Paris: "From Zero to Hero: Scaling Postgres in Kubernetes Using the Power of CloudNativePG" - Gabriele Bartolini, EDB
- November 7, 2023, KubeCon North America 2023 in Chicago: "Disaster Recovery with Very Large Postgres Databases (in Kubernetes)" - Michelle Au, Google & Gabriele Bartolini, EDB
- October 27, 2022, KubeCon North America 2022 in Detroit: "Data On Kubernetes, Deploying And Running PostgreSQL And Patterns For Databases In a Kubernetes Cluster" - Chris Milsted, Ondat & Gabriele Bartolini, EDB
Useful links
- "Quorum-Based Consistency for Cluster Changes With CloudNativePG Operator" (webinar) - Jeremy Schneider, GEICO Tech & Leonardo Cecchi, EDB
- Data on Kubernetes (DoK) Community
- "Cloud Neutral Postgres Databases with Kubernetes and CloudNativePG" by Gabriele Bartolini (November 2024)
- "How to migrate your PostgreSQL database in Kubernetes with ~0 downtime from anywhere" by Gabriele Bartolini (March 2024)
- "Maximizing Microservice Databases with Kubernetes, Postgres, and CloudNativePG" by Gabriele Bartolini (February 2024)
- "Recommended Architectures for PostgreSQL in Kubernetes" by Gabriele Bartolini (September 2023)
- "The Current State of Major PostgreSQL Upgrades with CloudNativePG" by Gabriele Bartolini (August 2023)
- "The Rise of the Kubernetes Native Database" by Jeff Carpenter (December 2022)
- "Why Run Postgres in Kubernetes?" by Gabriele Bartolini (May 2022)
- "Shift-Left Security: The Path To PostgreSQL On Kubernetes" by Gabriele Bartolini (April 2021)
- "Local Persistent Volumes and PostgreSQL usage in Kubernetes" by Gabriele Bartolini (June 2020)
We are a Cloud Native Computing Foundation Sandbox project.
CloudNativePG was originally built and sponsored by EDB.
Postgres, PostgreSQL, and the Slonik Logo are trademarks or registered trademarks of the PostgreSQL Community Association of Canada, and used with their permission.