CloudNativePG

• CloudNativePG
  • Supported Kubernetes distributions
  • Container images
    • Operator
    • Operands
  • Main features
  • About this guide
• Before You Start
  • Kubernetes terminology
  • PostgreSQL terminology
  • Cloud terminology
  • What to do next
• Use cases
  • Case 1: Applications inside Kubernetes
  • Case 2: Applications outside Kubernetes
• Architecture
  • Synchronizing the state
  • Kubernetes architecture
    • Multi-availability zone Kubernetes clusters
    • Single availability zone Kubernetes clusters
    • Reserving nodes for PostgreSQL workloads
    • Proposed node label
    • Proposed node taint
  • PostgreSQL architecture
    • Read-write workloads
    • Read-only workloads
  • Deployments across Kubernetes clusters
• Installation and upgrades
  • Installation on Kubernetes
    • Directly using the operator manifest
    • Using the cnpg plugin for kubectl
    • Testing the latest development snapshot
    • Using the Helm Chart
    • Using OLM
  • 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.0 or 1.26.1
    • Upgrading to 1.26 from a previous minor version
    • Deprecation of backup metrics and fields in the Cluster .status
    • Declarative Hibernation in the cnpg plugin
    • Upgrading to 1.25 from a previous minor version
    • Upgrading to 1.24 from a previous minor version
    • From Replica Clusters to Distributed Topology
• Quickstart
  • Part 1: Setup the local Kubernetes playground
    • Minikube
    • Kind
  • Part 2: Install CloudNativePG
  • Part 3: Deploy a PostgreSQL cluster
  • Part 4: Monitor clusters with Prometheus and Grafana
    • Installation
    • Viewing with Prometheus
    • Grafana Dashboard
• Image Catalog
  • CloudNativePG Catalogs
    • PostgreSQL Container Images
    • PostGIS Container Images
• Bootstrap
  • The bootstrap section
  • The externalClusters section
    • Password files
  • Bootstrap an empty cluster (initdb )
    • Passing Options to initdb
    • Executing Queries After Initialization
  • Bootstrap from another cluster
    • Bootstrap from a backup (recovery )
    • Bootstrap from a live cluster (pg_basebackup )
    • Requirements
    • About the replication user
    • Username/Password authentication
    • TLS certificate authentication
    • Configure the application database
    • Current limitations
• Importing Postgres databases
  • How it works
  • The microservice type
  • The monolith type
  • A practical example
  • Import optimizations
  • Customizing pg_dump and pg_restore Behavior
  • Online Import and Upgrades
• Security
  • Code
  • Container
    • Image Signatures
    • Attestations
    • Guidelines and Frameworks for Container Security
  • Cluster
    • Role Based Access Control (RBAC)
    • Deployments and ClusterRole Resources
    • Why Are ClusterRole Permissions Needed?
    • Calls to the API server made by the instance manager
    • Pod and Container Security Contexts
    • Security Context Constraints
    • Restricting Pod access using AppArmor
    • Network Policies
    • Exposed Ports
    • PostgreSQL
    • Storage
• Postgres instance manager
  • Startup Probe
    • Startup Probe Strategy
  • Liveness Probe
    • Primary Isolation
  • Readiness Probe
    • Readiness Probe Strategy
  • Shutdown control
    • Shutdown of the primary during a switchover
  • Failover
  • Disk Full Failure
• Scheduling
  • Pod Affinity and Anti-Affinity
    • Requiring Pod Anti-Affinity
    • Topology Considerations
    • Disabling Anti-Affinity Policies
    • Fine-Grained Control with Custom Rules
  • Node selection through nodeSelector
  • Tolerations
  • Isolating PostgreSQL workloads
• Resource management
• Failure Modes
  • Self-Healing
    • Primary Failure
    • Standby Failure
  • Manual Intervention
    • Disabling Reconciliation
• Rolling Updates
  • Automated updates (unsupervised )
  • Manual updates (supervised )
