CloudNativePG

• Introduction
  • 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
  • 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
    • In-place updates of the instance manager
    • Compatibility among versions
    • Upgrading to 1.24.0 or 1.23.3
    • From Replica Clusters to Distributed Topology
    • Upgrading to 1.23 from a previous minor version
    • User defined replication slots
    • Server-side apply of manifests
    • Upgrading to 1.22 from a previous minor version
• 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
  • Import optimizations
• Security
  • Code
  • Container
    • 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 Security Policies
    • Restricting Pod access using AppArmor
    • Network Policies
    • Exposed Ports
    • PostgreSQL
    • Storage
• Postgres instance manager
  • Startup, liveness and readiness probes
  • Shutdown control
    • Shutdown of the primary during a switchover
  • Failover
  • Disk Full Failure
• Scheduling
  • Pod affinity and anti-affinity
  • Node selection through nodeSelector
  • Tolerations
• Resource management
• Failure Modes
  • Storage space usage
  • Failure modes
    • Pod deleted by the user
    • Readiness probe failure
    • Liveness probe failure
    • Worker node drained
    • Worker node failure
  • Self-healing
  • Manual intervention
• 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
    • Migrating from the Deprecated Synchronous Replication Implementation
    • Priority-based Synchronous Replication
    • Controlling synchronous_standby_names Content
    • Examples
  • Synchronous Replication (Deprecated)
    • Select nodes for synchronous replication
  • Replication slots
    • Replication slots for High Availability
    • User-Defined Replication slots
    • Synchronization frequency
    • Capping the WAL size retained for replication slots
    • Monitoring replication slots
• Backup
  • WAL archive
  • Cold and Hot backups
  • Object stores or volume snapshots: which one to use?
  • Scheduled backups
  • On-demand backups
  • Backup from a standby
• Backup on object stores
  • Common object stores
  • Retention policies
  • Compression algorithms
  • Tagging of backup objects
  • Extra options for the backup and WAL commands
• WAL archiving
• Backup on volume snapshots
  • About standard Volume Snapshots
  • Requirements
  • How to configure Volume Snapshot backups
  • Hot and cold backups
    • Overriding the default behavior
  • Persistence of volume snapshot objects
  • Example
• Recovery
  • Recovery from an object store
  • Recovery from VolumeSnapshot objects
  • Recovery from a Backup object
  • Additional Considerations
  • Point in time recovery (PITR)
    • PITR from an object store
    • 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
    • Replication settings
    • Log control settings
    • Shared Preload Libraries
    • Managed extensions
    • Enabling auto_explain
    • Enabling pg_stat_statements
    • Enabling pgaudit
    • Enabling pg_failover_slots
  • The pg_hba section
    • LDAP Configuration
  • The pg_ident section
  • Changing configuration
  • Enabling ALTER SYSTEM
  • Dynamic Shared Memory settings
    • POSIX shared memory
    • System V shared memory
  • Fixed parameters
• Database Role Management
  • Password management
    • Password expiry, VALID UNTIL
    • Password hashed
  • Unrealizable role configurations
  • Status of managed roles
• 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
  • 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
    • Expanding PVC volumes on AKS
    • Workaround for volume expansion on AKS
    • 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
    • Prometheus Operator example
    • 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 operator
    • Prometheus Operator example
  • How to inspect the exported metrics
  • Auxiliary resources
• Logging
  • Operator log
  • PostgreSQL log
  • 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
    • 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
  • 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
• Kubectl Plugin
  • Install
    • Via the installation script
    • Using the Debian or RedHat packages
    • Debian packages
    • RPM packages
    • Using Krew
    • Using Homebrew
    • Supported Architectures
    • Configuring auto-completion
  • Use
    • Status
    • Promote
    • Certificates
    • Restart
    • Reload
    • Maintenance
    • Report
    • report Operator
    • report Cluster
    • Logs
    • Cluster logs
    • 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
• Automated failover
  • RTO and RPO impact
  • Delayed failover
• 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
• 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
• 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 policies
    • 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
    • Upgrade of the operator
    • Upgrade of the managed workload
    • 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
    • Liveness and readiness probes
    • Rolling deployments
    • Scale up and down of replicas
    • Maintenance window and PodDisruptionBudget for Kubernetes nodes
    • Fencing
    • Hibernation (declarative)
    • Hibernation (imperative)
    • Reuse of persistent volumes storage in pods
    • CPU and memory requests and limits
    • Connection pooling with PgBouncer
  • 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
