Welcome to the CloudNativePG project!

CloudNativePG is an open source operator designed to manage
PostgreSQL workloads on any supported Kubernetes
cluster running in private, public, hybrid, or multi-cloud environments.

CloudNativePG was originally built and sponsored by EDB.

Table of content

• Code of conduct
• Governance policies
• Contributing
• License

Getting Started

The best way to get started is with the "Quickstart"
section in the documentation.

Scope

The goal of CloudNativePG is to increase the adoption of PostgreSQL, one of the
most loved DBMS in traditional VM and bare metal environments, inside
Kubernetes, thus making the database an integral part of the development
process and CI/CD automated pipelines.

In scope

CloudNativePG has been designed by Postgres experts with Kubernetes
administrators in mind. Put simply, it leverages Kubernetes by extending its
controller and by defining, in a programmatic way, all the actions that a good
DBA would normally do when managing a highly available PostgreSQL database
cluster.

Since the inception, our philosophy has been to adopt a Kubernetes native
approach to PostgreSQL cluster management, making incremental decisions that
would answer the fundamental question: "What would a Kubernetes user expect
from a Postgres operator?".

The most important decision we made is to have the status of a PostgreSQL
cluster directly available in the Cluster resource, so to inspect it through
the Kubernetes API. We've fully embraced the operator pattern and eventual
consistency, two of the core principles upon which Kubernetes is built for
managing complex applications.

As a result, the operator is responsible for managing the status of the
Cluster resource, keeping it up to date with the information that each
PostgreSQL instance manager regularly reports back through the API server. Such
changes might trigger, for example, actions like:

• a PostgreSQL failover where, after an unexpected failure of a cluster's
  primary instance, the operator itself elects the new primary, updates the
  status, and directly coordinates the operation through the reconciliation
  loop, by relying on the instance managers

• scaling up or down the number of read-only replicas, based on a positive or
  negative variation in the number of desired instances in the cluster, so that
  the operator creates or removes the required resources to run PostgreSQL,
  such as persistent volumes, persistent volume claims, pods, secrets, config
  maps, and then coordinates cloning and streaming replication tasks

• updates of the endpoints of the PostgreSQL services that applications rely on
  to interact with the database, as Kubernetes represents the single source of
  truth and authority

• updates of container images in a rolling fashion, following a change in the
  image name, by first updating the pods where replicas are running, and then
  the primary, issuing a switchover first

The latter example is based on another pillar of CloudNativePG:
immutable application containers - as explained in the
blog article "Why EDB Chose Immutable Application Containers".

The above list can be extended. However, the gist is that CloudNativePG
exclusively relies on the Kubernetes API server and the instance manager to
coordinate the complex operations that need to take place in a business
continuity PostgreSQL cluster, without requiring any assistance from an
intermediate management tool responsible for high availability and failover
management like similar open source operators.

CloudNativePG also manages additional resources to help the Cluster resource
manage PostgreSQL - currently ScheduledBackup, Pooler, and Backup.

Fully embracing Kubernetes also means that, in case of failure of the whole
Kubernetes cluster, the operator won’t do anything, postponing any decision to
when the cluster is back up again. In the meantime, Postgres instances should
continue running according to the last known state of the cluster.

Out of scope

CloudNativePG is exclusively focused on the PostgreSQL database management
system maintained by the PostgreSQL Global Development Group (PGDG). We are not
currently considering adding to CloudNativePG extensions or capabilities that
are included in forks of the PostgreSQL database management system, unless in
the form of extensible or pluggable frameworks.

CloudNativePG doesn't intend to pursue database independence (e.g. control a
MariaDB cluster).

Communications

• Slack Channel
• Github Discussions
• Twitter

Resources

• Roadmap
• Website
• FAQ
• Blog
• "Why Run Postgres in Kubernetes?" (May 2022)
• "Shift-Left Security: The Path To PostgreSQL On Kubernetes" (April 2021)
• "Local Persistent Volumes and PostgreSQL usage in Kubernetes" (June 2020)

Maintainers

The current maintainers of the CloudNativePG project are:

• Gabriele Bartolini (EDB)
• Francesco Canovai (EDB)
• Leonardo Cecchi (EDB)
• Jonathan Gonzalez (EDB)
• Marco Nenciarini (EDB)
• Armando Ruocco (EDB)
• Philippe Scorsolini (upbound)

They are listed in the CODEOWNERS file.

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!

Star History

Trademarks

Postgres, PostgreSQL and the Slonik Logo
are trademarks or registered trademarks of the PostgreSQL Community Association
of Canada, and used with their permission.