• Replication
  • Application-level replication
  • A very mature technology
  • Streaming replication support
    • Continuous backup integration
  • Synchronous Replication
    • Quorum-based Synchronous Replication
    • Example
    • Migrating from Deprecated Synchronous Replication Implementation
    • Priority-based Synchronous Replication
    • Controlling synchronous_standby_names Content
    • Examples
    • Data Durability and Synchronous Replication
    • Required Data Durability
    • Preferred Data Durability
  • Synchronous Replication (Deprecated)
    • Select nodes for synchronous replication
  • Replication slots
    • Replication slots for High Availability
    • User-Defined Replication slots
    • Synchronization frequency
    • Logical Decoding Slot Synchronization
    • Behavior on PostgreSQL 17 and later
    • Behavior on PostgreSQL 16 and earlier
    • Capping the WAL size retained for replication slots
    • Monitoring replication slots
• Logical Replication
  • Publications
    • Required Fields in the Publication Manifest
    • Reconciliation and Status
    • Removing a publication
  • Subscriptions
    • Required Fields in the Subscription Manifest
    • Reconciliation and Status
    • Removing a Subscription
    • Resilience to Failovers
  • Limitations
    • Addressing Schema Replication
    • Handling Sequences
  • Example of live migration and major Postgres upgrade with logical replication
    • Step 1: Setting Up the Publisher (freddie )
    • Step 2: Setting Up the Subscriber (king )
• Backup
  • Main Concepts
    • WAL archive
    • Cold and Hot backups
  • Comparing Available Backup Options: Object Stores vs Volume Snapshots
    • Object Store–Based Backups
    • Volume Snapshots
    • Choosing Between the Two
    • Comparison Summary
  • Backup Methods
  • Backup from a Standby
    • How It Works
    • Forcing Backup on the Primary
    • Overriding the Cluster-Wide Target
  • Retention Policies
• WAL archiving
  • Plugin-Based Architecture
  • Supported Plugins
  • Deprecation Notice: Native Barman Cloud
  • About the archive timeout
• Recovery
  • Recovery from an Object Store with the Barman Cloud Plugin
  • Recovery from VolumeSnapshot Objects
  • Recovery from a Backup object
  • Additional Considerations
  • Point in time recovery (PITR)
    • PITR from an object store
    • Point-in-Time Recovery (PITR) from VolumeSnapshot Objects
    • Recovery targets
  • Configure the application database
  • How recovery works under the hood
  • Restoring into a Cluster with a Backup Section
• Service Management
  • Disabling Default Services
  • Adding Your Own Services
    • About Exposing Postgres Services
• PostgreSQL Configuration
  • The postgresql section
    • Write-Ahead Log Level
    • Replication Settings
    • Log control settings
    • Shared Preload Libraries
    • Managed extensions
    • Enabling auto_explain
    • Enabling pg_stat_statements
    • Enabling pgaudit
  • The pg_hba section
  • The pg_ident section
  • Dynamic Shared Memory settings
    • POSIX shared memory
    • System V shared memory
  • Fixed parameters
• PostgreSQL Role Management
  • Password management
    • Password expiry, VALID UNTIL
    • Password hashed
  • Unrealizable role configurations
  • Status of managed roles
• PostgreSQL Database Management
  • Key Concepts
    • Scope of Management
    • Declarative Database Manifest
    • Required Fields in the Database Manifest
  • Reserved Database Names
  • Reconciliation and Status
  • Deleting a Database
    • Deleting via delete Reclaim Policy
    • Declaratively Setting ensure: absent
  • Managing Extensions in a Database
  • Managing Schemas in a Database
  • Managing Foreign Data Wrappers (FDWs) In a Database
  • Limitations and Caveats
    • Renaming a database
    • Creating vs. Altering a Database
    • Replica Clusters
    • Conflict Resolution
    • Postgres Version Differences
    • Manual Changes