• Networking
  • Cross-namespace network policy for the operator
  • Cross-cluster networking
• Benchmarking
  • pgbench
  • fio
• Commercial support
• Frequently Asked Questions (FAQ)
  • Running PostgreSQL in Kubernetes
  • High availability
• API Reference
  • Resource Types
  • Backup
  • Cluster
  • ClusterImageCatalog
  • ImageCatalog
  • Pooler
  • ScheduledBackup
  • AffinityConfiguration
  • AvailableArchitecture
  • AzureCredentials
  • BackupConfiguration
  • BackupMethod
  • BackupPhase
  • BackupPluginConfiguration
  • BackupSnapshotElementStatus
  • BackupSnapshotStatus
  • BackupSource
  • BackupSpec
  • BackupStatus
  • BackupTarget
  • BarmanCredentials
  • BarmanObjectStoreConfiguration
  • BootstrapConfiguration
  • BootstrapInitDB
  • BootstrapPgBaseBackup
  • BootstrapRecovery
  • CatalogImage
  • CertificatesConfiguration
  • CertificatesStatus
  • ClusterMonitoringTLSConfiguration
  • ClusterSpec
  • ClusterStatus
  • CompressionType
  • ConfigMapKeySelector
  • ConfigMapResourceVersion
  • DataBackupConfiguration
  • DataSource
  • DatabaseRoleRef
  • EmbeddedObjectMetadata
  • EncryptionType
  • EnsureOption
  • EphemeralVolumesSizeLimitConfiguration
  • ExternalCluster
  • GoogleCredentials
  • ImageCatalogRef
  • ImageCatalogSpec
  • Import
  • ImportSource
  • InstanceID
  • InstanceReportedState
  • LDAPBindAsAuth
  • LDAPBindSearchAuth
  • LDAPConfig
  • LDAPScheme
  • LocalObjectReference
  • ManagedConfiguration
  • ManagedRoles
  • ManagedService
  • ManagedServices
  • Metadata
  • MonitoringConfiguration
  • NodeMaintenanceWindow
  • OnlineConfiguration
  • PasswordState
  • PgBouncerIntegrationStatus
  • PgBouncerPoolMode
  • PgBouncerSecrets
  • PgBouncerSpec
  • PluginStatus
  • PodTemplateSpec
  • PodTopologyLabels
  • PoolerIntegrations
  • PoolerMonitoringConfiguration
  • PoolerSecrets
  • PoolerSpec
  • PoolerStatus
  • PoolerType
  • PostgresConfiguration
  • PrimaryUpdateMethod
  • PrimaryUpdateStrategy
  • RecoveryTarget
  • ReplicaClusterConfiguration
  • ReplicationSlotsConfiguration
  • ReplicationSlotsHAConfiguration
  • RoleConfiguration
  • S3Credentials
  • SQLRefs
  • ScheduledBackupSpec
  • ScheduledBackupStatus
  • SecretKeySelector
  • SecretVersion
  • SecretsResourceVersion
  • ServiceAccountTemplate
  • ServiceSelectorType
  • ServiceTemplateSpec
  • ServiceUpdateStrategy
  • SnapshotOwnerReference
  • SnapshotType
  • StorageConfiguration
  • SwitchReplicaClusterStatus
  • SyncReplicaElectionConstraints
  • SynchronizeReplicasConfiguration
  • SynchronousReplicaConfiguration
  • SynchronousReplicaConfigurationMethod
  • TablespaceConfiguration
  • TablespaceState
  • TablespaceStatus
  • Topology
  • VolumeSnapshotConfiguration
  • WalBackupConfiguration
• 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 notes
  • Release notes for CloudNativePG 1.23
    • Version 1.23.3
    • Version 1.23.2
    • Version 1.23.1
    • Version 1.23.0
  • Release notes for CloudNativePG 1.22
    • Version 1.22.5
    • Version 1.22.4
    • Version 1.22.3
    • Version 1.22.2
    • Version 1.22.1
    • Version 1.22.0
  • old release notes
    • 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
  • 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
• appendixes
  • Appendix A - Common object stores for backups
    • AWS S3
    • Azure Blob Storage
    • Google Cloud Storage
    • MinIO Gateway