CloudNativePG
CloudNativePG (CNPG) is an open-source operator
designed to manage PostgreSQL workloads on any supported Kubernetes cluster. It fosters cloud-neutrality through seamless deployment in private, public, hybrid, and multi-cloud environments via its Distributed Topology feature.
Built around DevOps principles, CloudNativePG embraces declarative configuration and immutable infrastructure, ensuring reliability and automation in database management.
At its core, CloudNativePG introduces a custom Kubernetes resource
called Cluster , representing a PostgreSQL cluster with:
A single primary instance for write operations.
Optional replicas for High Availability and read scaling.
These instances reside within a Kubernetes namespace, allowing applications to connect seamlessly using operator-managed services. Failovers and switchovers occur transparently, eliminating the need for manual intervention.
For applications inside the Kubernetes cluster, CNPG provides a
microservice database approach, enabling co-location of PostgreSQL
clusters and applications in the same namespace for optimized access.
For applications outside the cluster, CNPG offers flexible connectivity
through service templates and LoadBalancer services for direct TCP
exposure. Additionally, web applications can take advantage of the
native connection pooler based on PgBouncer.
CloudNativePG was originally built by EDB , then released open source under Apache License 2.0. The source code repository is in GitHub .
Note
Based on the Operator Capability Levels model , users can expect a "Level V - Auto Pilot" subset of capabilities from the CloudNativePG Operator.
- Introduction
- Before you start
- Use cases
- Architecture
- Installation and upgrades
- Installation on Kubernetes
- Details about the deployment
- Upgrades
- Spread Upgrades
- In-place updates of the instance manager
- Compatibility among versions
- Upgrading to 1.28.0 or 1.27.x
- Upgrading to 1.27 from a previous minor version
- Upgrading to 1.26 from a previous minor version
- Deprecation of backup metrics and fields in the
Cluster.status - Declarative Hibernation in the
cnpgplugin
- Verifying release assets
- Quickstart
- Image Catalog
- Bootstrap
- Importing Postgres databases
- Security
- Governance and Trust
- Code
- Container
- Cluster
- Role Based Access Control (RBAC)
- Deployments and
ClusterRoleResources - Why Are ClusterRole Permissions Needed?
- Calls to the API server made by the instance manager
- Pod and Container Security Contexts
- Customizing Security Contexts
- Security Context Constraints
- Restricting Pod access using AppArmor
- Network Policies
- Exposed Ports
- PostgreSQL
- Storage
- Postgres Instance Manager
- Scheduling
- Resource management
- Failure Modes
- Rolling updates
- Replication
- Logical Replication
- Backup
- WAL archiving
- Recovery
- Service management
- PostgreSQL Configuration
- PostgreSQL Role management
- PostgreSQL Database management
- Tablespaces
- Operator configuration
- Instance Pod configuration
- Storage
- Backup and recovery
- Benchmarking CloudNativePG
- Encryption at rest
- Persistent Volume Claim (PVC)
- Configuration via a storage class
- Configuration via a PVC template
- Volume for WAL
- Volumes for tablespaces
- Volume expansion
- Static provisioning of persistent volumes
- Block storage considerations (Ceph/Longhorn)
- Labels and Annotations
- Monitoring
- Monitoring Instances
- Output caching
- Monitoring with the Prometheus operator
- Creating a
PodMonitor - Deprecation of Automatic
PodMonitorCreation - Enabling TLS on the Metrics Port
- Predefined set of metrics
- User defined metrics
- Example of a user defined metric
- Example of a user defined metric with predicate query
- Example of a user defined metric running on multiple databases
- Structure of a user defined metric
- Output of a user defined metric
- Default set of metrics
- Differences with the Prometheus Postgres exporter
- Monitoring the CloudNativePG operator
- How to inspect the exported metrics
- Auxiliary resources
- Monitoring Instances
- Logging
- Certificates
- Client TLS/SSL connections
- Client TLS/SSL connections
- Connecting from an application
- Connection Pooling
- Replica clusters
- Kubernetes upgrade and maintenance
- PostgreSQL upgrades
- Kubectl Plugin
- Install
- Use
- Generation of installation manifests
- Status
- Promote
- Certificates
- Restart
- Reload
- Maintenance
- Report
- report Operator
- report Cluster
- Logs
- Cluster logs
- Pretty
- Destroy
- Cluster Hibernation
- Benchmarking the database with pgbench
- Benchmarking the storage with fio
- Requesting a new physical backup
- Launching psql
- Snapshotting a Postgres cluster
- Using pgAdmin4 for evaluation/demonstration purposes only
- Logical Replication Publications
- Creating a new publication
- Dropping a publication
- Logical Replication Subscriptions
- Creating a new subscription
- Dropping a subscription
- Synchronizing sequences
- Integration with K9s
- Permissions required by the plugin
- Automated failover
- RTO and RPO impact
- Delayed failover
- Failover Quorum (Quorum-based Failover)
- How it works
- Quorum Failover Example Scenarios
- Scenario 1: Three-node cluster, failing pod(s)
- Scenario 2: Three-node cluster, network partition
- Scenario 3: Five-node cluster, network partition
- Scenario 4: Three-node cluster with remote synchronous replicas
- Scenario 5: Three-node cluster, preferred data durability, network partition
- Troubleshooting
- Before you start
- First steps
- Are there backups?
- Emergency backup
- Logs
- Operator information
- Cluster information
- Pod information
- Backup information
- Storage information
- Node information
- Conditions
- Networking
- PostgreSQL core dumps
- Visualizing and Analyzing Profiling Data
- Some known issues
- Storage is full
- Pods are stuck in
Pendingstate - Replicas out of sync when no backup is configured
- Cluster stuck in
Creating new replica - Networking is impaired by installed Network Policies
- Error while bootstrapping the data directory
- Bootstrap job hangs in running status
- Replicas take over two minutes to reconnect after a failover
- Fencing
- Declarative hibernation
- PostGIS
- End-to-End Tests
- Container Image Requirements
- Image Volume Extensions
- CNPG-I
- Operator capability levels
- Level 1: Basic install
- Operator deployment via declarative configuration
- PostgreSQL cluster deployment via declarative configuration
- Override of operand images through the CRD
- Labels and annotations
- Self-contained instance manager
- Storage configuration
- Replica configuration
- Service Configuration
- Database configuration
- Configuration of Postgres roles, users, and groups
- Configuration of Postgres extensions
- Pod security standards
- Affinity
- Topology spread constraints
- Command-line interface
- Current status of the cluster
- Operator’s certification authority
- Cluster’s certification authority
- TLS connections
- Certificate authentication for streaming replication
- Continuous configuration management
- Import of existing PostgreSQL databases
- PostGIS clusters
- Basic LDAP authentication for PostgreSQL
- Multiple installation methods
- Convention over configuration
- Level 2: Seamless upgrades
- Level 3: Full lifecycle
- PostgreSQL WAL archive
- PostgreSQL Backups
- Backups from a standby
- Full restore from a backup
- Point-in-time recovery (PITR) from a backup
- Zero-Data-Loss Clusters Through Synchronous Replication
- Replica clusters
- Distributed Database Topologies
- Tablespace support
- Customizable Startup, Liveness, and Readiness Probes
- Rolling deployments
- Scale up and down of replicas
- Maintenance window and PodDisruptionBudget for Kubernetes nodes
- Fencing
- Hibernation
- Reuse of persistent volumes storage in pods
- CPU and memory requests and limits
- Connection pooling with PgBouncer
- Logical Replication
- Level 4: Deep insights
- Level 5: Auto pilot
- Level 1: Basic install
- Custom Pod Controller
- Examples
- Networking
- Benchmarking
- Frequently Asked Questions (FAQ)
- API Reference
- API Reference
- Packages
- postgresql.cnpg.io/v1
- Resource Types
- AffinityConfiguration
- AvailableArchitecture
- Backup
- BackupConfiguration
- BackupMethod
- BackupPhase
- BackupPluginConfiguration
- BackupSnapshotElementStatus
- BackupSnapshotStatus
- BackupSource
- BackupSpec
- BackupStatus
- BackupTarget
- BootstrapConfiguration
- BootstrapInitDB
- BootstrapPgBaseBackup
- BootstrapRecovery
- CatalogImage
- CertificatesConfiguration
- CertificatesStatus
- Cluster
- ClusterImageCatalog
- ClusterMonitoringTLSConfiguration
- ClusterSpec
- ClusterStatus
- ConfigMapResourceVersion
- DataDurabilityLevel
- DataSource
- Database
- DatabaseObjectSpec
- DatabaseObjectStatus
- DatabaseReclaimPolicy
- DatabaseRoleRef
- DatabaseSpec
- DatabaseStatus
- EmbeddedObjectMetadata
- EnsureOption
- EphemeralVolumesSizeLimitConfiguration
- ExtensionConfiguration
- ExtensionSpec
- ExternalCluster
- FDWSpec
- FailoverQuorum
- FailoverQuorumStatus
- ImageCatalog
- ImageCatalogRef
- ImageCatalogSpec
- ImageInfo
- Import
- ImportSource
- InstanceID
- InstanceReportedState
- IsolationCheckConfiguration
- LDAPBindAsAuth
- LDAPBindSearchAuth
- LDAPConfig
- LDAPScheme
- LivenessProbe
- ManagedConfiguration
- ManagedRoles
- ManagedService
- ManagedServices
- Metadata
- MonitoringConfiguration
- NodeMaintenanceWindow
- OnlineConfiguration
- OptionSpec
- PasswordState
- PgBouncerIntegrationStatus
- PgBouncerPoolMode
- PgBouncerSecrets
- PgBouncerSpec
- PluginConfiguration
- PluginStatus
- PodName
- PodStatus
- PodTemplateSpec
- PodTopologyLabels
- Pooler
- PoolerIntegrations
- PoolerMonitoringConfiguration
- PoolerSecrets
- PoolerSpec
- PoolerStatus
- PoolerType
- PostgresConfiguration
- PrimaryUpdateMethod
- PrimaryUpdateStrategy
- Probe
- ProbeStrategyType
- ProbeWithStrategy
- ProbesConfiguration
- Publication
- PublicationReclaimPolicy
- PublicationSpec
- PublicationStatus
- PublicationTarget
- PublicationTargetObject
- PublicationTargetTable
- RecoveryTarget
- ReplicaClusterConfiguration
- ReplicationSlotsConfiguration
- ReplicationSlotsHAConfiguration
- RoleConfiguration
- RoleStatus
- SQLRefs
- ScheduledBackup
- ScheduledBackupSpec
- ScheduledBackupStatus
- SchemaSpec
- SecretVersion
- SecretsResourceVersion
- ServerSpec
- ServiceAccountTemplate
- ServiceSelectorType
- ServiceTemplateSpec
- ServiceUpdateStrategy
- SnapshotOwnerReference
- SnapshotType
- StorageConfiguration
- Subscription
- SubscriptionReclaimPolicy
- SubscriptionSpec
- SubscriptionStatus
- SwitchReplicaClusterStatus
- SyncReplicaElectionConstraints
- SynchronizeReplicasConfiguration
- SynchronousReplicaConfiguration
- SynchronousReplicaConfigurationMethod
- TablespaceConfiguration
- TablespaceState
- TablespaceStatus
- Topology
- UsageSpec
- UsageSpecType
- VolumeSnapshotConfiguration
- Supported releases
- Preview Versions
- Release notes
- Release notes for CloudNativePG 1.28
- Release notes for CloudNativePG 1.28
- Release notes for CloudNativePG 1.27
- Release notes for CloudNativePG 1.26
- Old Release notes
- Release notes for CloudNativePG 1.25
- Release notes for CloudNativePG 1.24
- Release notes for CloudNativePG 1.23
- Release notes for CloudNativePG 1.22
- Release notes for CloudNativePG 1.21
- Release notes for CloudNativePG 1.20
- Release notes for CloudNativePG 1.19
- Release notes for CloudNativePG 1.18
- Release notes for CloudNativePG 1.17
- Release notes for CloudNativePG 1.16
- Release notes for CloudNativePG 1.15
- EDB Cloud-Native PostgreSQL
- CNCF Projects Integrations
- Appendixes