• Tablespaces
  • Declarative tablespaces
  • Using declarative tablespaces
  • Storage classes and tablespaces
  • Tablespace ownership
  • Backup and recovery
  • Replica clusters
  • Temporary tablespaces
  • kubectl plugin support
  • Limitations
• Operator configuration
  • Available options
  • Defining an operator config map
  • Defining an operator secret
  • Restarting the operator to reload configs
  • pprof HTTP Server
• Instance pod configuration
  • Projected volumes
  • Ephemeral volumes
    • Volume Claim Template for Temporary Storage
    • Volume for shared memory
  • Environment variables
• 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
    • Using the volume expansion Kubernetes feature
    • Re-creating storage
  • Static provisioning of persistent volumes
  • Block storage considerations (Ceph/Longhorn)
• Labels and annotations
  • Predefined labels
  • Predefined annotations
  • Prerequisites
  • Defining cluster’s metadata
  • Current limitations
• Monitoring
  • Monitoring Instances
    • Monitoring with the Prometheus operator
    • 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
    • Monitoring the operator with Prometheus
  • How to inspect the exported metrics
    • Using port forwarding
    • Using curl
  • Auxiliary resources
• Logging
  • Cluster Logs
  • Operator Logs
  • PostgreSQL Logs
  • PGAudit Logs
  • Other Logs
• Certificates
  • Operator-Managed Mode
    • Server certificates
    • Server CA secret
    • Server TLS secret
    • Server alternative DNS names
    • Client certificates
    • Client CA secret
    • Client streaming_replica certificate
  • User-provided certificates mode
    • Server certificates
    • Example
    • Cert-manager example
    • Client certificate
    • Customizing the streaming_replica client certificate
    • Cert-manager example
• Client TLS/SSL connections
  • Issuing a new certificate
  • Testing the connection via a TLS certificate
  • About TLS protocol versions
• Connecting from an application
  • DNS resolution
  • Environment variables
  • Secrets
• Connection pooling
  • Architecture
  • Quick start
  • Pooler resource lifecycle
  • Security
    • Certificates
  • Authentication
  • Pod templates
  • Service Template
  • High availability (HA)
  • PgBouncer configuration options
  • Monitoring
  • Logging
  • Pausing connections
  • Limitations
    • Single PostgreSQL cluster
    • Controlled configurability
• Replica clusters
  • Basic Concepts
    • About PostgreSQL Roles
    • Bootstrapping a Replica Cluster
    • Configuring Replication
    • Defining an External Cluster
    • Backup and Symmetric Architectures
    • Distributed Architecture Flexibility
  • Setting Up a Replica Cluster
  • Distributed Topology
    • Planning for a Distributed PostgreSQL Database
    • Demoting a Primary to a Replica Cluster
    • Promoting a Replica to a Primary Cluster
  • Standalone Replica Clusters
    • Main Differences with Distributed Topology
    • Example of Standalone Replica Cluster using pg_basebackup
    • Example of Standalone Replica Cluster from an object store
    • Example using a Volume Snapshot
  • Delayed replicas
• Kubernetes Upgrade and Maintenance
  • Importance of Regular Updates
  • Maintenance Operations in a Cluster
  • Temporary PostgreSQL Cluster Degradation
  • Pod Disruption Budgets
  • PostgreSQL Clusters used for Development or Testing
  • Node Maintenance Window
    • Single instance clusters with reusePVC set to false
• PostgreSQL Upgrades
  • Minor Version Upgrades
    • Upgrading a Minor Version in CloudNativePG
  • Major Version Upgrades
  • Offline In-Place Major Upgrades
    • Upgrade Process
    • Post-Upgrade Actions
    • Example: Performing a Major Upgrade
    • Upgrade Process
• Kubectl Plugin
  • Install
    • Via the installation script
    • Using the Debian or RedHat packages
    • Debian packages
    • RPM packages
    • Using the Arch Linux User Repository (AUR) Package
    • Using Krew
    • Using Homebrew
    • Supported Architectures
    • Configuring auto-completion
  • 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
    • Role examples
