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

• Code of Conduct
• Governance Policies
• Contributing
• Adopters
• Commercial Support
• License

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 Cluster resource, 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 Channel
• Twitter
• Mastodon
• Bluesky

Resources

• Roadmap
• Website
• FAQ
• Blog
• CloudNativePG plugin Interface (CNPG-I).

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

• 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)
• 7 November 2023, KubeCon North America 2023 in Chicago: "Disaster Recovery with Very Large Postgres Databases (in Kubernetes)" (Michelle Au, Google & Gabriele Bartolini, EDB)
• 27 October 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

• 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.

---