• 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
    • Kubernetes environment
    • Useful utilities
  • First steps
  • Are there backups?
  • Emergency backup
  • Logs
  • Operator information
    • Gather more information about the operator
  • Cluster information
  • Pod information
    • Gather and filter extra information about PostgreSQL pods
  • Backup information
  • Storage information
  • Node information
  • Conditions
    • How to wait for a particular condition
  • Networking
  • PostgreSQL core dumps
  • Some known issues
    • Storage is full
    • Pods are stuck in Pending state
    • 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
  • How to fence instances
  • How to lift fencing
  • How fencing works
• Declarative hibernation
  • Hibernation
  • Rehydration
• PostGIS
  • Basic concepts about a PostGIS cluster
  • Create a new PostgreSQL cluster with PostGIS
• End-to-End Tests
• Container Image Requirements
  • Image Tag Requirements
• Image Volume Extensions
  • Benefits
  • Requirements
  • How it works
  • How to add a new extension
    • Adding a new extension to a Cluster resource
    • Adding a new extension to a Database resource
  • Advanced Topics
    • Setting Custom Paths
    • Multi-extension Images
    • Including System Libraries
  • Image Specifications
  • Caveats
• CNPG-I
  • Why CNPG-I?
  • Registering a plugin
    • Sidecar Container
    • Standalone Deployment (recommended)
    • Configuring TLS Certificates
  • Using a plugin
  • Community plugins
• 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
    • 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
    • Operator Upgrade
    • Upgrade of the managed workload
    • Offline In-Place Major Upgrades of PostgreSQL
    • Display cluster availability status during upgrade
  • 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
    • Prometheus exporter with configurable queries
    • Grafana dashboard
    • Standard output logging of PostgreSQL error messages in JSON format
    • Real-time query monitoring
    • Audit
    • Kubernetes events
  • Level 5: Auto pilot
    • Automated failover for self-healing
    • Automated recreation of a standby
• Custom Pod Controller
  • PVC resizing
  • Primary Instances versus Replicas
  • Coherence of PVCs
  • Local storage, remote storage, and database size
• Examples
  • Basics
  • Backups
  • Replica clusters
  • PostGIS
  • Managed roles
  • Managed services
  • Declarative tablespaces
  • Pooler configuration
  • Logical replication via declarative Publication and Subscription objects
  • Declarative management of Postgres databases
• Networking
  • Cross-namespace network policy for the operator
  • Cross-cluster networking
• Benchmarking
  • pgbench
  • fio
• Frequently Asked Questions (FAQ)
  • Running PostgreSQL in Kubernetes
  • High availability
• API Reference
  • Resource Types
  • Backup
  • Cluster
  • ClusterImageCatalog
  • Database
  • FailoverQuorum
  • ImageCatalog
  • Pooler
  • Publication
  • ScheduledBackup
  • Subscription
  • AffinityConfiguration
  • AvailableArchitecture
  • BackupConfiguration
  • BackupMethod
  • BackupPhase
  • BackupPluginConfiguration
  • BackupSnapshotElementStatus
  • BackupSnapshotStatus
  • BackupSource
  • BackupSpec
  • BackupStatus
  • BackupTarget
  • BootstrapConfiguration
  • BootstrapInitDB
  • BootstrapPgBaseBackup
  • BootstrapRecovery
  • CatalogImage
  • CertificatesConfiguration
  • CertificatesStatus
  • ClusterMonitoringTLSConfiguration
  • ClusterSpec
  • ClusterStatus
  • ConfigMapResourceVersion
  • DataDurabilityLevel
  • DataSource
  • DatabaseObjectSpec
  • DatabaseObjectStatus
  • DatabaseReclaimPolicy
  • DatabaseRoleRef
  • DatabaseSpec
  • DatabaseStatus
  • EmbeddedObjectMetadata
  • EnsureOption
  • EphemeralVolumesSizeLimitConfiguration
  • ExtensionConfiguration
  • ExtensionSpec
  • ExternalCluster
  • FDWSpec
  • FailoverQuorumStatus
  • ImageCatalogRef
  • ImageCatalogSpec
  • ImageInfo
  • Import
  • ImportSource
  • InstanceID
  • InstanceReportedState
  • IsolationCheckConfiguration
  • LDAPBindAsAuth
  • LDAPBindSearchAuth
  • LDAPConfig
  • LDAPScheme
  • LivenessProbe
  • ManagedConfiguration
  • ManagedRoles
  • ManagedService
  • ManagedServices
  • Metadata
  • MonitoringConfiguration
  • NodeMaintenanceWindow
  • OnlineConfiguration
  • OptionSpec
  • OptionSpecValue
  • PasswordState
  • PgBouncerIntegrationStatus
  • PgBouncerPoolMode
  • PgBouncerSecrets
  • PgBouncerSpec
  • PluginConfiguration
  • PluginStatus
  • PodTemplateSpec
  • PodTopologyLabels
  • PoolerIntegrations
  • PoolerMonitoringConfiguration
  • PoolerSecrets
  • PoolerSpec
  • PoolerStatus
  • PoolerType
  • PostgresConfiguration
  • PrimaryUpdateMethod
  • PrimaryUpdateStrategy
  • Probe
  • ProbeStrategyType
  • ProbeWithStrategy
  • ProbesConfiguration
  • PublicationReclaimPolicy
  • PublicationSpec
  • PublicationStatus
  • PublicationTarget
  • PublicationTargetObject
  • PublicationTargetTable
  • RecoveryTarget
  • ReplicaClusterConfiguration
  • ReplicationSlotsConfiguration
  • ReplicationSlotsHAConfiguration
  • RoleConfiguration
  • SQLRefs
  • ScheduledBackupSpec
  • ScheduledBackupStatus
  • SchemaSpec
  • SecretVersion
  • SecretsResourceVersion
  • ServiceAccountTemplate
  • ServiceSelectorType
  • ServiceTemplateSpec
  • ServiceUpdateStrategy
  • SnapshotOwnerReference
  • SnapshotType
  • StorageConfiguration
  • SubscriptionReclaimPolicy
  • SubscriptionSpec
  • SubscriptionStatus
  • SwitchReplicaClusterStatus
  • SyncReplicaElectionConstraints
  • SynchronizeReplicasConfiguration
  • SynchronousReplicaConfiguration
  • SynchronousReplicaConfigurationMethod
  • TablespaceConfiguration
  • TablespaceState
  • TablespaceStatus
  • Topology
  • UsageSpec
  • VolumeSnapshotConfiguration
• Supported releases
  • Support Policy
  • Naming Scheme
  • Support status of CloudNativePG releases
    • Supported PostgreSQL versions
  • Upcoming releases
  • Old releases
  • What we mean by support
• Preview Versions
  • Purpose of Release Candidates
  • Community Involvement
  • Usage Advisory
  • Current Preview Version
• Release Note
  • Release notes for CloudNativePG 1.27
    • Version 1.27.0
  • Release notes for CloudNativePG 1.26
    • Version 1.26.1
    • Version 1.26.0
  • Release notes for CloudNativePG 1.25
    • Version 1.25.3
    • Version 1.25.2
    • Version 1.25.1
    • Version 1.25.0
  • Release notes for 1.14.0 and earlier
    • Version 1.14.0
    • Version 1.13.0
    • Version 1.12.0
    • Version 1.11.0
    • Version 1.10.0
    • Version 1.9.2
    • Version 1.9.1
    • Version 1.9.0
    • Version 1.8.0
    • Version 1.7.1
    • Version 1.7.0
    • Version 1.6.0
    • Version 1.5.1
    • Version 1.5.0
    • Version 1.4.0
    • Version 1.3.0
    • Version 1.2.1
    • Version 1.2.0
    •  Version 1.1.0
    • Version 1.0.0