diff --git a/product_docs/docs/postgres_for_kubernetes/1/addons.mdx b/product_docs/docs/postgres_for_kubernetes/1/addons.mdx index fe8935148b..2d507704da 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/addons.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/addons.mdx @@ -11,6 +11,7 @@ per-cluster basis. These add-ons are: 3. [Velero](#velero) !!!info + If you are planning to use Velero in OpenShift, please refer to the [OADP section](openshift.md#oadp-for-velero) in the Openshift documentation. !!! @@ -52,6 +53,7 @@ Recovery simply relies on the operator to reconcile the cluster from an existing PVC group. !!!info Important + The External Backup Adapter is not a tool to perform backups. It simply provides a generic interface that any third-party backup tool in the Kubernetes space can use. Such tools are responsible for safely storing the PVC @@ -329,6 +331,7 @@ Here is a full example of YAML content to be placed in either: for the `external-backup-adapter-cluster` add-on !!!tip Hint + Copy the content below and paste it inside the `ConfigMap` or `Secret` that you use to configure the operator or the annotation in the `Cluster`, making sure you use the `|` character that [YAML reserves for literals](https://yaml.org/spec/1.2.2/#812-literal-style), @@ -449,6 +452,7 @@ ahead replica instance to be the designated backup and will add Kasten-specific backup hooks through annotations and labels to that instance. !!!info Important + The operator will refuse to shut down a primary instance to take a cold backup unless the Cluster is annotated with `k8s.enterprisedb.io/snapshotAllowColdBackupOnPrimary: enabled` @@ -514,6 +518,7 @@ These [annotations](https://velero.io/docs/latest/backup-hooks/) are used by Velero to run the commands to prepare the Postgres instance to be backed up. !!!info Important + The operator will refuse to shut down a primary instance to take a cold backup unless the Cluster is annotated with `k8s.enterprisedb.io/snapshotAllowColdBackupOnPrimary: enabled` @@ -561,6 +566,7 @@ This command will create a standard Velero backup using the configured object storage and the configured Snapshot API. !!!info Important + By default, the Velero add-on exclude only a few resources from the backup operation, namely pods and PVCs of the instances that have not been selected (as you recall, the operator tries to backup the PVCs of the first replica). diff --git a/product_docs/docs/postgres_for_kubernetes/1/appendixes/_category_.json b/product_docs/docs/postgres_for_kubernetes/1/appendixes/_category_.json new file mode 100644 index 0000000000..406ff35478 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/appendixes/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Appendixes", + "position": 600, + "link": { + "type": "generated-index" + } +} diff --git a/product_docs/docs/postgres_for_kubernetes/1/applications.mdx b/product_docs/docs/postgres_for_kubernetes/1/applications.mdx index 97d4b98a31..c0852673a2 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/applications.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/applications.mdx @@ -12,6 +12,7 @@ For more information on services and how to manage them, please refer to the ["Service management"](service_management.md) section. !!!tip Hint + It is highly recommended using those services in your applications, and avoiding connecting directly to a specific PostgreSQL instance, as the latter can change during the cluster lifetime. @@ -26,6 +27,7 @@ For the credentials to connect to PostgreSQL, you can use the secrets generated by the operator. !!!note Connection Pooling + Please refer to the ["Connection Pooling" section](connection_pooling.md) for information about how to take advantage of PgBouncer as a connection pooler, and create an access layer between your applications and the PostgreSQL clusters. @@ -94,5 +96,6 @@ The `-superuser` ones are supposed to be used only for administrative purposes, and correspond to the `postgres` user. !!!info Important + Superuser access over the network is disabled by default. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/architecture.mdx b/product_docs/docs/postgres_for_kubernetes/1/architecture.mdx index 1b8fea5e7b..5269087656 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/architecture.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/architecture.mdx @@ -6,6 +6,7 @@ originalFilePath: 'src/architecture.md' !!!tip Hint + For a deeper understanding, we recommend reading our article on the CNCF blog post titled ["Recommended Architectures for PostgreSQL in Kubernetes"](https://www.cncf.io/blog/2023/09/29/recommended-architectures-for-postgresql-in-kubernetes/), which provides valuable insights into best practices and design @@ -56,6 +57,7 @@ Replicas are usually called *standby servers* and can also be used for read-only workloads, thanks to the *Hot Standby* feature. !!!info Important + **We recommend against storage-level replication with PostgreSQL**, although {{name.ln}} allows you to adopt that strategy. For more information, please refer to the talk given by Chris Milsted and Gabriele Bartolini at KubeCon NA 2022 entitled @@ -79,6 +81,7 @@ This means that **each data center is active at any time** and can run workloads simultaneously. !!!note + Most of the public Cloud Providers' managed Kubernetes services already provide 3 or more availability zones in each region. !!! @@ -112,6 +115,7 @@ managing them via declarative configuration. This setup is ideal for disaster recovery (DR), read-only operations, or cross-region availability. !!!info Important + Each operator deployment can only manage operations within its local Kubernetes cluster. For operations across Kubernetes clusters, such as controlled switchover or unexpected failover, coordination must be handled @@ -144,6 +148,7 @@ the [replica cluster feature](replica_cluster.md)). ![Example of a Kubernetes architecture with only 2 data centers](./images/k8s-architecture-2-az.png) !!!tip Hint + If you are at an early stage of your Kubernetes journey, please share this document with your infrastructure team. The two data centers setup might be simply the result of a "lift-and-shift" transition to Kubernetes @@ -178,6 +183,7 @@ within {{name.ln}}' scope, as the operator can only function within a single Kubernetes cluster. !!!info Important + {{name.ln}} provides all the necessary primitives and probes to coordinate PostgreSQL active/passive topologies across different Kubernetes clusters through a higher-level operator or management tool. @@ -194,6 +200,7 @@ This approach ensures optimal performance and resource allocation for your database operations. !!!tip Hint + As a general rule of thumb, deploy Postgres nodes in multiples of three—ideally with one node per availability zone. Three nodes is an optimal number because it ensures that a PostgreSQL cluster with three @@ -208,6 +215,7 @@ taints help prevent any non-`postgres` workloads from being scheduled on that node. !!!info Important + This methodology is the most straightforward way to ensure that PostgreSQL workloads are isolated from other workloads in terms of both computing resources and, when using locally attached disks, storage. While different @@ -289,6 +297,7 @@ Kubernetes cluster, with the following specifications: within the same Kubernetes cluster / region !!!info Important + You can configure the above services through the `managed.services` section in the `Cluster` configuration. This can be done by reducing the number of services and selecting the type (default is `ClusterIP`). For more details, @@ -309,18 +318,21 @@ automatically updates the `-rw` service to point to the promoted primary, making sure that traffic from the applications is seamlessly redirected. !!!note Replication + Please refer to the ["Replication" section](replication.md) for more information about how {{name.ln}} relies on PostgreSQL replication, including synchronous settings. !!! !!!note Connecting from an application + Please refer to the ["Connecting from an application" section](applications.md) for information about how to connect to {{name.ln}} from a stateless application within the same Kubernetes cluster. !!! !!!note Connection Pooling + Please refer to the ["Connection Pooling" section](connection_pooling.md) for information about how to take advantage of PgBouncer as a connection pooler, and create an access layer between your applications and the PostgreSQL clusters. @@ -343,6 +355,7 @@ service to another instance of the cluster. ### Read-only workloads !!!info Important + Applications must be aware of the limitations that [Hot Standby](https://www.postgresql.org/docs/current/hot-standby.html) presents and familiar with the way PostgreSQL operates when dealing with @@ -363,6 +376,7 @@ Applications can also access any PostgreSQL instance through the ## Deployments across Kubernetes clusters !!!info + {{name.ln}} supports deploying PostgreSQL across multiple Kubernetes clusters through a feature that allows you to define a distributed PostgreSQL topology using replica clusters, as described in this section. @@ -420,6 +434,7 @@ This is typically triggered by: cluster by promoting the PostgreSQL replica cluster. !!!warning + {{name.ln}} cannot perform any cross-cluster automated failover, as it does not have authority beyond a single Kubernetes cluster. Such operations must be performed manually or delegated to a multi-cluster/federated @@ -427,6 +442,7 @@ cluster-aware authority. !!! !!!info Important + {{name.ln}} allows you to control the distributed topology via declarative configuration, enabling you to automate these procedures as part of your Infrastructure as Code (IaC) process, including GitOps. @@ -442,6 +458,7 @@ You can also define replica clusters with a lower number of replicas, and then increase this number when the cluster is promoted to primary. !!!note Replica clusters + Please refer to the ["Replica Clusters" section](replica_cluster.md) for more detailed information on how physical replica clusters operate and how to define a distributed topology with read-only clusters across different diff --git a/product_docs/docs/postgres_for_kubernetes/1/backup.mdx b/product_docs/docs/postgres_for_kubernetes/1/backup.mdx index e2841a02e1..d27fed6074 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/backup.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/backup.mdx @@ -5,52 +5,23 @@ originalFilePath: 'src/backup.md' -!!!info -This section covers **physical backups** in PostgreSQL. -While PostgreSQL also supports logical backups using the `pg_dump` utility, -these are **not suitable for business continuity** and are **not managed** by -{{name.ln}}. If you still wish to use `pg_dump`, refer to the -[*Troubleshooting / Emergency backup* section](troubleshooting.md#emergency-backup) -for guidance. -!!! - -!!!info Important -Starting with version 1.26, native backup and recovery capabilities are -being **progressively phased out** of the core operator and moved to official -CNPG-I plugins. This transition aligns with {{name.ln}}' shift towards a -**backup-agnostic architecture**, enabled by its extensible -interface—**CNPG-I**—which standardizes the management of **WAL archiving**, -**physical base backups**, and corresponding **recovery processes**. -!!! - -{{name.ln}} currently supports **physical backups of PostgreSQL clusters** in -two main ways: - -- **Via [CNPG-I](https://github.com/cloudnative-pg/cnpg-i/) plugins**: the - {{name.ln}} Community officially supports the [**Barman Cloud Plugin**](https://cloudnative-pg.io/plugin-barman-cloud/) - for integration with object storage services. - -- **Natively**, with support for: - - - [Object storage via Barman Cloud](backup_barmanobjectstore.md) - *(although deprecated from 1.26 in favor of the Barman Cloud Plugin)* - - [Kubernetes Volume Snapshots](backup_volumesnapshot.md), if - supported by the underlying storage class - -Before selecting a backup strategy with {{name.ln}}, it's important to -familiarize yourself with the foundational concepts covered in the ["Main Concepts"](#main-concepts) -section. These include WAL archiving, hot and cold backups, performing backups -from a standby, and more. - -## Main Concepts - PostgreSQL natively provides first class backup and recovery capabilities based on file system level (physical) copy. These have been successfully used for more than 15 years in mission critical production databases, helping organizations all over the world achieve their disaster recovery goals with Postgres. -In {{name.ln}}, the backup infrastructure for each PostgreSQL cluster is made +!!!note + +There's another way to backup databases in PostgreSQL, through the +`pg_dump` utility - which relies on logical backups instead of physical ones. +However, logical backups are not suitable for business continuity use cases +and as such are not covered by {{name.ln}} (yet, at least). +If you want to use the `pg_dump` utility, let yourself be inspired by the +["Troubleshooting / Emergency backup" section](troubleshooting.md#emergency-backup). +!!! + +In EDB Postgres for Kubernetes, the backup infrastructure for each PostgreSQL cluster is made up of the following resources: - **WAL archive**: a location containing the WAL files (transactional logs) @@ -62,7 +33,35 @@ CNPG-I provides a generic and extensible interface for managing WAL archiving (both archive and restore operations), as well as the base backup and corresponding restore processes. -### WAL archive +On the other hand, EDB Postgres for Kubernetes supports two ways to store physical base backups: + +- on [object stores](backup_barmanobjectstore.md), as tarballs - optionally + compressed +- on [Kubernetes Volume Snapshots](backup_volumesnapshot.md), if supported by + the underlying storage class + +!!!info Important + +Before choosing your backup strategy with {{name.ln}}, it is important that +you take some time to familiarize with some basic concepts, like WAL archive, +hot and cold backups. +!!! + +!!!info Important + +Please refer to the official Kubernetes documentation for a list of all +the supported [Container Storage Interface (CSI) drivers](https://kubernetes-csi.github.io/docs/drivers.html) +that provide snapshotting capabilities. +!!! + +!!!info + +Starting with version 1.25, {{name.ln}} includes experimental support for +backup and recovery using plugins, such as the +[Barman Cloud plugin](https://github.com/cloudnative-pg/plugin-barman-cloud). +!!! + +## WAL archive The WAL archive in PostgreSQL is at the heart of **continuous backup**, and it is fundamental for the following reasons: @@ -74,6 +73,7 @@ is fundamental for the following reasons: time from the first available base backup in your system !!!warning + WAL archive alone is useless. Without a physical base backup, you cannot restore a PostgreSQL cluster. !!! @@ -92,9 +92,10 @@ out-of-the-box an [RPO](before_you_start.md#postgresql-terminology) ≤ 5 minute recovery, even across regions. !!!info Important + Our recommendation is to always setup the WAL archive in production. -There are known use cases — normally involving staging and development -environments — where none of the above benefits are needed and the WAL +There are known use cases - normally involving staging and development +environments - where none of the above benefits are needed and the WAL archive is not necessary. RPO in this case can be any value, such as 24 hours (daily backups) or infinite (no backup at all). !!! @@ -139,10 +140,17 @@ solutions to grow. Backups to an object store (e.g. AWS S3, Azure Blob, GCS): -- Always require WAL archiving -- Support hot backups only -- Do not support incremental or differential copies -- Support retention policies +- availability of a viable object store solution in your Kubernetes cluster +- availability of a trusted storage class that supports volume snapshots +- size of the database: with object stores, the larger your database, the + longer backup and, most importantly, recovery procedures take (the latter + impacts [RTO](before_you_start.md#postgresql-terminology)); in presence of Very Large Databases + (VLDB), the general advice is to rely on Volume Snapshots as, thanks to + copy-on-write, they provide faster recovery +- data mobility and possibility to store or relay backup files on a + secondary location in a different region, or any subsequent one +- other factors, mostly based on the confidence and familiarity with the + underlying storage solutions ### Volume Snapshots @@ -206,6 +214,7 @@ strategy in {{name.ln}}. They are defined using the `ScheduledBackup` custom resource. !!!info + For a complete list of configuration options, refer to the [`ScheduledBackupSpec`](pg4k.v1.md#scheduledbackupspec) in the API reference. @@ -213,9 +222,11 @@ in the API reference. ### Cron Schedule -The `schedule` field defines **when** the backup should occur, using a -*six-field cron expression* that includes seconds. This format follows the -[Go `cron` package specification](https://pkg.go.dev/github.com/robfig/cron#hdr-CRON_Expression_Format). +!!!warning + +Beware that this format accepts also the `seconds` field, and it is +different from the `crontab` format in Unix/Linux systems. +!!! !!!warning This format differs from the traditional Unix/Linux `crontab`—it includes a @@ -243,9 +254,26 @@ since seconds are not supported. ### Backup Frequency and RTO +!!!warning + +The `spec.cluster` field is immutable after creation. To schedule backups +for a different `Cluster`, create a new `ScheduledBackup` resource instead +of updating an existing one. +!!! + !!!tip Hint -The frequency of your backups directly impacts your **Recovery Time Objective** -([RTO](before_you_start.md#postgresql-terminology)). + +Backup frequency might impact your recovery time objective ([RTO](before_you_start.md#postgresql-terminology)) after a +disaster which requires a full or Point-In-Time recovery operation. Our +advice is that you regularly test your backups by recovering them, and then +measuring the time it takes to recover from scratch so that you can refine +your RTO predictability. Recovery time is influenced by the size of the +base backup and the amount of WAL files that need to be fetched from the archive +and replayed during recovery (remember that WAL archiving is what enables +continuous backup in PostgreSQL!). +Based on our experience, a weekly base backup is more than enough for most +cases - while it is extremely rare to schedule backups more frequently than once +a day. !!! To optimize your disaster recovery strategy based on continuous backup: @@ -258,16 +286,27 @@ To optimize your disaster recovery strategy based on continuous backup: In most cases, a **weekly base backup** is sufficient. It is rare to schedule full backups more frequently than once per day. -### Immediate Backup +!!!note + +`.spec.backupOwnerReference` indicates which ownerReference should be put inside +the created backup resources. -To trigger a backup immediately when the `ScheduledBackup` is created: +- *none:* no owner reference for created backup objects (same behavior as before the field was introduced) +- *self:* sets the Scheduled backup object as owner of the backup +- *cluster:* set the cluster as owner of the backup +!!! ```yaml spec: immediate: true ``` -### Pause Scheduled Backups +!!!info + +For a full list of available options, see the +[`BackupSpec`](pg4k.v1.md#backupspec) in the +API reference. +!!! To temporarily stop scheduled backups from running: @@ -361,7 +400,12 @@ Status: Stopped At: 2020-10-26T13:57:44Z ``` -* * * +!!!info Important + +This feature will not backup the secrets for the superuser and the +application user. The secrets are supposed to be backed up as part of +the standard backup procedures for the Kubernetes cluster. +!!! !!!info Important On-demand backups do **not** include Kubernetes secrets for the PostgreSQL @@ -387,10 +431,18 @@ Specify the method using the `.spec.method` field (defaults to If your cluster is configured to support volume snapshots, you can enable scheduled snapshot backups like this: -```yaml -spec: - method: volumeSnapshot -``` +!!!info + +Although the standby might not always be up to date with the primary, +in the time continuum from the first available backup to the last +archived WAL this is normally irrelevant. The base backup indeed +represents the starting point from which to begin a recovery operation, +including PITR. Similarly to what happens with +[`pg_basebackup`](https://www.postgresql.org/docs/current/app-pgbasebackup.html), +when backing up from an online standby we do not force a switch of the WAL on the +primary. This might produce unexpected results in the short term (before +`archive_timeout` kicks in) in deployments with low write activity. +!!! To use the Barman Cloud Plugin as the backup method, set `method: plugin` and configure the plugin accordingly. You can find an example in the @@ -455,10 +507,12 @@ spec: ``` !!!warning -Be cautious when using `primary` as the target for **cold backups using -volume snapshots**, as this will require shutting down the primary instance -temporarily—interrupting all write operations. The same caution applies to -single-instance clusters, even if you haven't explicitly set the target. + +Beware of setting the target to primary when performing a cold backup +with volume snapshots, as this will shut down the primary for +the time needed to take the snapshot, impacting write operations. +This also applies to taking a cold backup in a single-instance cluster, even +if you did not explicitly set the primary as the target. !!! ### Overriding the Cluster-Wide Target diff --git a/product_docs/docs/postgres_for_kubernetes/1/backup_barmanobjectstore.mdx b/product_docs/docs/postgres_for_kubernetes/1/backup_barmanobjectstore.mdx index 1aa167ba06..6ce72a2635 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/backup_barmanobjectstore.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/backup_barmanobjectstore.mdx @@ -5,15 +5,6 @@ originalFilePath: 'src/appendixes/backup_barmanobjectstore.md' -!!!warning -As of {{name.ln}} 1.26, **native Barman Cloud support is deprecated** in -favor of the **Barman Cloud Plugin**. This page has been moved to the appendix -for reference purposes. While the native integration remains functional for -now, we strongly recommend beginning a gradual migration to the plugin-based -interface after appropriate testing. For guidance, see -[Migrating from Built-in {{name.ln}} Backup](https://cloudnative-pg.io/plugin-barman-cloud/docs/migration/). -!!! - {{name.ln}} natively supports **online/hot backup** of PostgreSQL clusters through continuous physical backup and WAL archiving on an object store. This means that the database is always up (no downtime required) @@ -35,12 +26,14 @@ as it is composed of a community PostgreSQL image and the latest `barman-cli-cloud` package. !!!info Important + Always ensure that you are running the latest version of the operands in your system to take advantage of the improvements introduced in Barman cloud (as well as improve the security aspects of your cluster). !!! !!!warning Changes in Barman Cloud 3.16+ and Bucket Creation + Starting with Barman Cloud 3.16, most Barman Cloud commands no longer automatically create the target bucket, assuming it already exists. Only the `barman-cloud-check-wal-archive` command creates the bucket now. Whenever this @@ -139,7 +132,12 @@ that archival request will be just dismissed with a positive status. ## Retention policies -{{name.ln}} can manage the automated deletion of backup files from +!!!info Important + +Retention policies are not currently available on volume snapshots. +!!! + +EDB Postgres for Kubernetes can manage the automated deletion of backup files from the backup object store, using **retention policies** based on the recovery window. @@ -168,6 +166,7 @@ spec: ``` !!!note There's more ... + The **recovery window retention policy** is focused on the concept of *Point of Recoverability* (`PoR`), a moving point in time determined by `current time - recovery window`. The *first valid backup* is the first diff --git a/product_docs/docs/postgres_for_kubernetes/1/backup_volumesnapshot.mdx b/product_docs/docs/postgres_for_kubernetes/1/backup_volumesnapshot.mdx index aa7fcd36f4..03cffb48e0 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/backup_volumesnapshot.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/backup_volumesnapshot.mdx @@ -5,6 +5,16 @@ originalFilePath: 'src/appendixes/backup_volumesnapshot.md' +!!!warning + +As noted in the [backup document](backup.md), a cold snapshot explicitly +set to target the primary will result in the primary being fenced for +the duration of the backup, rendering the cluster read-only during that +For safety, in a cluster already containing fenced instances, a cold +snapshot is rejected. +!!! + + !!!info Important Please refer to the official Kubernetes documentation for a list of all the supported [Container Storage Interface (CSI) drivers](https://kubernetes-csi.github.io/docs/drivers.html) @@ -54,9 +64,10 @@ volumes of a given storage class, and managed as `VolumeSnapshot` and `VolumeSnapshotContent` resources. !!!info Important + It is your responsibility to verify with the third party vendor that volume snapshots are supported. {{name.ln}} only interacts -with the Kubernetes API on this matter, and we cannot support issues +with the Kubernetes API on this matter and we cannot support issues at the storage level for each specific CSI driver. !!! @@ -66,6 +77,7 @@ at the storage level for each specific CSI driver. Snapshot backups through the `backup.volumeSnapshot` stanza. !!!info + Please refer to [`VolumeSnapshotConfiguration`](pg4k.v1.md#volumesnapshotconfiguration) in the API reference for a full list of options. !!! @@ -105,8 +117,9 @@ As you can see, the `backup` section contains both the `volumeSnapshot` stanza `plugins` one (controlling the [WAL archive](wal_archiving.md)). !!!info -Once you have defined the `plugin`, you can decide to use -both volume snapshot and plugin backup strategies simultaneously + +Once you have defined the `barmanObjectStore`, you can decide to use +both volume snapshot and object store backup strategies simultaneously to take physical backups. !!! @@ -115,6 +128,7 @@ The `volumeSnapshot.className` option allows you to reference the default defined in your PostgreSQL cluster. !!!info + In case you are using a different storage class for `PGDATA` and WAL files, you can specify a separate `VolumeSnapshotClass` for that volume through the `walClassName` option (which defaults to @@ -142,6 +156,7 @@ By default, {{name.ln}} requests an online/hot backup on volume snapshots, using terminating the backup procedure !!!info Important + The default values are suitable for most production environments. Hot backups are consistent and can be used to perform snapshot recovery, as we ensure WAL retention from the start of the backup through a temporary @@ -248,6 +263,7 @@ In case a `VolumeSnapshot` is deleted, the `deletionPolicy` specified in the - if set to `Delete`, the `VolumeSnapshotContent` object is removed as well !!!warning + `VolumeSnapshotContent` objects do not keep all the information regarding the backup and the cluster they refer to (like the annotations and labels that are contained in the `VolumeSnapshot` object). Although possible, restoring @@ -358,6 +374,7 @@ EKS cluster on AWS using the `ebs-sc` storage class and the `csi-aws-vsc` volume snapshot class. !!!info Important + If you are interested in testing the example, please read ["Volume Snapshots" for the Amazon Elastic Block Store (EBS) CSI driver](https://github.com/kubernetes-sigs/aws-ebs-csi-driver/tree/master/examples/kubernetes/snapshot) for detailed instructions on the installation process for the storage class and the snapshot class. diff --git a/product_docs/docs/postgres_for_kubernetes/1/benchmarking.mdx b/product_docs/docs/postgres_for_kubernetes/1/benchmarking.mdx index 764e6d10f4..1131bb0190 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/benchmarking.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/benchmarking.mdx @@ -13,6 +13,7 @@ Benchmarking is focused on two aspects: - the **storage**, by relying on [fio](https://fio.readthedocs.io/en/latest/fio_doc.html) !!!info IMPORTANT + `pgbench` and `fio` must be run in a staging or pre-production environment. Do not use these plugins in a production environment, as it might have catastrophic consequences on your databases and the other @@ -38,6 +39,7 @@ kubectl cnp pgbench \ ``` !!!info IMPORTANT + Please refer to the [`pgbench` documentation](https://www.postgresql.org/docs/current/pgbench.html) for information about the specific options to be used in your jobs. !!! @@ -54,6 +56,7 @@ kubectl cnp pgbench \ ``` !!!note + This will generate a database with 100000000 records, taking approximately 13GB of space on disk. !!! @@ -133,6 +136,7 @@ Through the `--dry-run` flag you can generate the manifest of the job for later modification/execution. !!!note + The kubectl plugin command `fio` will create a deployment with predefined fio job values using a ConfigMap. If you want to provide custom job values, we recommend generating a manifest using the `--dry-run` flag and providing your diff --git a/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx b/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx index dd7335e222..2f93f9c698 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx @@ -6,6 +6,7 @@ originalFilePath: 'src/bootstrap.md' !!!note + When referring to "PostgreSQL cluster" in this section, the same concepts apply to both PostgreSQL and EDB Postgres Advanced Server, unless differently stated. @@ -26,6 +27,7 @@ For more detailed information about this feature, please refer to the ["Importing Postgres databases"](database_import.md) section. !!!info Important + Bootstrapping from an existing cluster enables the creation of a **replica cluster**—an independent PostgreSQL cluster that remains in continuous recovery, stays synchronized with the source cluster, and @@ -34,6 +36,7 @@ For more details, refer to the [Replica Cluster section](replica_cluster.md). !!! !!!warning + {{name.ln}} requires both the `postgres` user and database to always exist. Using the local Unix Domain Socket, it needs to connect as the `postgres` user to the `postgres` database via `peer` authentication in @@ -42,6 +45,7 @@ order to perform administrative tasks on the cluster. !!! !!!info + {{name.ln}} is gradually introducing support for [Kubernetes' native `VolumeSnapshot` API](https://github.com/cloudnative-pg/cloudnative-pg/issues/2081) for both incremental and differential copy in backup and recovery @@ -81,6 +85,7 @@ storage that the {{name.ln}} operator provides for `recovery`, please refer to the dedicated ["Recovery" section](recovery.md) for guidance on each method. !!!note API reference + Please refer to the ["API reference for the `bootstrap` section](pg4k.v1.md#bootstrapconfiguration) for more information. !!! @@ -102,6 +107,7 @@ The primary use cases include: backup. !!!info + Ongoing development will extend the functionality of `externalClusters` to accommodate additional use cases, such as logical replication and foreign servers in future releases. @@ -122,6 +128,7 @@ method or the `recovery` one. An external cluster needs to have: - the catalog of physical base backups for the Postgres cluster !!!note + A recovery object store is normally an AWS S3, Azure Blob Storage, or Google Cloud Storage source that is managed by Barman Cloud. !!! @@ -144,6 +151,7 @@ continuously fed from the source, either via streaming, via WAL shipping through the PostgreSQL's `restore_command`, or any of the two. !!!note API reference + Please refer to the ["API reference for the `externalClusters` section](pg4k.v1.md#externalcluster) for more information. !!! @@ -226,6 +234,7 @@ data. Applications should connect to the cluster with the user that owns the application database. !!!info Important + If you need to create additional users, please refer to ["Declarative database role management"](declarative_role_management.md). !!! @@ -247,6 +256,7 @@ The PostgreSQL data directory is initialized using the settings such as default locale configurations and data checksums. !!!warning + {{name.ln}} acts only as a direct proxy to `initdb` for locale-related options, due to the ongoing and significant enhancements in PostgreSQL's locale support. It is your responsibility to ensure that the correct options are @@ -323,6 +333,7 @@ walSegmentSize option in `initdb` (default: not set - defined by PostgreSQL as 16 megabytes). !!!note + The only two locale options that {{name.ln}} implements during the `initdb` bootstrap refer to the `LC_COLLATE` and `LC_TYPE` subcategories. The remaining locale subcategories can be configured directly in the PostgreSQL @@ -352,6 +363,7 @@ spec: ``` !!!warning + {{name.ln}} supports another way to customize the behavior of the `initdb` invocation, using the `options` subsection. However, given that there are options that can break the behavior of the operator (such as `--auth` or @@ -382,13 +394,26 @@ queries, executed in the following order: Objects in each list will be processed sequentially. !!!warning + Use the `postInit`, `postInitTemplate`, and `postInitApplication` options with extreme care, as queries are run as a superuser and can disrupt the entire cluster. An error in any of those queries will interrupt the bootstrap phase, leaving the cluster incomplete and requiring manual intervention. !!! +!!!note + +These queries run with the standard `"$user", public` `search_path`, even +though operator-issued connections otherwise pin a fixed `search_path` for +security reasons. +See [Schema resolution and `search_path` hardening](security.md#schema-resolution-and-search_path-hardening) +for details. +Schema-qualify object references if you need them to be independent of the +`search_path`. +!!! + !!!info Important + Ensure the existence of entries inside the ConfigMaps or Secrets specified in `postInitSQLRefs`, `postInitTemplateSQLRefs`, and `postInitApplicationSQLRefs`, otherwise the bootstrap will fail. Errors in any @@ -448,6 +473,7 @@ spec: ``` !!!note + Within SQL scripts, each SQL statement is executed in a single exec on the server according to the [PostgreSQL semantics](https://www.postgresql.org/docs/current/protocol-flow.html#PROTOCOL-FLOW-MULTI-STATEMENT). Comments can be included, but internal commands like `psql` cannot. @@ -494,12 +520,13 @@ The source cluster must be defined in the `externalClusters` section, identified by `name` (our recommendation is to use the same `name` of the origin cluster). !!!info Important + By default the `recovery` method strictly uses the `name` of the cluster in the `externalClusters` section to locate the main folder of the backup data within the object store, which is normally reserved -for the name of the server. Backup plugins provide ways to specify a -different one. For example, the Barman Cloud Plugin provides the [`serverName` parameter](https://cloudnative-pg.io/plugin-barman-cloud/docs/parameters/) -(by default assigned to the value of `name` in the external cluster definition). +for the name of the server. You can specify a different one with the +`barmanObjectStore.serverName` property (by default assigned to the +value of `name` in the external cluster definition). !!! ### Bootstrap from a backup (`recovery`) @@ -530,6 +557,7 @@ The primary use cases for this method include: Kubernetes clusters !!!info Important + Avoid using this method, based on physical replication, to migrate an existing PostgreSQL cluster outside of Kubernetes into {{name.ln}}, unless you are completely certain that all [requirements](#requirements) are met and @@ -541,6 +569,7 @@ way that seamlessly works with {{name.ln}}. !!! !!!warning + In its current implementation, this method clones the source PostgreSQL instance, thereby creating a *snapshot*. Once the cloning process has finished, the new cluster is immediately started. @@ -555,6 +584,7 @@ creating the `streaming_replica` user, managing replicas, and more. The resulting cluster operates independently from the source instance. !!!info Important + Configuring the network connection between the target and source instances lies outside the scope of {{name.ln}} documentation, as it depends heavily on the specific context and environment. @@ -588,6 +618,7 @@ The following requirements apply to the `pg_basebackup` bootstrap method: using a role with `REPLICATION LOGIN` privileges !!!note Seealso + For further information, please refer to the ["Planning" section for Warm Standby](https://www.postgresql.org/docs/current/warm-standby.html#STANDBY-PLANNING), the @@ -622,6 +653,7 @@ Enter the password at the prompt and save it for later, as you will need to add it to a secret in the target instance. !!!note + Although the name is not important, we will use `streaming_replica` for the sake of simplicity. Feel free to change it as you like, provided you adapt the instructions in the following sections. @@ -647,7 +679,7 @@ file on the source PostgreSQL instance: host replication streaming_replica all md5 ``` -The following manifest creates a new PostgreSQL 18.3 cluster, +The following manifest creates a new PostgreSQL 18.4 cluster, called `target-db`, using the `pg_basebackup` bootstrap method to clone an external PostgreSQL cluster defined as `source-db` (in the `externalClusters` array). As you can see, the `source-db` @@ -662,7 +694,7 @@ metadata: name: target-db spec: instances: 3 - imageName: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 + imageName: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 bootstrap: pg_basebackup: @@ -682,7 +714,7 @@ spec: ``` All the requirements must be met for the clone operation to work, including -the same PostgreSQL version (in our case 18.3). +the same PostgreSQL version (in our case 18.4). #### TLS certificate authentication @@ -694,11 +726,12 @@ The following example clones an existing PostgreSQL cluster (`cluster-example`) in the same Kubernetes cluster. !!!note + This example can be easily adapted to cover an instance that resides outside the Kubernetes cluster. !!! -The manifest defines a new PostgreSQL 18.3 cluster called `cluster-clone-tls`, +The manifest defines a new PostgreSQL 18.4 cluster called `cluster-clone-tls`, which is bootstrapped using the `pg_basebackup` method from the `cluster-example` external cluster. The host is identified by the read/write service in the same cluster, while the `streaming_replica` user is authenticated @@ -713,7 +746,7 @@ metadata: name: cluster-clone-tls spec: instances: 3 - imageName: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 + imageName: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 bootstrap: pg_basebackup: @@ -747,6 +780,7 @@ If the new cluster is created as a replica cluster (with replica mode enabled), database configuration will be skipped. !!!info Important + While the `Cluster` is in recovery mode, no changes to the database, including the catalog, are permitted. This restriction includes any role overrides, which are deferred until the `Cluster` transitions to primary. @@ -801,6 +835,7 @@ Note that this limitation applies only if the target cluster is not defined as a replica cluster. !!!info Important + Before you attempt a migration, you must test both the procedure and the applications. In particular, it is fundamental that you run the migration procedure as many times as needed to systematically measure the downtime of your diff --git a/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx b/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx index eaa65afcfc..cbffe83586 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx @@ -14,6 +14,7 @@ To set up a cluster, the operator requires: - A streaming replication client certificate generated by the client CA !!!note + You can find all the secrets used by the cluster and their expiration dates in the cluster's status. !!! @@ -33,6 +34,7 @@ You can also choose a hybrid approach, where only part of the certificates is generated outside CNP. !!!note + The operator and instances verify server certificates against the CA only, disregarding the DNS name. This approach is due to the typical absence of DNS names in user-provided certificates for the `-rw` service used for @@ -47,12 +49,14 @@ managed continuously by the operator, with automatic renewal 7 days before expiration (within a 90-day validity period). !!!info + You can adjust this default behavior by configuring the `CERTIFICATE_DURATION` and `EXPIRING_CHECK_THRESHOLD` environment variables. For detailed guidance, refer to the [Operator Configuration](operator_conf.md). !!! !!!info Important + Certificate renewal does not cause any downtime for the PostgreSQL server, as a simple reload operation is sufficient. However, any user-managed certificates not controlled by {{name.ln}} must be re-issued following the @@ -119,11 +123,13 @@ the following parameters: - `serverCASecret` – The name of a secret containing the `ca.crt` key. !!!note + The operator still creates and manages the two secrets related to client certificates. !!! !!!note + The operator and instances verify server certificates against the CA only, disregarding the DNS name. This approach is due to the typical absence of DNS names in user-provided certificates for the `-rw` service used for @@ -131,6 +137,7 @@ communication within the cluster. !!! !!!note + If you want ConfigMaps and secrets to be reloaded by instances, you can add a label with the key `k8s.enterprisedb.io/reload` to it. Otherwise you must reload the instances using the `kubectl cnp reload` subcommand. @@ -262,51 +269,24 @@ the following parameters: to use to verify client certificate. !!!note + The operator still creates and manages the two secrets related to server certificates. !!! !!!note + As the cluster isn't in control of the client CA secret key, you can no longer generate client certificates using `kubectl cnp certificate`. !!! !!!note + If you want ConfigMaps and secrets to be automatically reloaded by instances, you can add a label with the key `k8s.enterprisedb.io/reload` to it. Otherwise, you must reload the instances using the `kubectl cnp reload` subcommand. !!! -#### Customizing the `streaming_replica` client certificate - -In some environments, it may not be possible to generate a certificate with the -common name `streaming_replica` due to company policies or other security -concerns, such as a CA shared across multiple clusters. In such cases, the user -mapping feature can be used to allow authentication as the `streaming_replica` -user with certificates containing different common names. - -To configure this setup, add a `pg_ident.conf` entry for the predefined map -named `cnp_streaming_replica`. - -For example, to enable `streaming_replica` authentication using a certificate -with the common name `streaming-replica.cnp.svc.cluster.local`, add the -following to your cluster definition: - -```yaml -apiVersion: postgresql.k8s.enterprisedb.io/v1 -kind: Cluster -metadata: - name: cluster-example -spec: - postgresql: - pg_ident: - - cnp_streaming_replica streaming-replica.cnp.svc.cluster.local streaming_replica -``` - -For further details on how `pg_ident.conf` is managed by the operator, see the -["PostgreSQL Configuration" page](postgresql_conf.md#the-pg_ident-section) in -the documentation. - #### Cert-manager example This simple example shows how to use [cert-manager](https://cert-manager.io/) diff --git a/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/_category_.json b/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/_category_.json new file mode 100644 index 0000000000..0bb5a46834 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "CNCF Projects Integrations", + "position": 590, + "link": { + "type": "generated-index" + } +} diff --git a/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/cilium.mdx b/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/cilium.mdx index 3433f937ec..7a360c419d 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/cilium.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/cilium.mdx @@ -38,6 +38,7 @@ In the following examples, we demonstrate how Cilium can be used to secure a authorized Pods. !!!info Important + Before proceeding, ensure that the `cluster-example` Postgres cluster is up and running in your environment. !!! @@ -87,7 +88,7 @@ metadata: name: postgresql-operator-operator-access namespace: default spec: - description: "Allow {{name.ln}} operator access to any pod in the target namespace" + description: "Allow EDB Postgres for Kubernetes operator access to any pod in the target namespace" endpointSelector: {} ingress: - fromEndpoints: @@ -100,6 +101,7 @@ spec: ``` !!!info Important + The `postgresql-operator-system` namespace is the default namespace for the operator when using the YAML manifests. If the operator was installed using a different process (Helm, OLM, etc.), the namespace may be different. Make sure to adjust @@ -119,7 +121,7 @@ metadata: name: cnp-cluster-internal-access namespace: default spec: - description: "Allow {{name.ln}} operator access and connection between pods in the same namespace" + description: "Allow EDB Postgres for Kubernetes operator access and connection between pods in the same namespace" endpointSelector: {} ingress: - fromEndpoints: diff --git a/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/external-secrets.mdx b/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/external-secrets.mdx index 4012167c83..792d2900b5 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/external-secrets.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/cncf-projects/external-secrets.mdx @@ -47,6 +47,7 @@ every 24 hours in the `cluster-example` Postgres cluster from the [quickstart guide](../quickstart.md#part-3-deploy-a-postgresql-cluster). !!!info Important + Before proceeding, ensure that the `cluster-example` Postgres cluster is up and running in your environment. !!! @@ -54,7 +55,7 @@ and running in your environment. By default, {{name.ln}} generates and manages a Kubernetes `Secret` named `cluster-example-app`, which contains the credentials for the `app` user in the `cluster-example` cluster. You can read more about this in the -[“Connecting from an application” section](../applications.mdx#secrets). +[“Connecting from an application” section](../applications.md#secrets). With External Secrets, the goal is to: @@ -164,6 +165,7 @@ External Secrets Operator, and HashiCorp Vault to automatically rotate a PostgreSQL password and securely store it in Vault. !!!info Important + This example assumes that HashiCorp Vault is already installed and properly configured in your environment, and that your team has the necessary expertise to operate it. There are various ways to deploy Vault, and detailing them is @@ -214,6 +216,7 @@ data: This configuration creates a `SecretStore` resource named `vault-backend`. !!!info Important + This example uses basic token-based authentication, which is suitable for testing API, and CLI use cases. While it is the default method enabled in Vault, it is not recommended for production environments. For production, @@ -223,6 +226,7 @@ for a full list of supported authentication mechanisms. !!! !!!info + HashiCorp Vault must have a KV secrets engine enabled at the `secrets` path with version `v2`. If your Vault instance uses a different path or version, be sure to update the `path` and `version` fields accordingly. diff --git a/product_docs/docs/postgres_for_kubernetes/1/cnpg_i.mdx b/product_docs/docs/postgres_for_kubernetes/1/cnpg_i.mdx index f90cca9350..22171632a4 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/cnpg_i.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/cnpg_i.mdx @@ -92,6 +92,12 @@ TCP gRPC endpoint behind a Service, with **mTLS** for secure communication. Standalone plugins are discovered dynamically by watching for Services with the required labels and annotations — no operator restart is needed. +When a standalone plugin's pods are rolled (for example, after upgrading its +image), the operator detects the change through the EndpointSlices backing the +plugin Service and reconciles every cluster using that plugin, so they start +interacting with the new pods promptly instead of waiting for the periodic +resync. + Example Deployment: ```yaml @@ -163,6 +169,7 @@ spec: ``` !!!note + You can provide your own certificate bundles, but the recommended method is to use [Cert-manager](https://cert-manager.io). !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/connection_pooling.mdx b/product_docs/docs/postgres_for_kubernetes/1/connection_pooling.mdx index 6c9cdd3d46..fce7f1c424 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/connection_pooling.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/connection_pooling.mdx @@ -54,9 +54,17 @@ spec: ``` !!!info Important + The pooler name can't be the same as any cluster name in the same namespace. !!! +!!!warning + +The `spec.cluster` field is immutable after creation. To point a pooler at +a different `Cluster`, create a new `Pooler` resource instead of updating +an existing one. +!!! + This example creates a `Pooler` resource called `pooler-example-rw` that's strictly associated with the Postgres `Cluster` resource called `cluster-example`. It points to the primary, identified by the read/write @@ -70,6 +78,7 @@ and accepting up to 1000 connections each. The default pool size is 10 user/database pairs toward PostgreSQL. !!!info Important + The `Pooler` resource sets only the `*` fallback database in PgBouncer. This setting means that that all parameters in the connection strings passed from the client are relayed to the PostgreSQL server. For details, see ["Section \[databases\]" @@ -80,6 +89,7 @@ in the PgBouncer documentation](https://www.pgbouncer.org/config.html#section-da the configuration files used with PgBouncer. !!!note API reference + For details, see [`PgBouncerSpec`](pg4k.v1.md#pgbouncerspec) in the API reference. !!! @@ -94,17 +104,18 @@ The key point to understand is that the lifecycles of the `Cluster` and `Pooler` resources are independent. Deleting a cluster does not automatically remove its poolers, and deleting a pooler does not affect the cluster. -!!!info -Once you are familiar with how poolers work, you have complete flexibility -in designing your architecture. You can run clusters without poolers, clusters -with a single pooler, or clusters with multiple poolers (for example, one per -application). +!!!info Important + +Once you know how a pooler works, you have full freedom in terms of +possible architectures. You can have clusters without poolers, clusters with +a single pooler, or clusters with several poolers, that is, one per application. !!! !!!info Important -When the operator itself is upgraded, pooler pods will also undergo a -rolling upgrade. This ensures that the instance manager inside the pooler -pods is upgraded consistently. + +When the operator is upgraded, the pooler pods will undergo a rolling +upgrade. This is necessary to ensure that the instance manager within the +pooler pods is also upgraded. !!! ## Security @@ -170,7 +181,11 @@ The built-in integration performs the following tasks: - Cleans up all of the above automatically when no poolers are associated with the cluster -#### SQL instructions +!!!info Important + +If you specify your own secrets, the operator doesn't automatically +integrate the pooler. +!!! As part of the built-in integration, {{name.ln}} automatically executes a set of SQL statements during reconciliation. These statements are run by the @@ -188,14 +203,17 @@ Grant access to the `postgres` database: GRANT CONNECT ON DATABASE postgres TO cnp_pooler_pgbouncer; ``` -Create the lookup function for password verification. This function is created -in the `postgres` database with `SECURITY DEFINER` privileges and is used by -PgBouncer’s `auth_query` option: +Finally, as a *superuser* connect in each application database, and then create +the authentication function inside each of the application databases. Because it +runs as the function owner, its `search_path` is pinned to `pg_catalog, pg_temp` +so that the function body cannot resolve operators or objects through a caller- +or tenant-controlled `search_path`: ```sql CREATE OR REPLACE FUNCTION public.user_search(uname TEXT) RETURNS TABLE (usename name, passwd text) - LANGUAGE sql SECURITY DEFINER AS + LANGUAGE sql SECURITY DEFINER + SET search_path = pg_catalog, pg_temp AS 'SELECT usename, passwd FROM pg_catalog.pg_shadow WHERE usename=$1;'; ``` @@ -209,13 +227,20 @@ GRANT EXECUTE ON FUNCTION public.user_search(text) TO cnp_pooler_pgbouncer; ``` -### Custom authentication method +!!!note -Providing your own certificate secrets disables the built-in integration. +Clusters created with an earlier version of {{name.ln}} carry a +`user_search` function without the pinned `search_path`. The operator +recreates the function with the `SET search_path` clause automatically +during reconciliation when the cluster is upgraded. +!!! -This gives you the flexibility — and responsibility — to manage the -authentication process yourself. You can follow the instructions above to -replicate similar behavior to the default setup. +!!!info Important + +Given that `user_search` is a `SECURITY DEFINER` function, you need to +create it through a role with `SUPERUSER` privileges, such as the `postgres` +user. +!!! ## Pod templates @@ -353,6 +378,7 @@ The operator by default adds a `ServicePort` with the following data: ``` !!!warning + Specifying a `ServicePort` with the name `pgbouncer` or the port `5432` will prevent the default `ServicePort` from being added. This because `ServicePort` entries with the same `name` or `port` are not allowed on Kubernetes and result in errors. !!! @@ -367,10 +393,11 @@ using the `rw` service) or servers (if using the `ro` service with multiple replicas). !!!warning + If your infrastructure spans multiple availability zones with high latency across them, be aware of network hops. Consider, for example, the case of your application running in zone 2, connecting to PgBouncer running in zone 3, and -pointing to the PostgreSQL primary in zone 1. +pointing to the PostgreSQL primary in zone 1. !!! ## PgBouncer configuration options @@ -458,6 +485,7 @@ PgBouncer instance reloads the updated configuration without disrupting the service. !!!warning + Every PgBouncer pod has the same configuration, aligned with the parameters in the specification. A mistake in these parameters might disrupt the operability of the whole pooler. @@ -479,8 +507,9 @@ Like the {{name.ln}} instance, the exporter runs on port Go runtime (with the prefix `go_*`). !!!info + You can inspect the exported metrics on a pod running PgBouncer. For instructions, see -[How to inspect the exported metrics](monitoring.md#how-to-inspect-the-exported-metrics). +[How to inspect the exported metrics](monitoring#how-to-inspect-the-exported-metrics). Make sure that you use the correct IP and the `9127` port. !!! @@ -646,6 +675,7 @@ cnp_pgbouncer_stats_total_xact_time{database="pgbouncer"} 0 ``` !!!info + For a better understanding of the metrics please refer to the PgBouncer documentation. !!! @@ -671,6 +701,7 @@ spec: ### Deprecation of Automatic `PodMonitor` Creation !!!warning Feature Deprecation Notice + The `.spec.monitoring.enablePodMonitor` field in the `Pooler` resource is now deprecated and will be removed in a future version of the operator. !!! @@ -718,11 +749,13 @@ When the `paused` option is reset to `false`, the operator invokes the service defined in the `Pooler` resource. !!!note PAUSE + For more information, see [`PAUSE` in the PgBouncer documentation](https://www.pgbouncer.org/usage.html#pause-db). !!! !!!info Important + In future versions, the switchover operation will be fully integrated with the PgBouncer pooler and take advantage of the `PAUSE`/`RESUME` features to reduce the perceived downtime by client applications. @@ -750,6 +783,7 @@ the specific use case for the single PostgreSQL cluster, the adopted criteria is to explicitly list the options that can be configured by users. !!!note + The adopted solution likely addresses the majority of use cases. It leaves room for the future implementation of a separate operator for PgBouncer to complete the gamma with more advanced and customized diff --git a/product_docs/docs/postgres_for_kubernetes/1/container_images.mdx b/product_docs/docs/postgres_for_kubernetes/1/container_images.mdx index 9b952921b5..960bcd8a32 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/container_images.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/container_images.mdx @@ -5,6 +5,11 @@ originalFilePath: 'src/container_images.md' +The {{name.ln}} operator for Kubernetes is designed to +work with any compatible container image of PostgreSQL that complies +with the following requirements: + + The {{name.ln}} operator for Kubernetes is designed to work with any compatible PostgreSQL container image that meets the following requirements: @@ -16,27 +21,20 @@ compatible PostgreSQL container image that meets the following requirements: - `pg_basebackup` - Proper locale settings configured -Optional Components: - -- [PGAudit](https://www.pgaudit.org/) extension (only required if audit logging - is needed) -- `du` (used for `kubectl cnp status`) - !!!info Important -Only [PostgreSQL versions officially supported by PGDG](https://postgresql.org/) are allowed. -!!! -!!!info -Barman Cloud executables are no longer required in {{name.ln}}. The -recommended approach is to use the dedicated [Barman Cloud Plugin](https://github.com/cloudnative-pg/plugin-barman-cloud). +Only [PostgreSQL versions supported by the PGDG](https://postgresql.org/) are allowed. !!! -No entry point or command is required in the image definition. {{name.ln}} -automatically overrides it with its instance manager. +- [PGAudit](https://www.pgaudit.org/) extension (only required if audit logging + is needed) +- `du` (used for `kubectl cnp status`) !!!warning -{{name.ln}} only supports **Primary with multiple/optional Hot Standby -Servers architecture** for PostgreSQL application container images. + +Application Container Images will be used by {{name.ln}} +in a **Primary with multiple/optional Hot Standby Servers Architecture** +only. !!! ## Image Tag Requirements @@ -65,9 +63,11 @@ Examples of accepted image tags: - `16.0` !!!warning + `latest` is not considered a valid tag for the image. !!! !!!note + Image tag requirements do not apply for images defined in a catalog. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/database_import.mdx b/product_docs/docs/postgres_for_kubernetes/1/database_import.mdx index 9c8c91b064..8b5e6ea2cc 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/database_import.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/database_import.mdx @@ -22,10 +22,11 @@ As a result, the instructions in this section are suitable for both: - importing one or more databases from an existing PostgreSQL instance, even outside Kubernetes - importing the database from any PostgreSQL version to one that is either the - same or newer, enabling *major upgrades* of PostgreSQL (e.g. from version 13.x - to version 17.x) + same or newer, enabling *major upgrades* of PostgreSQL (e.g. from version 14.x + to version 18.x) !!!warning + When performing major upgrades of PostgreSQL you are responsible for making sure that applications are compatible with the new version and that the upgrade path of the objects contained in the database (including extensions) is @@ -36,6 +37,7 @@ In both cases, the operation is performed on a consistent **snapshot** of the origin database. !!!info Important + For this reason we suggest to stop write operations on the source before the final import in the `Cluster` resource, as changes done to the source database after the start of the backup will not be in the destination cluster - @@ -66,6 +68,7 @@ The first import method is available via the `microservice` type, the second via the `monolith` type. !!!warning + It is your responsibility to ensure that the destination cluster can access the source cluster with a superuser or a user having enough privileges to take a logical backup with `pg_dump`. Please refer to the @@ -136,6 +139,7 @@ spec: ``` !!!warning + The example above deliberately uses a source database running a version of PostgreSQL that is not supported anymore by the Community, and consequently by {{name.ln}}. @@ -167,6 +171,7 @@ There are a few things you need to be aware of when using the `microservice` typ - Roles are not imported - and as such they cannot be specified inside `initdb.import.roles` !!!tip Hint + The microservice approach adheres to {{name.ln}} conventions and defaults for the destination cluster. If you do not set `initdb.database` or `initdb.owner` for the destination cluster, both parameters will default to @@ -263,6 +268,7 @@ There are a few things you need to be aware of when using the `monolith` type: - The `postImportApplicationSQL` field is not supported !!!tip Hint + The databases and their owners are preserved exactly as they exist in the source cluster—no `app` database or user will be created during import. If your `bootstrap.initdb` stanza specifies custom `database` and `owner` values that @@ -390,6 +396,7 @@ configuration, then runs `initdb --sync-only` to ensure that data is permanently written on disk. !!!info Important + WAL archiving, if requested, and WAL level will be honored after the database import process has completed. Similarly, replicas will be cloned after the bootstrap phase, when the actual cluster resource starts. @@ -424,62 +431,13 @@ bootstrap: - '--jobs=2' ``` -### Stage-Specific `pg_restore` options - -For more granular control over the import process, {{name.ln}} supports -stage-specific `pg_restore` options for the following phases: - -- `pre-data` – e.g., schema definitions -- `data` – e.g., table contents -- `post-data` – e.g., indexes, constraints and triggers - -By specifying options for each phase, you can optimize parallelism and apply -flags tailored to the nature of the objects being restored. - -```yaml -bootstrap: - initdb: - import: - type: microservice - schemaOnly: false - databases: - - mynewdb - source: - externalCluster: sourcedb-external - pgRestorePredataOptions: - - '--jobs=1' - pgRestoreDataOptions: - - '--jobs=4' - pgRestorePostdataOptions: - - '--jobs=2' -``` - -In the example above: - -- `--jobs=1` is applied to the `pre-data` stage to preserve the ordering of - schema creation. -- `--jobs=4` increases parallelism during the `data` stage, speeding up large - data imports. -- `--jobs=2` balances performance and dependency handling in the `post-data` - stage. - -These stage-specific settings are particularly valuable for large databases or -resource-sensitive environments where tuning concurrency can significantly -improve performance. - -!!!note -When provided, stage-specific options take precedence over the general -`pgRestoreExtraOptions`. -!!! - !!!warning -The `pgDumpExtraOptions`, `pgRestoreExtraOptions`, and all stage-specific -restore options (`pgRestorePredataOptions`, `pgRestoreDataOptions`, -`pgRestorePostdataOptions`) are passed directly to the underlying PostgreSQL -tools without validation by the operator. Certain flags may conflict with the -operator’s intended functionality or design. Use these options with caution -and always test them thoroughly in a safe, controlled environment before -applying them in production. + +Use the `pgDumpExtraOptions` and `pgRestoreExtraOptions` fields with +caution and at your own risk. These options are not validated or verified by +the operator, and some configurations may conflict with its intended +functionality or behavior. Always test thoroughly in a safe and controlled +environment before applying them in production. !!! ## Online Import and Upgrades diff --git a/product_docs/docs/postgres_for_kubernetes/1/declarative_database_management.mdx b/product_docs/docs/postgres_for_kubernetes/1/declarative_database_management.mdx index eef8fc3f08..4fda5d7fb6 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/declarative_database_management.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/declarative_database_management.mdx @@ -23,10 +23,11 @@ automated, and consistent approach to managing PostgreSQL databases. ### Scope of Management !!!info Important -{{name.ln}} manages **global objects** in PostgreSQL clusters, including -databases, roles, and tablespaces. However, it does **not** manage database content -beyond extensions and schemas (e.g., tables). To manage database content, use specialized -tools or rely on the applications themselves. + +{{name.ln}} manages **global objects** in PostgreSQL clusters, such as +databases, roles, and tablespaces. However, it does **not** manage the content +of databases (e.g., schemas and tables). For database content, specialized +tools or the applications themselves should be used. !!! ### Declarative `Database` Manifest @@ -54,6 +55,7 @@ When applied, this manifest creates a `Database` object called role, in the `cluster-example` PostgreSQL cluster. !!!info + Please refer to the [API reference](pg4k.v1.md#databasespec) the full list of attributes you can define for each `Database` object. !!! @@ -69,7 +71,15 @@ The `Database` object must reference a specific `Cluster`, determining where the database will be created. It is managed by the cluster's primary instance, ensuring the database is created or updated as needed. +!!!warning + +The `spec.cluster` field is immutable after creation. To target a +different `Cluster`, create a new `Database` resource instead of updating +an existing one. +!!! + !!!info + The distinction between `metadata.name` and `spec.name` allows multiple `Database` resources to reference databases with the same name across different {{name.ln}} clusters in the same Kubernetes namespace. @@ -82,6 +92,7 @@ PostgreSQL automatically creates databases such as `postgres`, `template0`, and objects in {{name.ln}}. !!!info Important + Creating a `Database` with `spec.name` set to `postgres`, `template0`, or `template1` is not allowed. !!! @@ -148,6 +159,11 @@ spec: Deleting this `Database` object will automatically remove the `two` database from the `cluster-example` cluster. +On a replica cluster the database is read-only, so deleting a `Database` object +releases its finalizer and removes the Kubernetes object without dropping the +PostgreSQL database, even with `databaseReclaimPolicy: delete`. Dropping the +database is left to the primary cluster, which owns it. + ### Declaratively Setting `ensure: absent` To remove a database, set the `ensure` field to `absent` like in the following @@ -435,6 +451,7 @@ Postgres commands: in particular, the options accepted by `ALTER` are a subset of those accepted by `CREATE`. !!!warning + Some fields, such as encoding and collation settings, are immutable in PostgreSQL. Attempts to modify these fields on existing databases will be ignored. diff --git a/product_docs/docs/postgres_for_kubernetes/1/declarative_hibernation.mdx b/product_docs/docs/postgres_for_kubernetes/1/declarative_hibernation.mdx index 49e9ce75f4..d862a66e15 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/declarative_hibernation.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/declarative_hibernation.mdx @@ -17,6 +17,16 @@ process is running. The declarative hibernation feature enables saving CPU power by removing the database Pods, while keeping the database PVCs. +!!!note + +Declarative hibernation is different from the existing implementation +of [imperative hibernation via the `cnp` plugin](kubectl-plugin.md#cluster-hibernation). +Imperative hibernation shuts down all Postgres instances in the High +Availability cluster, and keeps a static copy of the PVCs of the primary that +contain `PGDATA` and WALs. The plugin enables to exit the hibernation phase, by +resuming the primary and then recreating all the replicas - if they exist. +!!! + ## Hibernation To hibernate a cluster, set the `k8s.enterprisedb.io/hibernation=on` annotation: @@ -55,7 +65,7 @@ $ kubectl cnp status Cluster Summary Name: cluster-example Namespace: default -PostgreSQL Image: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 +PostgreSQL Image: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 Primary instance: cluster-example-2 Status: Cluster in healthy state Instances: 3 diff --git a/product_docs/docs/postgres_for_kubernetes/1/declarative_role_management.mdx b/product_docs/docs/postgres_for_kubernetes/1/declarative_role_management.mdx index f4a04abeb3..57fe84f094 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/declarative_role_management.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/declarative_role_management.mdx @@ -155,6 +155,7 @@ never expires, mirroring the behavior of PostgreSQL. Specifically: allowing `VALID UNTIL NULL` in the `ALTER ROLE` SQL statement) !!!warning + New roles created without `passwordSecret` will have a `NULL` password inside PostgreSQL. !!! @@ -177,23 +178,77 @@ stringData: password: SCRAM-SHA-256$:$: ``` +!!!warning + +The example above uses `stringData:`, where Kubernetes encodes the value +for you, which is the safest path for pre-hashed passwords. If you must +use `data:`, encode the bytes exactly with `printf '%s' "$hash" | base64` +(or `echo -n "$hash" | base64`). A trailing newline from a naive +`echo "$hash" | base64` makes the value miss the SCRAM/MD5 shadow-format +check, so the operator falls back to treating it as cleartext and +re-hashes it, and login stops working. +!!! + ### Safety when transmitting cleartext passwords -While role passwords are safely managed in Kubernetes using Secrets, -there is still a risk on the PostgreSQL side. If creating/altering a role with -password, PostgreSQL may print the password as part of the query statement -in some `postgres` logs, as mentioned in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createrole.html): +Role passwords are safely managed in Kubernetes using Secrets, but the +SQL path between the operator and PostgreSQL is also a concern. As noted +in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createrole.html): > The password will be transmitted to the server in cleartext, and it might > also be logged in the client's command history or the server log -{{name.ln}} adds a safety layer by temporarily suppressing both statement -logging (`log_statement`) and error statement logging -(`log_min_error_statement`) for any CREATE or ALTER operation on a role with -password, thus preventing leakage in both success and failure scenarios. +{{name.ln}} protects this path in two complementary ways: + +1. Before emitting `CREATE`/`ALTER ROLE ... PASSWORD '...'`, the operator + SCRAM-SHA-256 encodes any cleartext password operator-side (client-side + from PostgreSQL's point of view). This is the standard PostgreSQL + practice for keeping cleartext out of server logs and extensions like + `pg_stat_statements` or `pgaudit`, and is the same encoding that + `psql \password` and libpq's `PQencryptPasswordConn` perform. The + literal PostgreSQL receives is the SCRAM-SHA-256 verifier stored in + `pg_authid.rolpassword`. Passwords already provided in MD5 or + SCRAM-SHA-256 shadow form are forwarded unchanged. +2. The same `CREATE`/`ALTER ROLE` statements are executed inside a + transaction that temporarily suppresses both statement logging + (`log_statement`) and error statement logging + (`log_min_error_statement`), preventing leakage to the PostgreSQL log + in both success and failure scenarios. + The Status section of the cluster does not print the query statement for any managed role operation. +#### Opting out of operator-side encoding + +If you need PostgreSQL (not the operator) to decide how the password is +hashed (for example, on a cluster running `password_encryption = md5`), +set the annotation `k8s.enterprisedb.io/passwordPassthrough: "enabled"` on the +basic-auth Secret. The operator will then forward the password value +verbatim. + +!!!warning + +The `k8s.enterprisedb.io/passwordPassthrough` annotation must be set on the +**basic-auth Secret** itself, not on the `Cluster` resource. Placing it +on the `Cluster` has no effect, and the operator will continue to apply +SCRAM-SHA-256 encoding to the password before sending it to PostgreSQL. +!!! + +The opt-in is per-Secret and applies to every basic-auth Secret the +operator consumes (managed-role secrets, but also the superuser and +application-user secrets), so a single cluster can mix passthrough +secrets and operator-encoded secrets freely. The statement-logging +suppression layer described above still applies in both modes. + +!!!warning + +With `k8s.enterprisedb.io/passwordPassthrough: "enabled"`, the operator forwards +the Secret's `password` value verbatim. If that value is cleartext (the +common case on a `password_encryption = md5` cluster), extensions such +as `pg_stat_statements` or `pgaudit` will observe it. This is the +expected trade-off for letting PostgreSQL choose the hash format. +!!! + ## Unrealizable role configurations In PostgreSQL, in some cases, commands cannot be honored by the database and @@ -270,6 +325,7 @@ petrarca could not perform UPDATE_MEMBERSHIPS on role petrarca: role "poets" do ``` !!!info Important + In terms of backward compatibility, declarative role management is designed to ignore roles that exist in the database but are not included in the spec. The lifecycle of these roles will continue to be managed within PostgreSQL, diff --git a/product_docs/docs/postgres_for_kubernetes/1/failover.mdx b/product_docs/docs/postgres_for_kubernetes/1/failover.mdx index e0e1e4f43e..1f949b91cc 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/failover.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/failover.mdx @@ -29,6 +29,7 @@ controller will initiate the failover process, in two steps: the primary, and become a replica node. !!!info Important + The two-phase procedure helps ensure the WAL receivers can stop in an orderly fashion, and that the failing primary will not start streaming WALs again upon restart. These safeguards prevent timeline discrepancies between the new primary @@ -44,6 +45,7 @@ During the time the failing primary is being shut down: *immediate shutdown* is initiated. !!!info + "Fast" mode does not wait for PostgreSQL clients to disconnect and will terminate an online backup in progress. All active transactions are rolled back and clients are forcibly disconnected, then the server is shut down. @@ -69,6 +71,7 @@ and/or data being lost ([RPO](before_you_start.md#postgresql-terminology)): with no data loss. !!!note + The timeout that controls fast shutdown is set by `.spec.switchoverDelay`, as in the case of a switchover. Increasing the time for fast shutdown is safer from an RPO point of view, but possibly delays the return to normal operation - @@ -76,6 +79,7 @@ negatively affecting RTO. !!! !!!warning + As already mentioned in the ["Instance Manager" section](instance_manager.md) when explaining the switchover process, the `.spec.switchoverDelay` option affects the RPO and RTO of your PostgreSQL database. Setting it to a low value, @@ -143,297 +147,3 @@ the rest of the cluster, and the kubelet kills the container within approximately three probe periods (`~30s`). Full high availability (recreation of the old primary on a healthy node by the operator) is still gated on the taint-based eviction actually deleting the pod. - -## Failover Quorum (Quorum-based Failover) - -Failover quorum is a mechanism that enhances data durability and safety during -failover events in {{name.ln}}-managed PostgreSQL clusters. - -Quorum-based failover allows the controller to determine whether to promote a replica -to primary based on the state of a quorum of replicas. -This is useful when stronger data durability is required than the one offered -by [synchronous replication](replication.md#synchronous-replication) and -default automated failover procedures. - -When synchronous replication is not enabled, some data loss is expected and -accepted during failover, as a replica may lag behind the primary when -promoted. - -With synchronous replication enabled, the guarantee is that the application -will not receive explicit acknowledgment of the successful commit of a -transaction until the WAL data is known to be safely received by all required -synchronous standbys. -This is not enough to guarantee that the operator is able to promote the most -advanced replica. - -For example, in a three-node cluster with synchronous replication set to `ANY 1 -(...)`, data is written to the primary and one standby before a commit is -acknowledged. If both the primary and the aligned standby become unavailable -(such as during a network partition), the remaining replica may not have the -latest data. Promoting it could lose some data that the application considered -committed. - -Quorum-based failover addresses this risk by ensuring that failover only occurs -if the operator can confirm the presence of all synchronously committed data in -the instance to promote, and it does not occur otherwise. - -This feature allows users to choose their preferred trade-off between data -durability and data availability. - -Failover quorum can be enabled by setting the -`.spec.postgresql.synchronous.failoverQuorum` field to `true`: - -```yaml -apiVersion: postgresql.k8s.enterprisedb.io/v1 -kind: Cluster -metadata: - name: cluster-example -spec: - instances: 3 - - postgresql: - synchronous: - method: any - number: 1 - failoverQuorum: true - - storage: - size: 1Gi -``` - -For backward compatibility, the legacy annotation -`alpha.k8s.enterprisedb.io/failoverQuorum` is still supported by the admission webhook and -takes precedence over the `Cluster` spec option: - -- If the annotation evaluates to `"true"` and a synchronous replication stanza - is present, the webhook automatically sets - `.spec.postgresql.synchronous.failoverQuorum` to `true`. -- If the annotation evaluates to `"false"`, the feature is always disabled - -!!!info Important -Because the annotation overrides the spec, we recommend that users of this -experimental feature migrate to the native -`.spec.postgresql.synchronous.failoverQuorum` option and remove the annotation -from their manifests. The annotation is **deprecated** and will be removed in a -future release. -!!! - -### How it works - -Before promoting a replica to primary, the operator performs a quorum check, -following the principles of the Dynamo `R + W > N` consistency model[^1]. - -In the quorum failover, these values assume the following meaning: - -- `R` is the number of *promotable replicas* (read quorum); -- `W` is the number of replicas that must acknowledge the write before the - `COMMIT` is returned to the client (write quorum); -- `N` is the total number of potentially synchronous replicas; - -*Promotable replicas* are replicas that have these properties: - -- are part of the cluster; -- are able to report their state to the operator; -- are potentially synchronous; - -If `R + W > N`, then we can be sure that among the promotable replicas there is -at least one that has confirmed all the synchronous commits, and we can safely -promote it to primary. If this is not the case, the controller will not promote -any replica to primary, and will wait for the situation to change. - -Users can force a promotion of a replica to primary through the -`kubectl cnp promote` command even if the quorum check is failing. - -!!!warning -Manual promotion should only be used as a last resort. Before proceeding, -make sure you fully understand the risk of data loss and carefully consider the -consequences of prioritizing the resumption of write workloads for your -applications. -!!! - -An additional CRD is used to track the quorum state of the cluster. A `Cluster` -with the quorum failover enabled will have a `FailoverQuorum` resource with the same -name as the `Cluster` resource. The `FailoverQuorum` CR is created by the -controller when the quorum failover is enabled, and it is updated by the primary -instance during its reconciliation loop, and read by the operator during quorum -checks. It is used to track the latest known configuration of the synchronous -replication. - -!!!info Important -Users should not modify the `FailoverQuorum` resource directly. During -PostgreSQL configuration changes, when it is not possible to determine the -configuration, the `FailoverQuorum` resource will be reset, preventing any -failover until the new configuration is applied. -!!! - -The `FailoverQuorum` resource works in conjunction with PostgreSQL synchronous -replication. - -!!!warning -There is no guarantee that `COMMIT` operations returned to the -client but that have not been performed synchronously, such as those made -explicitly disabling synchronous replication with -`SET synchronous_commit TO local`, will be present on a promoted replica. -!!! - -### Quorum Failover Example Scenarios - -In the following scenarios, `R` is the number of promotable replicas, `W` is -the number of replicas that must acknowledge a write before commit, and `N` is -the total number of potentially synchronous replicas. The "Failover" column -indicates whether failover is allowed under quorum failover rules. - -#### Scenario 1: Three-node cluster, failing pod(s) - -A cluster with `instances: 3`, `synchronous.number=1`, and -`dataDurability=required`. - -- If only the primary fails, two promotable replicas remain (R=2). - Since `R + W > N` (2 + 1 > 2), failover is allowed and safe. -- If both the primary and one replica fail, only one promotable replica - remains (R=1). Since `R + W = N` (1 + 1 = 2), failover is not allowed to - prevent possible data loss. - -| R | W | N | Failover | -| :-: | :-: | :-: | :------: | -| 2 | 1 | 2 | ✅ | -| 1 | 1 | 2 | ❌ | - -#### Scenario 2: Three-node cluster, network partition - -A cluster with `instances: 3`, `synchronous.number: 1`, and -`dataDurability: required` experiences a network partition. - -- If the operator can communicate with the primary, no failover occurs. The - cluster can be impacted if the primary cannot reach any standby, since it - won't commit transactions due to synchronous replication requirements. -- If the operator cannot reach the primary but can reach both replicas (R=2), - failover is allowed. If the operator can reach only one replica (R=1), - failover is not allowed, as the synchronous one may be the other one. - -| R | W | N | Failover | -| :-: | :-: | :-: | :------: | -| 2 | 1 | 2 | ✅ | -| 1 | 1 | 2 | ❌ | - -#### Scenario 3: Five-node cluster, network partition - -A cluster with `instances: 5`, `synchronous.number=2`, and -`dataDurability=required` experiences a network partition. - -- If the operator can communicate with the primary, no failover occurs. The - cluster can be impacted if the primary cannot reach at least two standbys, - as since it won't commit transactions due to synchronous replication - requirements. -- If the operator cannot reach the primary but can reach at least three - replicas (R=3), failover is allowed. If the operator can reach only two - replicas (R=2), failover is not allowed, as the synchronous one may be the - other one. - -| R | W | N | Failover | -| :-: | :-: | :-: | :------: | -| 3 | 2 | 4 | ✅ | -| 2 | 2 | 4 | ❌ | - -#### Scenario 4: Three-node cluster with remote synchronous replicas - -A cluster with `instances: 3` and remote synchronous replicas defined in -`standbyNamesPre` or `standbyNamesPost`. We assume that the primary is failing. - -This scenario requires an important consideration. Replicas listed in -`standbyNamesPre` or `standbyNamesPost` are not counted in -`R` (they cannot be promoted), but are included in `N` (they may have received -synchronous writes). So, if -`synchronous.number <= len(standbyNamesPre) + len(standbyNamesPost)`, failover -is not possible, as no local replica can be guaranteed to have the required -data. The operator prevents such configurations during validation, but some -invalid configurations are shown below for clarity. - -**Example configurations:** - -Configuration #1 (valid): - -```yaml -instances: 3 -postgresql: - synchronous: - method: any - number: 2 - standbyNamesPre: - - angus -``` - -In this configuration, when the primary fails, `R = 2` (the local replicas), -`W = 2`, and `N = 3` (2 local replicas + 1 remote), allowing failover. -In case of an additional replica failing (`R = 1`) failover is not allowed. - -| R | W | N | Failover | -| :-: | :-: | :-: | :------: | -| 3 | 2 | 4 | ✅ | -| 2 | 2 | 4 | ❌ | - -Configuration #2 (invalid): - -```yaml -instances: 3 -postgresql: - synchronous: - method: any - number: 1 - maxStandbyNamesFromCluster: 1 - standbyNamesPre: - - angus -``` - -In this configuration, `R = 2` (the local replicas), `W = 1`, and `N = 3` -(2 local replicas + 1 remote). -Failover is not possible in this setup, so quorum failover can not be -enabled with this configuration. - -| R | W | N | Failover | -| :-: | :-: | :-: | :------: | -| 1 | 1 | 2 | ❌ | - -Configuration #3 (invalid): - -```yaml -instances: 3 -postgresql: - synchronous: - method: any - number: 1 - maxStandbyNamesFromCluster: 0 - standbyNamesPre: - - angus - - malcolm -``` - -In this configuration, `R = 0` (the local replicas), `W = 1`, and `N = 2` -(0 local replicas + 2 remote). -Failover is not possible in this setup, so quorum failover can not be -enabled with this configuration. - -| R | W | N | Failover | -| :-: | :-: | :-: | :------: | -| 0 | 1 | 2 | ❌ | - -#### Scenario 5: Three-node cluster, preferred data durability, network partition - -Consider a cluster with `instances: 3`, `synchronous.number=1`, and -`dataDurability=preferred` that experiences a network partition. - -- If the operator can communicate with both the primary and the API server, - the primary continues to operate, removing unreachable standbys from the - `synchronous_standby_names` set. -- If the primary cannot reach the operator or API server, a quorum check is - performed. The `FailoverQuorum` status cannot have changed, as the primary cannot - have received new configuration. If the operator can reach both replicas, - failover is allowed (`R=2`). If only one replica is reachable (`R=1`), - failover is not allowed. - -| R | W | N | Failover | -| :-: | :-: | :-: | :------: | -| 2 | 1 | 2 | ✅ | -| 1 | 1 | 2 | ❌ | - -[^1]: [Dynamo: Amazon’s highly available key-value store](https://www.amazon.science/publications/dynamo-amazons-highly-available-key-value-store) diff --git a/product_docs/docs/postgres_for_kubernetes/1/failure_modes.mdx b/product_docs/docs/postgres_for_kubernetes/1/failure_modes.mdx index 0318b4a2b4..82120e87d3 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/failure_modes.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/failure_modes.mdx @@ -5,6 +5,15 @@ originalFilePath: 'src/failure_modes.md' +!!!note + +In previous versions of {{name.ln}}, this page included specific failure +scenarios. Since these largely follow standard Kubernetes behavior, we have +streamlined the content to avoid duplication of information that belongs to the +underlying Kubernetes stack and is not specific to {{name.ln}}. +!!! + + !!!note In previous versions of {{name.ln}}, this page included specific failure scenarios. Since these largely follow standard Kubernetes behavior, we have @@ -20,6 +29,7 @@ covers startup, liveness, and readiness probes, as well as the [self-healing](#self-healing) section below. !!!info Important + If you are running {{name.ln}} in production, we strongly recommend seeking [professional support](https://cloudnative-pg.io/support/). !!! @@ -53,6 +63,7 @@ For failure scenarios not covered by automated recovery, manual intervention may be required. !!!info Important + Do not perform manual operations without [professional support](https://cloudnative-pg.io/support/). !!! @@ -88,3 +99,13 @@ metadata: spec: # ... ``` + +Use this annotation **with extreme caution** and only during emergency +operations. + +!!!warning + +This annotation should be removed as soon as the issue is resolved. Leaving +it in place prevents the operator from executing self-healing actions, +including failover. +!!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/faq.mdx b/product_docs/docs/postgres_for_kubernetes/1/faq.mdx index ceeb996cf0..bf054edc32 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/faq.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/faq.mdx @@ -155,6 +155,7 @@ publication on GitHub: Feel free to report any relevant missing entry as a PR. !!!info + The [Data on Kubernetes Community](https://dok.community) (which includes some of our maintainers) is working on an independent and vendor neutral project to list the operators called diff --git a/product_docs/docs/postgres_for_kubernetes/1/fencing.mdx b/product_docs/docs/postgres_for_kubernetes/1/fencing.mdx index d8c695dc00..9c00ab6bda 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/fencing.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/fencing.mdx @@ -99,6 +99,7 @@ This consists of an initial fast shutdown with a timeout set to set to 1 !!!warning + If a **primary instance** is fenced, its postmaster process is shut down but no failover is performed, interrupting the operativity of the applications. When the fence will be lifted, the primary instance will be diff --git a/product_docs/docs/postgres_for_kubernetes/1/image_catalog.mdx b/product_docs/docs/postgres_for_kubernetes/1/image_catalog.mdx index b6a47175de..b585807f43 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/image_catalog.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/image_catalog.mdx @@ -5,15 +5,23 @@ originalFilePath: 'src/image_catalog.md' +`ImageCatalog` and `ClusterImageCatalog` are essential resources that empower +you to define images for creating a `Cluster`. + + `ImageCatalog` and `ClusterImageCatalog` are Custom Resource Definitions (CRDs) that allow you to decouple the PostgreSQL image lifecycle from the `Cluster` definition. By using a catalog, you can manage image updates centrally; when a catalog entry is updated, all associated clusters automatically [roll out the new image](rolling_update.md). -While you can build custom catalogs, {{name.ln}} provides -[official catalogs](#edb-cloudnativepg-cluster-catalogs) as `ClusterImageCatalog` -resources, covering all official Community PostgreSQL container images. +!!!warning + +The operator places trust in the user-defined major version and refrains +from conducting any PostgreSQL version detection. It is the user's +responsibility to ensure alignment between the declared major version in +the catalog and the PostgreSQL image. +!!! ## Catalog scoping @@ -66,7 +74,7 @@ spec: - major: 17 image: docker.enterprisedb.com/k8s/postgresql:17.6-standard-ubi9 - major: 18 - image: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 + image: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 ``` The following example defines a cluster-wide `ClusterImageCatalog`: @@ -85,12 +93,12 @@ spec: - major: 17 image: docker.enterprisedb.com/k8s/postgresql:17.6-standard-ubi9 - major: 18 - image: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 + image: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 ``` -### Referencing a Catalog in a Cluster - -A `Cluster` resource uses the `imageCatalogRef` to select its images: +A `Cluster` resource has the flexibility to reference either an `ImageCatalog` +(like in the following example) or a `ClusterImageCatalog` to precisely specify +the desired image. ```yaml apiVersion: postgresql.k8s.enterprisedb.io/v1 @@ -101,9 +109,10 @@ spec: instances: 3 imageCatalogRef: apiGroup: postgresql.k8s.enterprisedb.io - kind: ClusterImageCatalog # Or 'ImageCatalog' - name: postgresql-global - major: 18 + # Change the following to `ClusterImageCatalog` if needed + kind: ImageCatalog + name: postgresql + major: 16 storage: size: 1Gi ``` @@ -113,96 +122,15 @@ spec: [Image Volume Extensions](imagevolume_extensions.md) allow you to bundle containers for extensions directly within the catalog entry: -```yaml -apiVersion: postgresql.k8s.enterprisedb.io/v1 -kind: ImageCatalog -metadata: - name: postgresql -spec: - images: - - major: 18 - image: docker.enterprisedb.com/k8s_enterprise/postgresql:18.3-minimal-ubi9 - extensions: - - name: foo - image: - reference: # registry path for your `foo` extension image -``` - -The `extensions` section follows the [`ExtensionConfiguration`](pg4k.v1.md#extensionconfiguration) -API schema and structure. -Clusters referencing an image catalog can load any of its associated extensions -by name. - -!!!info - -Refer to the [documentation of image volume extensions](imagevolume_extensions.md) -for details on the internal image structure, configuration options, and -instructions on how to select or override catalog extensions within a cluster. -!!! - -[Image Volume Extensions](imagevolume_extensions.md) allow you to bundle -containers for extensions directly within the catalog entry: - -```yaml -apiVersion: postgresql.k8s.enterprisedb.io/v1 -kind: ImageCatalog -metadata: - name: postgresql -spec: - images: - - major: 18 - image: docker.enterprisedb.com/k8s_enterprise/postgresql:18.3-minimal-ubi9 - extensions: - - name: foo - image: - reference: # registry path for your `foo` extension image -``` - -The `extensions` section follows the [`ExtensionConfiguration`](pg4k.v1.md#extensionconfiguration) -API schema and structure. -Clusters referencing an image catalog can load any of its associated extensions -by name. - -!!!info -Refer to the [documentation of image volume extensions](imagevolume_extensions.md) -for details on the internal image structure, configuration options, and -instructions on how to select or override catalog extensions within a cluster. -!!! - -## EDB CloudNativePG Cluster Catalogs - The {{name.ln}} project maintains `ClusterImageCatalog` manifests for all supported images. -These catalogs are regularly updated and published in two distinct locations -within the [artifacts repository](https://github.com/cloudnative-pg/artifacts/tree/main): - -- **[`image-catalogs`](https://github.com/cloudnative-pg/artifacts/tree/main/image-catalogs):** - core catalog definitions for base image types. +These catalogs are regularly updated and published in the +[artifacts repository](https://github.com/cloudnative-pg/artifacts/tree/main/image-catalogs). -- **[`image-catalogs-extensions`](https://github.com/cloudnative-pg/artifacts/tree/main/image-catalogs-extensions):** - identical to the above catalogs, with the key difference that the `minimal` - image type includes extension definitions. - -Each catalog corresponds to a specific combination of image type and Debian -release (e.g., `trixie`). It lists the most up-to-date container images for -every supported PostgreSQL major version. - -!!!important - -To ensure maximum security and immutability, all images within official -{{name.ln}} catalogs are identified by their **SHA256 digests** rather than -just tags. -!!! - -### Version Compatibility - -While core catalogs work with older versions of the operator, **catalogs -containing an `extensions` section are only compatible with {{name.ln}} 1.29 -or later**. Using a catalog with extension definitions on an older operator -will result in those definitions being rejected. - -### Installation and Usage +Each catalog corresponds to a specific combination of image type (e.g. +`minimal`) and Debian release (e.g. `trixie`). It lists the most up-to-date +container images for every supported PostgreSQL major version. By installing these catalogs, cluster administrators can ensure that their PostgreSQL clusters are automatically updated to the latest patch release @@ -221,7 +149,7 @@ You can install all the available catalogs by using the `kustomization` file present in the `image-catalogs` directory: ```shell -kubectl apply -k https://github.com/cloudnative-pg/artifacts//image-catalogs?ref=main +kubectl apply -k 'https://github.com/cloudnative-pg/artifacts//image-catalogs?ref=main' ``` You can then view all the catalogs deployed with: @@ -230,10 +158,7 @@ You can then view all the catalogs deployed with: kubectl get clusterimagecatalogs.postgresql.k8s.enterprisedb.io ``` -### Example: Using a Catalog in a Cluster - -To create a cluster that always tracks the latest `minimal` image for -PostgreSQL 18 on `trixie`, define your `Cluster` as follows: +For example, you can create a cluster with the latest `minimal` image for PostgreSQL 18 on `trixie` with: ```yaml apiVersion: postgresql.k8s.enterprisedb.io/v1 diff --git a/product_docs/docs/postgres_for_kubernetes/1/index.mdx b/product_docs/docs/postgres_for_kubernetes/1/index.mdx index 532aaf9229..bd47b712df 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/index.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/index.mdx @@ -102,8 +102,6 @@ and OpenShift. It is designed, developed, and supported by EDB and covers the full lifecycle of a highly available Postgres database clusters with a primary/standby architecture, using native streaming replication. -{{name.ln}} was made generally available on February 4, 2021. Earlier versions were made available to selected customers prior to the GA release. - !!!note The operator has been renamed from Cloud Native PostgreSQL. Existing users @@ -141,6 +139,8 @@ You need a valid EDB subscription to use {{name.ln}} in production. !!!note +!!!note + Based on the [Operator Capability Levels model](operator_capability_levels.md), users can expect a **"Level V - Auto Pilot"** set of capabilities from the {{name.ln}} Operator. diff --git a/product_docs/docs/postgres_for_kubernetes/1/installation_upgrade.mdx b/product_docs/docs/postgres_for_kubernetes/1/installation_upgrade.mdx index a040731a56..0e9cf60649 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/installation_upgrade.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/installation_upgrade.mdx @@ -3,6 +3,8 @@ title: 'Installation and upgrades' originalFilePath: 'src/installation_upgrade.md' --- + + !!!note OpenShift For instructions on how to install Cloud Native PostgreSQL on Red Hat @@ -26,7 +28,7 @@ You must obtain an EDB subscription token to install {{name.ln}}. Without a toke !!! Installing EDB Postgres Distributed for Kubernetes requires an EDB Repos 2.0 token to gain access to the EDB private software repositories. -For instructions on obtaining this token, see: [Get your token](/repos/getting_started/get_your_token/). +For instructions on obtaining this token, see: [Get your token](/repos/getting_started/with_web/get_your_token/). Then set the Repos 2.0 token as an environment variable `EDB_SUBSCRIPTION_TOKEN`: @@ -71,12 +73,11 @@ kubectl create secret -n postgresql-operator-system docker-registry edb-pull-sec Now that the pull-secret has been added to the namespace, the operator can be installed like any other resource in Kubernetes, through a YAML manifest applied via `kubectl`. -You can install the [latest operator manifest](https://get.enterprisedb.io/pg4k/pg4k-1.29.1.yaml) -for this minor release as follows: +You can install the manifest for the latest version of the operator by running: ```sh kubectl apply --server-side -f \ - https://get.enterprisedb.io/pg4k/pg4k-1.29.1.yaml + https://get.enterprisedb.io/pg4k/pg4k-1.25.9.yaml ``` You can verify that with: @@ -169,6 +170,16 @@ some default options. For more information, please refer to the !!!warning CRITICAL WARNING: UPGRADING OPERATORS +OpenShift users, or any customer attempting an operator upgrade, MUST configure the new unified repository pull secret (docker.enterprisedb.com/k8s) before running the upgrade. If the old, deprecated repository path is still in use during the upgrade process, image pull failure will occur, leading to deployment failure and potential downtime. Follow the [Central Migration Guide](/postgres_for_kubernetes/latest/migrating_edb_registries) first. +!!! + +!!!info Important + +Please carefully read the [release notes](rel_notes) +before performing an upgrade as some versions might require +extra steps. +!!! + OpenShift users, or any customer attempting an operator upgrade, MUST configure the new unified repository pull secret (docker.enterprisedb.com/k8s) before running the upgrade. If the old, deprecated repository path is still in use during the upgrade process, image pull failure will occur, leading to deployment failure and potential downtime. Follow the [Central Migration Guide](/repos/working_with_repos/migrating_edb_registries/) first. !!! @@ -288,8 +299,17 @@ When versions are not directly upgradable, the old version needs to be removed before installing the new one. This won't affect user data but only the operator itself. + + ### Upgrading to 1.29.1, 1.28.3, or 1.25.8 +!!!info Important + +We strongly recommend that all {{name.ln}} users upgrade to version +1.29.1, or at least to the latest stable version of your current minor release +(e.g., 1.28.x). +!!! + Version 1.29.1, 1.28.3, and 1.25.8 ship the fix for `CVE-2026-44477` / `GHSA-423p-g724-fr39`. The metrics exporter now authenticates as a dedicated `cnp_metrics_exporter` role with `pg_monitor` privileges @@ -304,6 +324,24 @@ the metrics exporter role"](monitoring.md#manually-creating-the-metrics-exporter-role) in the monitoring documentation. +### Upgrading to 1.25 from a previous minor version + +!!!info Important + +We strongly recommend that all {{name.ln}} users upgrade to version +1.25.1 or at least to the latest stable version of the minor release you are +currently using (namely 1.24.x). +!!! + +!!!warning + +Every time you are upgrading to a higher minor release, make sure you +go through the release notes and upgrade instructions of all the +intermediate minor releases. For example, if you want to move +from 1.23.x to 1.25, make sure you go through the release notes +and upgrade instructions for 1.24 and 1.25. +!!! + ### Upgrading to 1.29.0 or 1.28.x !!!info Important diff --git a/product_docs/docs/postgres_for_kubernetes/1/instance_manager.mdx b/product_docs/docs/postgres_for_kubernetes/1/instance_manager.mdx index 99f6dec3c0..859963b390 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/instance_manager.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/instance_manager.mdx @@ -44,6 +44,7 @@ adjust this setting based on the time PostgreSQL needs to fully initialize in your specific environment. !!!warning + Setting `.spec.startDelay` too low can cause the liveness probe to activate prematurely, potentially resulting in unnecessary Pod restarts if PostgreSQL hasn’t fully initialized. @@ -65,13 +66,15 @@ You can customize any of the probe settings in the `.spec.probes.startup` section of your configuration. !!!warning + Be sure that any custom probe settings are tailored to your cluster's operational requirements to avoid unintended disruptions. !!! !!!info + For more details on probe configuration, refer to the -[probe API documentation](pg4k.v1.md#probewithstrategy). +[probe API documentation](pg4k.v1.md#probe). !!! If you manually specify `.spec.probes.startup.failureThreshold`, it will @@ -174,11 +177,13 @@ You can customize any of the probe settings in the `.spec.probes.liveness` section of your configuration. !!!warning + Be sure that any custom probe settings are tailored to your cluster's operational requirements to avoid unintended disruptions. !!! !!!info + For more details on probe configuration, refer to the [probe API documentation](pg4k.v1.md#probe). !!! @@ -283,64 +288,17 @@ spec: ``` !!!warning + Ensure that any custom probe settings are aligned with your cluster’s operational requirements to prevent unintended disruptions. !!! !!!info -For more information on configuring probes, see the -[probe API](pg4k.v1.md#probewithstrategy). -!!! - -### Readiness Probe Strategy - -In certain scenarios, you may need to customize the readiness strategy for your -cluster. For example, you might delay marking a replica as ready until it -begins streaming from the primary or define a maximum replication lag threshold -before considering the replica ready. - -To accommodate these requirements, {{name.ln}} extends the -`.spec.probes.readiness` stanza with two optional parameters: `type` and -`maximumLag`. Please refer to the [Startup Probe Strategy](#startup-probe-strategy) -section for detailed information on these options. - -!!!info Important -Unlike the startup probe, the `.spec.probes.readiness.maximumLag` option is -continuously monitored. A lagging replica may become unready if this setting is -not appropriately tuned. -!!! -!!!warning -Incorrect configuration of the `maximumLag` option can lead to repeated -readiness probe failures, causing serious consequences, such as: - -- Exclusion of the replica from key operator features, such as promotion - during failover or participation in synchronous replication quorum. -- Disruptions in read/read-only services. -- In longer failover times scenarios, replicas might be declared unready, - leading to a cluster stall requiring manual intervention. -!!! - -!!!note Recommendation -Use the `streaming` and `maximumLag` options with extreme caution. If -you're unfamiliar with PostgreSQL replication, rely on the default -strategy. Seek professional advice if unsure. +For more information on configuring probes, see the +[probe API](pg4k.v1.md#probe). !!! -The following example requires a replica to have a maximum lag of 64Mi from the -source to be considered ready. It also provides approximately 300 seconds (30 -failures × 10 seconds) for the startup probe to succeed: - -```yaml -# -probes: - readiness: - type: streaming - maximumLag: 64Mi - failureThreshold: 30 - periodSeconds: 10 -``` - ## Shutdown control When a Pod running Postgres is deleted, either manually or by Kubernetes @@ -365,6 +323,7 @@ The shutdown procedure is composed of two steps: seconds. !!!info Important + In order to avoid any data loss in the Postgres cluster, which impacts the database [RPO](before_you_start.md#postgresql-terminology), don't delete the Pod where the primary instance is running. In this case, perform a switchover to @@ -384,6 +343,7 @@ the time given to the former primary to shut down gracefully and archive all the WAL files. By default it is set to `3600` (1 hour). !!!warning + The `.spec.switchoverDelay` option affects the [RPO](before_you_start.md#postgresql-terminology) and [RTO](before_you_start.md#postgresql-terminology) of your PostgreSQL database. Setting it to a low value, might favor RTO over RPO but lead to data loss at cluster level @@ -410,11 +370,13 @@ provides details on checking the disk space used by WAL segments and standard metrics on disk usage exported to Prometheus. !!!info Important + In a production system, it is critical to monitor the database continuously. Exhausted disk storage can lead to a database server shutdown. !!! !!!note + The detection of exhausted storage relies on a storage class that accurately reports disk size and usage. This may not be the case in simulated Kubernetes environments like Kind or with test storage class implementations diff --git a/product_docs/docs/postgres_for_kubernetes/1/kubectl-plugin.mdx b/product_docs/docs/postgres_for_kubernetes/1/kubectl-plugin.mdx index d4f8923d5a..2a40ebd955 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/kubectl-plugin.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/kubectl-plugin.mdx @@ -12,6 +12,7 @@ The plugin also works with `oc` in an OpenShift environment. You can install the `cnp` plugin using a variety of methods. !!!note + For air-gapped systems, installation via package managers, using previously downloaded files, may be a good option. !!! @@ -36,11 +37,11 @@ them in your systems. #### Debian packages -For example, let's install the 1.29.1 release of the plugin, for an Intel based +For example, let's install the 1.25.9 release of the plugin, for an Intel based 64 bit server. First, we download the right `.deb` file. ```sh -wget https://github.com/EnterpriseDB/kubectl-cnp/releases/download/v1.29.1/kubectl-cnp_1.29.1_linux_x86_64.deb \ +wget https://github.com/EnterpriseDB/kubectl-cnp/releases/download/v1.25.9/kubectl-cnp_1.25.9_linux_x86_64.deb \ --output-document kube-plugin.deb ``` @@ -51,17 +52,17 @@ $ sudo dpkg -i kube-plugin.deb Selecting previously unselected package cnp. (Reading database ... 6688 files and directories currently installed.) Preparing to unpack kube-plugin.deb ... -Unpacking kubectl-cnp (1.29.1) ... -Setting up kubectl-cnp (1.29.1) ... +Unpacking kubectl-cnp (1.25.9) ... +Setting up kubectl-cnp (1.25.9) ... ``` #### RPM packages -As in the example for `.rpm` packages, let's install the 1.29.1 release for an +As in the example for `.rpm` packages, let's install the 1.25.9 release for an Intel 64 bit machine. Note the `--output` flag to provide a file name. ```sh -curl -L https://github.com/EnterpriseDB/kubectl-cnp/releases/download/v1.29.1/kubectl-cnp_1.29.1_linux_x86_64.rpm \ +curl -L https://github.com/EnterpriseDB/kubectl-cnp/releases/download/v1.25.9/kubectl-cnp_1.25.9_linux_x86_64.rpm \ --output kube-plugin.rpm ``` @@ -75,7 +76,7 @@ Dependencies resolved. Package Architecture Version Repository Size ==================================================================================================== Installing: - cnp x86_64 1.29.1-1 @commandline 20 M + cnp x86_64 1.25.9-1 @commandline 20 M Transaction Summary ==================================================================================================== @@ -126,7 +127,31 @@ chmod +x kubectl_complete-cnp sudo mv kubectl_complete-cnp /usr/local/bin ``` +!!! Important + The name of the script needs to be exactly the one provided since is used by the kubectl auto-complete process + +### Configuring auto-completion + +To configure auto-completion for the plugin, a helper shell script needs to be +installed into your current PATH. Assuming the latter contains `/usr/local/bin`, +this can be done with the following commands: + +```sh +cat > kubectl_complete-cnp < ``` !!!note + The plugin automatically detects if the standard output channel is connected to a terminal. In such cases, it may add ANSI colors to the command output. To disable colors, use the `--color=never` option with the command. @@ -209,6 +235,7 @@ cluster, including: (replay LSN). !!!info Important + The status information above is taken at different times and at different locations, resulting in slightly inconsistent returned values. For example, the `Current Write LSN` location in the main header, might be different @@ -246,9 +273,9 @@ sandbox-3 0/604DE38 0/604DE38 0/604DE38 0/604DE38 00:00:00 00:00:00 00 Instances status Name Current LSN Replication role Status QoS Manager Version Node ---- ----------- ---------------- ------ --- --------------- ---- -sandbox-1 0/604DE38 Primary OK BestEffort 1.29.1 k8s-eu-worker -sandbox-2 0/604DE38 Standby (async) OK BestEffort 1.29.1 k8s-eu-worker2 -sandbox-3 0/604DE38 Standby (async) OK BestEffort 1.29.1 k8s-eu-worker +sandbox-1 0/604DE38 Primary OK BestEffort 1.25.9 k8s-eu-worker +sandbox-2 0/604DE38 Standby (async) OK BestEffort 1.25.9 k8s-eu-worker2 +sandbox-3 0/604DE38 Standby (async) OK BestEffort 1.25.9 k8s-eu-worker ``` If you require more detailed status information, use the `--verbose` option (or @@ -302,9 +329,9 @@ sandbox-primary primary 1 1 1 Instances status Name Current LSN Replication role Status QoS Manager Version Node ---- ----------- ---------------- ------ --- --------------- ---- -sandbox-1 0/6053720 Primary OK BestEffort 1.29.1 k8s-eu-worker -sandbox-2 0/6053720 Standby (async) OK BestEffort 1.29.1 k8s-eu-worker2 -sandbox-3 0/6053720 Standby (async) OK BestEffort 1.29.1 k8s-eu-worker +sandbox-1 0/6053720 Primary OK BestEffort 1.25.9 k8s-eu-worker +sandbox-2 0/6053720 Standby (async) OK BestEffort 1.25.9 k8s-eu-worker2 +sandbox-3 0/6053720 Standby (async) OK BestEffort 1.25.9 k8s-eu-worker ``` With an additional `-v` (e.g. `kubectl cnp status sandbox -v -v`), you can @@ -377,6 +404,7 @@ a switchover, the switchover will take precedence over the in-place restart. A common case for this will be a minor upgrade of PostgreSQL image. !!!note + If you want ConfigMaps and Secrets to be **automatically** reloaded by instances, you can add a label with key `k8s.enterprisedb.io/reload` to it. !!! @@ -445,6 +473,7 @@ The `operator` sub-command requests the operator to provide information regarding the operator deployment, configuration and events. !!!info Important + All confidential information in Secrets and ConfigMaps is REDACTED. The Data map will show the **keys** but the values will be empty. The flag `-S` / `--stopRedaction` will defeat the redaction and show the @@ -452,6 +481,7 @@ values. Use only at your own risk, this will share private data. !!! !!!note + By default, operator logs are not collected, but you can enable operator log collection with the `--logs` flag !!! @@ -469,6 +499,7 @@ Use the `-f` flag to name a result file explicitly. If the `-f` flag is not used default time-stamped filename is created for the zip file. !!!note + The report plugin obeys `kubectl` conventions, and will look for objects constrained by namespace. The {{name.short}} Operator will generally not be installed in the same namespace as the clusters. @@ -524,6 +555,7 @@ Archive: report_operator_.zip ``` !!!note + The plugin will try to get the PREVIOUS operator's logs, which is helpful when investigating restarted operators. In all cases, it will also try to get the CURRENT operator logs. If current @@ -532,12 +564,12 @@ and previous logs are available, it will show them both. ```output ====== Begin of Previous Log ===== -2023-03-28T12:56:41.251711811Z {"level":"info","ts":"2023-03-28T12:56:41Z","logger":"setup","msg":"Starting EDB Postgres for Kubernetes Operator","version":"1.29.1","build":{"Version":"1.29.1+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} +2023-03-28T12:56:41.251711811Z {"level":"info","ts":"2023-03-28T12:56:41Z","logger":"setup","msg":"Starting EDB Postgres for Kubernetes Operator","version":"1.25.9","build":{"Version":"1.25.9+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} 2023-03-28T12:56:41.251851909Z {"level":"info","ts":"2023-03-28T12:56:41Z","logger":"setup","msg":"Starting pprof HTTP server","addr":"0.0.0.0:6060"} ====== End of Previous Log ===== -2023-03-28T12:57:09.854306024Z {"level":"info","ts":"2023-03-28T12:57:09Z","logger":"setup","msg":"Starting EDB Postgres for Kubernetes Operator","version":"1.29.1","build":{"Version":"1.29.1+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} +2023-03-28T12:57:09.854306024Z {"level":"info","ts":"2023-03-28T12:57:09Z","logger":"setup","msg":"Starting EDB Postgres for Kubernetes Operator","version":"1.25.9","build":{"Version":"1.25.9+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} 2023-03-28T12:57:09.854363943Z {"level":"info","ts":"2023-03-28T12:57:09Z","logger":"setup","msg":"Starting pprof HTTP server","addr":"0.0.0.0:6060"} ``` @@ -609,6 +641,7 @@ Note that the cluster information does not contain configuration Secrets / Confi so the `-S` is disabled. !!!note + By default, cluster logs are not collected, but you can enable cluster log collection with the `--logs` flag !!! @@ -682,6 +715,7 @@ Install Plan, and add them automatically to the zip under the `openshift` sub-folder. !!!note + the namespace becomes very important on OpenShift. The default namespace for OpenShift in CNP is "openshift-operators". Many (most) clients will use a different namespace for the CNP operator. @@ -871,6 +905,7 @@ To explore all available options, use the `-h` flag for detailed explanations of the supported flags and their usage. !!!info + You can also increase the verbosity of the log by adding more `-v` options. !!! @@ -932,6 +967,7 @@ PVCs, in which the one containing the `PGDATA` is annotated with the latest available status, including content from `pg_controldata`. !!!warning + A cluster having fenced instances cannot be hibernated, as fencing is part of the hibernation procedure too. !!! @@ -985,6 +1021,7 @@ The `kubectl cnp backup` command requests a new physical backup for an existing Postgres cluster by creating a new `Backup` resource. !!!info + From release 1.21, the `backup` command accepts a new flag, `-m` to specify the backup method. To request a backup using volume snapshots, set `-m volumeSnapshot` @@ -1028,6 +1065,7 @@ process (psql) connected to an existing Postgres cluster, as if you were running it from the actual pod. This means that you will be using the `postgres` user. !!!info Important + As you will be connecting as `postgres` user, in production environments this method should be used with extreme care, by authorized personnel only. !!! @@ -1064,6 +1102,7 @@ This command will start `kubectl exec`, and the `kubectl` executable must be reachable in your `PATH` variable to correctly work. !!!note + When connecting to instances running on OpenShift, you must explicitly pass a username to the `psql` command, because of a [security measure built into OpenShift](https://cloud.redhat.com/blog/a-guide-to-openshift-and-uids): @@ -1076,6 +1115,7 @@ kubectl cnp psql cluster-example -- -U postgres ### Snapshotting a Postgres cluster !!!warning + The `kubectl cnp snapshot` command has been removed. Please use the [`backup` command](#requesting-a-new-physical-backup) to request backups using volume snapshots. @@ -1093,6 +1133,7 @@ images, you can install pgAdmin in your environment as a standard Kubernetes deployment. !!!info Important + Deployment of pgAdmin in Kubernetes production environments is beyond the scope of this document and, more broadly, of the {{name.ln}} project. !!! @@ -1154,6 +1195,7 @@ kubectl cnp pgadmin4 --dry-run cluster-example | kubectl delete -f - ``` !!!warning + Never deploy pgAdmin in production using the plugin. !!! @@ -1166,6 +1208,7 @@ creation of logical replication publications, particularly on remote PostgreSQL databases. !!!warning + It is crucial to have a solid understanding of both the capabilities and limitations of PostgreSQL's native logical replication system before using these commands. @@ -1195,6 +1238,7 @@ There are two primary use cases: `` PostgreSQL `Cluster` (by default, the `app` database). !!!warning + When connecting to an external cluster, ensure that the specified user has sufficient permissions to execute the `CREATE PUBLICATION` command. !!! @@ -1246,6 +1290,7 @@ which will create a publication named `app` for all the tables in the `source-cluster`, running the SQL commands on the source cluster. !!!info + There are two sample files that have been provided for illustration and inspiration: [logical-source](../samples/cluster-example-logical-source.yaml) and [logical-destination](../samples/cluster-example-logical-destination.yaml). @@ -1281,6 +1326,7 @@ replication subscriptions, especially when dealing with remote PostgreSQL databases. !!!warning + Before using these commands, it is essential to have a comprehensive understanding of both the capabilities and limitations of PostgreSQL's native logical replication system. @@ -1333,12 +1379,14 @@ kubectl cnp subscription create destination-cluster \ will create a subscription for `app` on the destination cluster. !!!warning + Prioritize testing subscriptions in a non-production environment to ensure their effectiveness and identify any potential issues before implementing them in a production setting. !!! !!!info + There are two sample files that have been provided for illustration and inspiration: [logical-source](../samples/cluster-example-logical-source.yaml) and [logical-destination](../samples/cluster-example-logical-destination.yaml). @@ -1406,6 +1454,7 @@ kubectl cnp subscription sync-sequences destination-cluster \ ``` !!!warning + Prioritize testing subscriptions in a non-production environment to guarantee their effectiveness and detect any potential issues before deploying them in a production setting. @@ -1530,6 +1579,7 @@ rules: ``` !!!info Important + Keeping the verbs restricted per `resources` and per `apiGroups` helps to prevent inadvertently granting more than intended permissions. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/kubernetes_upgrade.mdx b/product_docs/docs/postgres_for_kubernetes/1/kubernetes_upgrade.mdx index 2fbdd3229b..67e3f73115 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/kubernetes_upgrade.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/kubernetes_upgrade.mdx @@ -46,6 +46,7 @@ local to the Kubernetes worker node running the PostgreSQL database. Node-local storage, or simply *local storage*, is employed to enhance performance. !!!note + If your database files reside on shared storage accessible over the network, the default self-healing behavior of the operator can efficiently handle scenarios where volumes are reused by pods on different nodes after a @@ -100,6 +101,7 @@ on draining the node during development activities. ## Node Maintenance Window !!!info Important + While {{name.ln}} will continue supporting the node maintenance window, it is currently recommended to transition to direct control of pod disruption budgets, as explained in the previous section. This section is retained @@ -113,6 +115,7 @@ to avoid standard self-healing procedures to kick in, while, for example, enlarging the partition on the physical node or updating the node itself. !!!warning + Limit the duration of the maintenance window to the shortest amount of time possible. In this phase, some of the expected behaviors of Kubernetes are either disabled or running with @@ -145,6 +148,7 @@ does **not** apply to clusters with only one instance and reusePVC disabled: see section below. !!!note + When performing the `kubectl drain` command, you will need to add the `--delete-emptydir-data` option. Don't be afraid: it refers to another volume internally used @@ -152,6 +156,7 @@ by the operator - not the PostgreSQL data directory. !!! !!!info Important + `PodDisruptionBudget` management can be disabled by setting the `.spec.enablePDB` field to `false`. In that case, the operator won't create `PodDisruptionBudgets` and will delete them if they were @@ -161,6 +166,7 @@ previously created. ### Single instance clusters with `reusePVC` set to `false` !!!info Important + We recommend to always create clusters with more than one instance in order to guarantee high availability. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx b/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx index ccf6cb654b..b4b97c8a56 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx @@ -11,6 +11,7 @@ can be linked together and put in relationship through *labels* and *annotations*. !!!info + For more information, see the Kubernetes documentation on [annotations](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) and [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/). @@ -29,6 +30,7 @@ so that when you define these labels or annotations in a cluster's metadata, they're inherited by all resources created by it (including pods). !!!note + Label and annotation inheritance is the technique adopted by {{name.ln}} instead of alternative approaches such as pod templates. !!! @@ -120,28 +122,6 @@ instead it on the old primary during a failover or switchover and clears it automatically once the transition completes. -`app.kubernetes.io/managed-by` -: Name of the manager. It will always be `cloudnative-pg`. - Available across all {{name.ln}} managed resources. - -`app.kubernetes.io/name` -: Name of the application. It will always be `postgresql`. - Available on pods, jobs, deployments, services, persistentVolumeClaims, volumeSnapshots, - podDisruptionBudgets, podMonitors. - -`app.kubernetes.io/component` -: Name of the component (`database`, `pooler`, ...). - Available on pods, jobs, deployments, services, persistentVolumeClaims, volumeSnapshots, - podDisruptionBudgets, podMonitors. - -`app.kubernetes.io/instance` -: Name of the owning `Cluster` resource. - Available on pods, jobs, deployments, services, volumeSnapshots, podDisruptionBudgets, podMonitors. - -`app.kubernetes.io/version` -: Major version of PostgreSQL. - Available on pods, jobs, services, volumeSnapshots, podDisruptionBudgets, podMonitors. - ## Predefined annotations {{name.ln}} manages the following predefined annotations: @@ -203,6 +183,14 @@ instead `k8s.enterprisedb.io/operatorVersion` : Version of the operator. +`k8s.enterprisedb.io/passwordPassthrough` +: When set to `enabled` on a basic-auth `Secret` consumed by the + operator (superuser, application user, or a managed-role password + secret), the operator forwards the password value verbatim in the + `CREATE`/`ALTER ROLE` statement instead of SCRAM-SHA-256 encoding + it operator-side. PostgreSQL then encodes the value according to its + own `password_encryption` setting. See [Opting out of operator-side encoding](declarative_role_management.md#opting-out-of-operator-side-encoding). + `k8s.enterprisedb.io/pgControldata` : Output of the `pg_controldata` command. This annotation replaces the old, deprecated `k8s.enterprisedb.io/hibernatePgControlData` annotation. @@ -310,6 +298,7 @@ The following continues from that example and limits it to the following: - Labels: `app`, `environment`, and `workload` !!!note + Feel free to select the names that most suit your context for both annotations and labels. You can also use wildcards in naming and adopt strategies like using `mycompany/*` for all labels diff --git a/product_docs/docs/postgres_for_kubernetes/1/license_keys.mdx b/product_docs/docs/postgres_for_kubernetes/1/license_keys.mdx index edeb750157..4be21c17cb 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/license_keys.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/license_keys.mdx @@ -12,6 +12,11 @@ If you are not using an EDB subscription token and installing from public reposi OpenShift users, or any customer attempting an operator upgrade, MUST configure the new unified repository pull secret (docker.enterprisedb.com/k8s) before running the upgrade. If the old, deprecated repository path is still in use during the upgrade process, image pull failure will occur, leading to deployment failure and potential downtime. Follow the [Central Migration Guide](/repos/working_with_repos/migrating_edb_registries/) first. !!! +!!!warning CRITICAL WARNING: UPGRADING OPERATORS + +OpenShift users, or any customer attempting an operator upgrade, MUST configure the new unified repository pull secret (docker.enterprisedb.com/k8s) before running the upgrade. If the old, deprecated repository path is still in use during the upgrade process, image pull failure will occur, leading to deployment failure and potential downtime. Follow the [Central Migration Guide](/postgres_for_kubernetes/latest/migrating_edb_registries) first. +!!! + The following documentation is only for users who have installed the operator using a license key. ## Company level license keys diff --git a/product_docs/docs/postgres_for_kubernetes/1/logging.mdx b/product_docs/docs/postgres_for_kubernetes/1/logging.mdx index e78635b40d..40b3591acf 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/logging.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/logging.mdx @@ -12,6 +12,7 @@ management tools, including command line ones like [stern](https://github.com/stern/stern). !!!info Important + Long-term storage and management of logs are outside the scope of the operator and should be handled at the Kubernetes infrastructure level. For more information, see the @@ -31,6 +32,7 @@ Each log entry includes the following fields: - `logging_pod` – The name of the pod where the log was generated. !!!info + If your log ingestion system requires custom field names, you can rename the `level` and `ts` fields using the `log-field-level` and `log-field-timestamp` flags in the operator controller. This can be configured @@ -44,6 +46,7 @@ specification using the `logLevel` option. Available log levels are: `error`, `warning`, `info` (default), `debug`, and `trace`. !!!info Important + Currently, the log level can only be set at the time the instance starts. Changes to the log level in the cluster specification after the cluster has started will only apply to new pods, not existing ones. @@ -101,6 +104,7 @@ Each PostgreSQL log entry is a JSON object with the `logger` key set to ``` !!!info + Internally, the operator uses PostgreSQL's CSV log format. For more details, refer to the [PostgreSQL documentation on CSV log format](https://www.postgresql.org/docs/current/runtime-config-logging.html). !!! @@ -114,6 +118,7 @@ To enable PGAudit, add the necessary `pgaudit` parameters in the `postgresql` section of the cluster configuration. !!!info Important + The PGAudit library must be added to `shared_preload_libraries`. {{name.ln}} automatically manages this based on the presence of `pgaudit.*` parameters in the PostgreSQL configuration. The operator handles both the @@ -124,6 +129,7 @@ Additionally, the operator manages the creation and removal of the PGAudit extension across all databases within the cluster. !!!info Important + {{name.ln}} executes the `CREATE EXTENSION` and `DROP EXTENSION` commands in all databases within the cluster that accept connections. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx b/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx index 3b8dbc128a..9fbccaae11 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx @@ -34,6 +34,7 @@ This flexible model is particularly useful for: - Integration with external applications !!!info + For more details, examples, and limitations, please refer to the [official PostgreSQL documentation on Logical Replication](https://www.postgresql.org/docs/current/logical-replication.html). !!! @@ -62,6 +63,7 @@ When managing `Cluster` objects with **{{name.ln}}**, PostgreSQL publications can be defined declaratively through the `Publication` resource. !!!info + Please refer to the [API reference](pg4k.v1.md#publication) for the full list of attributes you can define for each `Publication` object. !!! @@ -100,6 +102,7 @@ command. This allows you to precisely define which tables, or even which types of data changes, should be included in a publication. !!!info Important + If you are using PostgreSQL versions earlier than 15, review the syntax and options available for `CREATE PUBLICATION` in your specific release. Some parameters and features may not be supported. @@ -147,6 +150,13 @@ The `Publication` object must reference a specific `Cluster`, determining where the publication will be created. It is managed by the cluster's primary instance, ensuring the publication is created or updated as needed. +!!!warning + +The `spec.cluster` field is immutable after creation. To create a +publication on a different `Cluster`, create a new `Publication` resource +instead of updating an existing one. +!!! + ### Reconciliation and Status After creating a `Publication`, {{name.ln}} manages it on the primary @@ -189,6 +199,11 @@ spec: In this case, deleting the `Publication` object also removes the `publisher` publication from the `app` database of the `freddie` cluster. +On a replica cluster the database is read-only, so deleting a `Publication` +object releases its finalizer and removes the Kubernetes object without dropping +the publication in PostgreSQL, even with `publicationReclaimPolicy: delete`. +Dropping the publication is left to the primary cluster, which owns it. + ## Subscriptions In PostgreSQL's publish-and-subscribe replication model, a @@ -199,6 +214,7 @@ specifies the set of publications (one or more) it subscribes to. Subscriptions can be created on any supported PostgreSQL instance acting as the *subscriber*. !!!info Important + Since schema definitions are not replicated, the subscriber must have the corresponding tables already defined before data replication begins. !!! @@ -207,6 +223,7 @@ corresponding tables already defined before data replication begins. declaratively using the `Subscription` resource. !!!info + Please refer to the [API reference](pg4k.v1.md#subscription) for the full list of attributes you can define for each `Subscription` object. !!! @@ -252,6 +269,7 @@ externalClusters: ``` !!!info + For more details on configuring the `externalClusters` section, see the ["Bootstrap" section](bootstrap.md#the-externalclusters-section) of the documentation. @@ -285,6 +303,13 @@ where the subscription will be managed. {{name.ln}} ensures that the subscription is created or updated on the primary instance of the specified cluster. +!!!warning + +The `spec.cluster` field is immutable after creation. To manage the +subscription on a different `Cluster`, create a new `Subscription` +resource instead of updating an existing one. +!!! + ### Reconciliation and Status After creating a `Subscription`, {{name.ln}} manages it on the primary @@ -327,12 +352,10 @@ spec: In this case, deleting the `Subscription` object also removes the `subscriber` subscription from the `app` database of the `king` cluster. -### Resilience to Failovers - -To ensure that your logical replication subscriptions remain operational after -a failover of the publisher, configure {{name.ln}} to synchronize logical -decoding slots across the cluster. For detailed instructions, see -[Logical Decoding Slot Synchronization](replication.md#logical-decoding-slot-synchronization). +On a replica cluster the database is read-only, so deleting a `Subscription` +object releases its finalizer and removes the Kubernetes object without dropping +the subscription in PostgreSQL, even with `subscriptionReclaimPolicy: delete`. +Dropping the subscription is left to the primary cluster, which owns it. ## Limitations diff --git a/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx b/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx index 35f5442f0d..4d48b7610f 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx @@ -6,6 +6,7 @@ originalFilePath: 'src/monitoring.md' !!!info Important + Installing Prometheus and Grafana is beyond the scope of this project. We assume they are correctly installed in your system. However, for experimentation we provide instructions in @@ -22,11 +23,13 @@ more `ConfigMap` or `Secret` resources (see the ["User defined metrics" section](#user-defined-metrics) below for details). !!!info Important + {{name.ln}}, by default, installs a set of [predefined metrics](#default-set-of-metrics) in a `ConfigMap` named `postgresql-operator-default-monitoring`. !!! !!!info + You can inspect the exported metrics by following the instructions in the ["How to inspect the exported metrics"](#how-to-inspect-the-exported-metrics) section below. @@ -65,25 +68,12 @@ The default database can always be overridden for a given user-defined metric, by specifying a list of one or more databases in the `target_databases` option. !!!note Prometheus/Grafana + If you are interested in evaluating the integration of {{name.ln}} with Prometheus and Grafana, you can find a quick setup guide in [Part 4 of the quickstart](quickstart.md#part-4-monitor-clusters-with-prometheus-and-grafana) !!! -### Output caching - -By default, the outputs of monitoring queries are cached for thirty -seconds. This is done to enhance resource efficiency and to avoid -PostgreSQL to run monitoring queries every time the prometheus -endpoint is scraped. - -The cache itself can be observed by the `cache_hits`, `cache_misses` -and `last_update_timestamp` metrics. - -Setting the `cluster.spec.monitoring.metricsQueriesTTL` to zero will -disable the cache, and in that case the metrics will be run on every -metrics endpoint scrape. - ### Monitoring with the Prometheus operator You can monitor a specific PostgreSQL cluster using the @@ -114,6 +104,7 @@ spec: ``` !!!info Important Configuration Details + - `metadata.name`: Give your `PodMonitor` a unique name. - `spec.namespaceSelector`: Use this to specify the namespace where your PostgreSQL cluster is running. @@ -124,6 +115,7 @@ spec: #### Deprecation of Automatic `PodMonitor` Creation !!!warning Feature Deprecation Notice + The `.spec.monitoring.enablePodMonitor` field in the `Cluster` resource is now deprecated and will be removed in a future version of the operator. !!! @@ -141,6 +133,7 @@ setting to `true`. This setup ensures that the metrics exporter uses the same server certificate used by PostgreSQL to secure communication on port 5432. !!!info Important + Changing the `.spec.monitoring.tls.enabled` setting will trigger a rolling restart of the Cluster. !!! @@ -171,11 +164,13 @@ spec: ``` !!!info Important + Ensure you modify the example above with a unique name, as well as the correct Cluster's namespace and labels (e.g., `cluster-example`). !!! !!!info Important + The `serverName` field in the metrics endpoint must match one of the names defined in the server certificate. If the default certificate is in use, the `serverName` value should be in the format `-rw`. @@ -263,7 +258,7 @@ cnp_collector_up{cluster="cluster-example"} 1 # HELP cnp_collector_postgres_version Postgres version # TYPE cnp_collector_postgres_version gauge -cnp_collector_postgres_version{cluster="cluster-example",full="18.3"} 18.3 +cnp_collector_postgres_version{cluster="cluster-example",full="18.4"} 18.4 # HELP cnp_collector_last_failed_backup_timestamp The last failed backup as a unix timestamp (Deprecated) # TYPE cnp_collector_last_failed_backup_timestamp gauge @@ -438,22 +433,17 @@ go_threads 18 ``` !!!note + `cnp_collector_postgres_version` is a GaugeVec metric containing the `Major.Minor` version of Postgres (either PostgreSQL or EPAS). The full semantic version `Major.Minor.Patch` can be found inside one of its label field named `full`. !!! -!!!warning -The metrics `cnp_collector_last_failed_backup_timestamp`, -`cnp_collector_last_available_backup_timestamp`, and -`cnp_collector_first_recoverability_point` have been deprecated starting -from version 1.26. These metrics will continue to function with native backup -solutions such as in-core Barman Cloud (deprecated) and volume snapshots. Note -that for these cases, `cnp_collector_first_recoverability_point` and -`cnp_collector_last_available_backup_timestamp` will remain zero until the -first backup is completed to the object store. This is separate from WAL -archiving. +!!!note + +`cnp_collector_first_recoverability_point` and `cnp_collector_last_available_backup_timestamp` +will be zero until your first backup to the object store. This is separate from the WAL archival. !!! ### User defined metrics @@ -488,12 +478,14 @@ The `customQueriesConfigMap`/`customQueriesSecret` sections contain a list of Take care that the referred resources have to be created **in the same namespace as the Cluster** resource. !!!note + If you want ConfigMaps and Secrets to be **automatically** reloaded by instances, you can add a label with key `k8s.enterprisedb.io/reload` to it, otherwise you will have to reload the instances using the `kubectl cnp reload` subcommand. !!! !!!info Important + When a user defined metric overwrites an already existing metric the instance manager prints a json warning log, containing the message:`Query with the same name already found. Overwriting the existing one.` and a key `queryName` containing the overwritten query name. @@ -534,6 +526,14 @@ collect per-database metrics across the whole cluster. Schema-qualify catalog references (`pg_catalog.now()`, `pg_catalog.current_database()`) to prevent `search_path` shadowing by user-owned objects. + +Custom monitoring queries run inside a transaction whose +`search_path` is pinned to `pg_catalog, public, pg_temp`, +regardless of any `search_path` configured on the database or the +role. Unqualified references to objects in other user-defined +schemas will therefore fail to resolve: schema-qualify them (e.g. +`myschema.mytable`) so the query does not depend on the +`search_path`. !!! #### Example of a user defined metric @@ -621,6 +621,7 @@ scraped, grant `CONNECT` explicitly (see "Custom query privileges and safety" above). !!!note + The `*` character has a [special meaning](https://yaml.org/spec/1.2/spec.html#id2786448) in yaml, so you need to quote (`"*"`) the `target_databases` value when it includes such a pattern. !!! @@ -749,6 +750,7 @@ cnp__{= ... } - tls.key: -``` - -Next, update the operator deployment to mount the secret and configure the -environment variable: - -```yaml -spec: - template: - spec: - containers: - - name: manager - env: - - name: METRICS_CERT_DIR - value: /run/secrets/k8s.enterprisedb.io/metrics - volumeMounts: - - mountPath: /run/secrets/k8s.enterprisedb.io/metrics - name: metrics-certificates - readOnly: true - volumes: - - name: metrics-certificates - secret: - secretName: postgresql-operator-metrics-cert - defaultMode: 420 -``` - -!!!note -When `METRICS_CERT_DIR` is set, the operator automatically enables TLS for -the metrics server. You must also update your PodMonitor configuration to -use the `https` scheme. -!!! - -Example `PodMonitor` configuration with TLS enabled: - -```yaml -apiVersion: monitoring.coreos.com/v1 -kind: PodMonitor -metadata: - name: postgresql-operator-controller-manager - namespace: postgresql-operator-system -spec: - selector: - matchLabels: - app.kubernetes.io/name: cloud-native-postgresql - podMetricsEndpoints: - - port: metrics - scheme: https - tlsConfig: - insecureSkipVerify: true # or configure proper CA validation -``` - ## How to inspect the exported metrics In this section we provide basic instructions on how to inspect @@ -950,6 +881,7 @@ the metrics exported by a specific PostgreSQL instance manager (primary or replica) or the operator. !!!note + In the examples below we assume we are working in the default namespace, and with the operator installed in the `postgresql-operator-system` namespace. Please adapt to your use case. @@ -995,7 +927,7 @@ metadata: spec: containers: - name: curl - image: curlimages/curl:8.17.0 + image: curlimages/curl:8.21.0 command: ['sleep', '3600'] EOF ``` @@ -1042,6 +974,7 @@ kubectl delete -f curl.yaml ## Auxiliary resources !!!info Important + These resources are provided for illustration and experimentation, and do not represent any kind of recommendation for your production system !!! @@ -1101,6 +1034,7 @@ data: If the `ConfigMap` already exists, just add the variable `enableUserWorkload: true`. !!!info Important + This will enable the monitoring for the whole cluster, if it is needed only for one namespace/project please refer to the official Red Hat documentation or talk with your cluster administrator. @@ -1123,6 +1057,7 @@ spec: ``` !!!note + We currently don’t use `ServiceMonitor` because our service doesn’t define a port pointing to the metrics. If we added a metric port this could expose sensitive data. diff --git a/product_docs/docs/postgres_for_kubernetes/1/object_stores.mdx b/product_docs/docs/postgres_for_kubernetes/1/object_stores.mdx index 5ab5b7c71f..93a4e45ba4 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/object_stores.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/object_stores.mdx @@ -5,15 +5,6 @@ originalFilePath: 'src/appendixes/object_stores.md' -!!!warning -As of {{name.ln}} 1.26, **native Barman Cloud support is deprecated** in -favor of the **Barman Cloud Plugin**. While the native integration remains -functional for now, we strongly recommend beginning a gradual migration to -the plugin-based interface after appropriate testing. The Barman Cloud -Plugin documentation describes -[how to use common object stores](https://cloudnative-pg.io/plugin-barman-cloud/docs/object_stores/). -!!! - You can store the [backup](backup.md) files in any service that is supported by the Barman Cloud infrastructure. That is: @@ -27,6 +18,7 @@ The required setup depends on the chosen storage provider and is discussed in the following sections. !!!note Authentication Methods + {{name.ln}} does not independently test all authentication methods supported by `barman-cloud`. {{name.ln}}' responsibility is limited to passing the provided credentials to `barman-cloud`, which then handles authentication @@ -167,6 +159,27 @@ spec: [...] ``` +!!!note + +Recent changes to the [boto3 implementation](https://github.com/boto/boto3/issues/4392) +of [Amazon S3 Data Integrity Protections](https://docs.aws.amazon.com/sdkref/latest/guide/feature-dataintegrity.html) +may lead to the `x-amz-content-sha256` error. If you encounter this issue, you +can apply the following workaround by setting specific environment variables at +the cluster level through `spec.env`: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +[...] +spec: + env: + - name: AWS_REQUEST_CHECKSUM_CALCULATION + value: when_required + - name: AWS_RESPONSE_CHECKSUM_VALIDATION + value: when_required +``` +!!! + ### Using Object Storage with a private CA Suppose you configure an Object Storage provider which uses a certificate @@ -194,6 +207,7 @@ spec: ``` !!!note + If you want ConfigMaps and Secrets to be **automatically** reloaded by instances, you can add a label with key `k8s.enterprisedb.io/reload` to the Secrets/ConfigMaps. Otherwise, you will have to reload the instances using the `kubectl cnp reload` subcommand. @@ -378,7 +392,136 @@ spec: Now the operator will use the credentials to authenticate against Google Cloud Storage. !!!info Important + This way of authentication will create a JSON file inside the container with all the needed information to access your Google Cloud Storage bucket, meaning that if someone gets access to the pod will also have write permissions to the bucket. !!! + +## MinIO Gateway + +Optionally, you can use MinIO Gateway as a common interface which +relays backup objects to other cloud storage solutions, like S3 or GCS. +For more information, please refer to [MinIO official documentation](https://docs.min.io/). + +Specifically, the EDB Postgres for Kubernetes cluster can directly point to a local +MinIO Gateway as an endpoint, using previously created credentials and service. + +MinIO secrets will be used by both the PostgreSQL cluster and the MinIO instance. +Therefore, you must create them in the same namespace: + +```sh +kubectl create secret generic minio-creds \ + --from-literal=MINIO_ACCESS_KEY= \ + --from-literal=MINIO_SECRET_KEY= +``` + +!!!note + +Cloud Object Storage credentials will be used only by MinIO Gateway in this case. +!!! + +!!!info Important + +In order to allow PostgreSQL to reach MinIO Gateway, it is necessary to create a +`ClusterIP` service on port `9000` bound to the MinIO Gateway instance. +!!! + +For example: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: minio-gateway-service +spec: + type: ClusterIP + ports: + - port: 9000 + targetPort: 9000 + protocol: TCP + selector: + app: minio +``` + +!!!warning + +At the time of writing this documentation, the official +[MinIO Operator](https://github.com/minio/minio-operator/issues/71) +for Kubernetes does not support the gateway feature. As such, we will use a +`deployment` instead. +!!! + +The MinIO deployment will use cloud storage credentials to upload objects to the +remote bucket and relay backup files to different locations. + +Here is an example using AWS S3 as Cloud Object Storage: + +```yaml +apiVersion: apps/v1 +kind: Deployment +[...] +spec: + containers: + - name: minio + image: minio/minio:RELEASE.2020-06-03T22-13-49Z + args: + - gateway + - s3 + env: + # MinIO access key and secret key + - name: MINIO_ACCESS_KEY + valueFrom: + secretKeyRef: + name: minio-creds + key: MINIO_ACCESS_KEY + - name: MINIO_SECRET_KEY + valueFrom: + secretKeyRef: + name: minio-creds + key: MINIO_SECRET_KEY + # AWS credentials + - name: AWS_ACCESS_KEY_ID + valueFrom: + secretKeyRef: + name: aws-creds + key: ACCESS_KEY_ID + - name: AWS_SECRET_ACCESS_KEY + valueFrom: + secretKeyRef: + name: aws-creds + key: ACCESS_SECRET_KEY +# Uncomment the below section if session token is required +# - name: AWS_SESSION_TOKEN +# valueFrom: +# secretKeyRef: +# name: aws-creds +# key: ACCESS_SESSION_TOKEN + ports: + - containerPort: 9000 +``` + +Proceed by configuring MinIO Gateway service as the `endpointURL` in the `Cluster` +definition, then choose a bucket name to replace `BUCKET_NAME`: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +[...] +spec: + backup: + barmanObjectStore: + destinationPath: s3://BUCKET_NAME/ + endpointURL: http://minio-gateway-service:9000 + s3Credentials: + accessKeyId: + name: minio-creds + key: MINIO_ACCESS_KEY + secretAccessKey: + name: minio-creds + key: MINIO_SECRET_KEY + [...] +``` + +Verify on `s3://BUCKET_NAME/` the presence of archived WAL files before +proceeding with a backup. diff --git a/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx b/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx index 4d0bdee91e..0a71e0ebf7 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx @@ -33,6 +33,10 @@ A project is a Kubernetes namespace with additional annotations, and is the central vehicle by which access to resources for regular users is managed. !!! +A project is a Kubernetes namespace with additional annotations, and is the +central vehicle by which access to resources for regular users is managed. +!!! + In most cases, the default cluster-wide installation of {{name.ln}} is the recommended one, with either central management of PostgreSQL clusters or delegated management (limited to specific users/projects according to RBAC @@ -216,8 +220,7 @@ each serving a distinct purpose: - `fast`: designed for users who want timely access to the latest stable features and patches. The head of the `fast` channel always points to the - latest **patch release** of the latest **minor release** of EDB Postgres for - Kubernetes. + latest **patch release** of the latest **minor release** of {{name.ln}}. - `stable`: similar to `fast`, but restricted to the latest **minor release** currently under EDB’s Long Term Support (LTS) policy. Designed for users who @@ -251,7 +254,7 @@ Please refer to ["Accessing EDB private image registries"](private_edb_registrie !!!warning CRITICAL WARNING: UPGRADING OPERATORS -OpenShift users, or any customer attempting an operator upgrade, MUST configure the new unified repository pull secret (docker.enterprisedb.com/k8s) before running the upgrade. If the old, deprecated repository path is still in use during the upgrade process, image pull failure will occur, leading to deployment failure and potential downtime. Follow the [Central Migration Guide](/repos/working_with_repos/migrating_edb_registries/) first. +OpenShift users, or any customer attempting an operator upgrade, MUST configure the new unified repository pull secret (docker.enterprisedb.com/k8s) before running the upgrade. If the old, deprecated repository path is still in use during the upgrade process, image pull failure will occur, leading to deployment failure and potential downtime. Follow the [Central Migration Guide](/postgres_for_kubernetes/latest/migrating_edb_registries) first. !!! The OpenShift install will use pull secrets in order to access the @@ -264,7 +267,7 @@ a pull secret in the `openshift-operators` namespace, named: You can create this secret using the `oc create` command by replacing `` with the repository token for your EDB account, as explained in -[Get your token](/repos/getting_started/get_your_token/). +[Get your token](/repos/getting_started/with_web/get_your_token/). ```sh oc create secret docker-registry postgresql-operator-pull-secret \ @@ -414,7 +417,7 @@ for information on how to install the `oc` command-line interface. !!!warning CRITICAL WARNING: UPGRADING OPERATORS -OpenShift users, or any customer attempting an operator upgrade, MUST configure the new unified repository pull secret (docker.enterprisedb.com/k8s) before running the upgrade. If the old, deprecated repository path is still in use during the upgrade process, image pull failure will occur, leading to deployment failure and potential downtime. Follow the [Central Migration Guide](/repos/working_with_repos/migrating_edb_registries/) first. +OpenShift users, or any customer attempting an operator upgrade, MUST configure the new unified repository pull secret (docker.enterprisedb.com/k8s) before running the upgrade. If the old, deprecated repository path is still in use during the upgrade process, image pull failure will occur, leading to deployment failure and potential downtime. Follow the [Central Migration Guide](/postgres_for_kubernetes/latest/migrating_edb_registries) first. !!! Instead of using the OpenShift Container Platform web console, you can install @@ -472,7 +475,10 @@ projects as you like or add/remove some namespaces. - bi-prod ``` - !!!info Important + :::info[Important] + Alternatively, you can list namespaces using a label selector, as explained in + ["Target namespace selection"](https://docs.openshift.com/container-platform/4.16/operators/understanding/olm/olm-understanding-operatorgroups.html#olm-operatorgroups-target-namespace_olm-understanding-operatorgroups). + ::: Alternatively, you can list namespaces using a label selector, as explained in ["Target namespace selection"](https://docs.openshift.com/container-platform/4.16/operators/understanding/olm/olm-understanding-operatorgroups.html#olm-operatorgroups-target-namespace_olm-understanding-operatorgroups). @@ -810,7 +816,7 @@ The above permissions are exclusively reserved for the operator's service account to interact with the Kubernetes API server. They are not directly accessible by the users of the operator that interact only with `Cluster`, `Pooler`, `Backup`, and `ScheduledBackup` resources (see -["Cluster roles on {{name.ln}} CRDs"](#cluster-roles-on-edb-postgres-ai-for-cloudnativepg-cluster-crds)). +["Cluster roles on {{name.ln}} CRDs"](#cluster-roles-on-edb-postgres-for-kubernetes-crds)). !!! The operator automates in a declarative way a lot of operations related to diff --git a/product_docs/docs/postgres_for_kubernetes/1/operator_capability_levels.mdx b/product_docs/docs/postgres_for_kubernetes/1/operator_capability_levels.mdx index 5fdbe783be..055c8dcf4a 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/operator_capability_levels.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/operator_capability_levels.mdx @@ -13,6 +13,7 @@ framework. ![Operator Capability Levels](./images/operator-capability-level.png) !!!info Important + Based on the [Operator Capability Levels model](operator_capability_levels.md), you can expect a "Level V - Auto Pilot" set of capabilities from the {{name.ln}} operator. @@ -27,6 +28,7 @@ Each capability level is associated with a certain set of management features th 5. Auto pilot !!!note + We consider this framework as a guide for future work and implementations in the operator. !!! @@ -38,6 +40,7 @@ enhancements, such as improvements in how you interact with the operator and a PostgreSQL cluster configuration. !!!info Important + We consider information security part of this level. !!! @@ -300,6 +303,7 @@ section of the PostgreSQL configuration. Depending on the configuration option, it also makes sure that all instances are properly reloaded or restarted. !!!note + Changes with `ALTER SYSTEM` aren't detected, meaning that the cluster state isn't enforced. !!! @@ -605,7 +609,12 @@ The operator allows you to scale up and down the number of instances in a PostgreSQL cluster. New replicas are started up from the primary server and participate in the cluster's HA infrastructure. The CRD declares a "scale" subresource that allows you to use the -`kubectl scale` command. +`kubectl scale` command. The scale subresource also publishes the label +selector of the managed instance pods, which lets autoscalers discover them. +See the [Vertical Pod Autoscaler integration](resource_management.md#integration-with-the-vertical-pod-autoscaler-vpa) +for the recommended use, and the +[Horizontal Pod Autoscaler integration](resource_management.md#integration-with-the-horizontal-pod-autoscaler-hpa) +for the caveats that apply to HPA. ### Maintenance window and PodDisruptionBudget for Kubernetes nodes @@ -654,6 +663,10 @@ to clone the data from the primary again. The operator allows administrators to control and manage resource usage by the cluster's pods in the `resources` section of the manifest. In particular, you can set `requests` and `limits` values for both CPU and RAM. +Because the `Cluster` exposes a label selector through its scale subresource, +it can also be used as a target for the +[Vertical Pod Autoscaler](resource_management.md#integration-with-the-vertical-pod-autoscaler-vpa) +in recommendation-only mode, to obtain sizing suggestions for these values. ### Connection pooling with PgBouncer diff --git a/product_docs/docs/postgres_for_kubernetes/1/operator_conf.mdx b/product_docs/docs/postgres_for_kubernetes/1/operator_conf.mdx index aa39c3c4bc..ead9b04e92 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/operator_conf.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/operator_conf.mdx @@ -20,6 +20,7 @@ By default, the operator is installed in the `postgresql-operator-system` namespace as a Kubernetes `Deployment` called `postgresql-operator-controller-manager`. !!!note + In the examples below we assume the default name and namespace for the operator deployment. !!! @@ -28,6 +29,7 @@ is located in the same namespace of the operator deployment and with `postgresql-operator-controller-manager-config` as the name. !!!info Important + Any change to the config's `ConfigMap`/`Secret` will not be automatically detected by the operator, - and as such, it needs to be reloaded (see below). Moreover, changes only apply to the resources created after the configuration @@ -35,6 +37,7 @@ is reloaded. !!! !!!info Important + The operator first processes the ConfigMap values and then the Secret’s, in this order. As a result, if a parameter is defined in both places, the one in the Secret will be used. !!! @@ -43,31 +46,29 @@ As a result, if a parameter is defined in both places, the one in the Secret wil The operator looks for the following environment variables to be defined in the `ConfigMap`/`Secret`: -| Name | Description | -| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `CERTIFICATE_DURATION` | Determines the lifetime of the generated certificates in days. Default is 90. | -| `CLUSTERS_ROLLOUT_DELAY` | The duration (in seconds) to wait between the roll-outs of different clusters during an operator upgrade. This setting controls the timing of upgrades across clusters, spreading them out to reduce system impact. The default value is `0` which means no delay between PostgreSQL cluster upgrades. | -| `CREATE_ANY_SERVICE` | When set to `true`, will create `-any` service for the cluster. Default is `false` | -| `DRAIN_TAINTS` | Specifies the taint keys that should be interpreted as indicators of node drain. By default, it includes the taints commonly applied by [kubectl](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/), [Cluster Autoscaler](https://github.com/kubernetes/autoscaler), and [Karpenter](https://github.com/aws/karpenter-provider-aws): `node.kubernetes.io/unschedulable`, `ToBeDeletedByClusterAutoscaler`, `karpenter.sh/disrupted`, `karpenter.sh/disruption`. | -| `EDB_LICENSE_KEY` | Default license key (to be used only if the cluster does not define one, and preferably in the `Secret`) | -| `ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES` | When set to `true`, enables in-place updates of the instance manager after an update of the operator, avoiding rolling updates of the cluster (default `false`) | -| `ENABLE_REDWOOD_BY_DEFAULT` | Enable the Redwood compatibility by default when using EPAS. | -| `EXPIRING_CHECK_THRESHOLD` | Determines the threshold, in days, for identifying a certificate as expiring. Default is 7. | -| `EXTERNAL_BACKUP_ADDON_CONFIGURATION` | Configuration for the `external-backup-adapter` add-on. (See ["Customizing the adapter" in Add-ons](addons.md#customizing-the-adapter)) | -| `INCLUDE_PLUGINS` | A comma-separated list of plugins to be always included in the Cluster's reconciliation. | -| `INHERITED_ANNOTATIONS` | List of annotation names that, when defined in a `Cluster` metadata, will be inherited by all the generated resources, including pods | -| `INHERITED_LABELS` | List of label names that, when defined in a `Cluster` metadata, will be inherited by all the generated resources, including pods | -| `INSTANCES_ROLLOUT_DELAY` | The duration (in seconds) to wait between roll-outs of individual PostgreSQL instances within the same cluster during an operator upgrade. The default value is `0`, meaning no delay between upgrades of instances in the same PostgreSQL cluster. | -| `KUBERNETES_CLUSTER_DOMAIN` | Defines the domain suffix for service FQDNs within the Kubernetes cluster. If left unset, it defaults to "cluster.local". | -| `METRICS_CERT_DIR` | The directory where TLS certificates for the operator metrics server are stored. When set, enables TLS for the metrics endpoint on port 8080. The directory must contain `tls.crt` and `tls.key` files following standard Kubernetes TLS secret conventions. If not set, the metrics server operates without TLS (default behavior). | -| `MONITORING_QUERIES_CONFIGMAP` | The name of a ConfigMap in the operator's namespace with a set of default queries (to be specified under the key `queries`) to be applied to all created Clusters | -| `MONITORING_QUERIES_SECRET` | The name of a Secret in the operator's namespace with a set of default queries (to be specified under the key `queries`) to be applied to all created Clusters | -| `OPERATOR_IMAGE_NAME` | The name of the operator image used to bootstrap Pods. Defaults to the image specified during installation. | -| `PGBOUNCER_IMAGE_NAME` | The name of the PgBouncer image used by default for new poolers. Defaults to the version specified in the operator. | -| `POSTGRES_IMAGE_NAME` | The name of the PostgreSQL image used by default for new clusters. Defaults to the version specified in the operator. | -| `PULL_SECRET_NAME` | Name of an additional pull secret to be defined in the operator's namespace and to be used to download images | -| `STANDBY_TCP_USER_TIMEOUT` | Defines the [`TCP_USER_TIMEOUT` socket option](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-TCP-USER-TIMEOUT) in milliseconds for replication connections from standby instances to the primary. Default is 5000 (5 seconds). Set to `0` to use the system's default. | -| `WATCH_NAMESPACE` | Specifies the namespace(s) where the operator should watch for resources. Multiple namespaces can be specified separated by commas. If not set, the operator watches all namespaces (cluster-wide mode). | +| Name | Description | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `CERTIFICATE_DURATION` | Determines the lifetime of the generated certificates in days. Default is 90. | +| `CLUSTERS_ROLLOUT_DELAY` | The duration (in seconds) to wait between the roll-outs of different clusters during an operator upgrade. This setting controls the timing of upgrades across clusters, spreading them out to reduce system impact. The default value is `0` which means no delay between PostgreSQL cluster upgrades. | +| `CREATE_ANY_SERVICE` | When set to `true`, will create `-any` service for the cluster. Default is `false` | +| `EDB_LICENSE_KEY` | Default license key (to be used only if the cluster does not define one, and preferably in the `Secret`) | +| `ENABLE_AZURE_PVC_UPDATES` | Enables to delete Postgres pod if its PVC is stuck in Resizing condition. This feature is mainly for the Azure environment (default `false`) | +| `ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES` | When set to `true`, enables in-place updates of the instance manager after an update of the operator, avoiding rolling updates of the cluster (default `false`) | +| `ENABLE_REDWOOD_BY_DEFAULT` | Enable the Redwood compatibility by default when using EPAS. | +| `EXPIRING_CHECK_THRESHOLD` | Determines the threshold, in days, for identifying a certificate as expiring. Default is 7. | +| `EXTERNAL_BACKUP_ADDON_CONFIGURATION` | Configuration for the `external-backup-adapter` add-on. (See ["Customizing the adapter" in Add-ons](addons.md#customizing-the-adapter)) | +| `INCLUDE_PLUGINS` | A comma-separated list of plugins to be always included in the Cluster's reconciliation. | +| `INHERITED_ANNOTATIONS` | List of annotation names that, when defined in a `Cluster` metadata, will be inherited by all the generated resources, including pods | +| `INHERITED_LABELS` | List of label names that, when defined in a `Cluster` metadata, will be inherited by all the generated resources, including pods | +| `INSTANCES_ROLLOUT_DELAY` | The duration (in seconds) to wait between roll-outs of individual PostgreSQL instances within the same cluster during an operator upgrade. The default value is `0`, meaning no delay between upgrades of instances in the same PostgreSQL cluster. | +| `KUBERNETES_CLUSTER_DOMAIN` | Defines the domain suffix for service FQDNs within the Kubernetes cluster. If left unset, it defaults to "cluster.local". | +| `MONITORING_QUERIES_CONFIGMAP` | The name of a ConfigMap in the operator's namespace with a set of default queries (to be specified under the key `queries`) to be applied to all created Clusters | +| `MONITORING_QUERIES_SECRET` | The name of a Secret in the operator's namespace with a set of default queries (to be specified under the key `queries`) to be applied to all created Clusters | +| `OPERATOR_IMAGE_NAME` | The name of the operator image used to bootstrap Pods. Defaults to the image specified during installation. | +| `PGBOUNCER_IMAGE_NAME` | The name of the PgBouncer image used by default for new poolers. Defaults to the version specified in the operator. | +| `POSTGRES_IMAGE_NAME` | The name of the PostgreSQL image used by default for new clusters. Defaults to the version specified in the operator. | +| `PULL_SECRET_NAME` | Name of an additional pull secret to be defined in the operator's namespace and to be used to download images | +| `WATCH_NAMESPACE` | Specifies the namespace(s) where the operator should watch for resources. Multiple namespaces can be specified separated by commas. If not set, the operator watches all namespaces (cluster-wide mode). | Values in `INHERITED_ANNOTATIONS` and `INHERITED_LABELS` support path-like wildcards. For example, the value `example.com/*` will match both the value `example.com/one` and `example.com/two`. @@ -153,6 +154,7 @@ kubectl delete pods -n [NAMESPACE_NAME_HERE] \ ``` !!!warning + Customizations will be applied only to `Cluster` resources created after the reload of the operator deployment. !!! @@ -190,6 +192,7 @@ After saving, the deployment will roll out and the new pod will have the pprof server enabled. !!!info Important + The pprof server only serves plain HTTP on port `6060`. !!! @@ -205,6 +208,7 @@ go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30 You can also access pprof using the browser at . !!!warning + The example above uses `kubectl port-forward` for local testing only. This is **not** the intended way to expose the feature in production. Treat pprof as a sensitive debugging interface and never expose it publicly. diff --git a/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.25.9.mdx b/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.25.9.mdx new file mode 100644 index 0000000000..f7036961e1 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.25.9.mdx @@ -0,0 +1,2366 @@ +--- +title: API Reference - v1.25.9 +navTitle: v1.25.9 +pdfExclude: 'true' + +--- + +## Packages + +- [postgresql.k8s.enterprisedb.io/v1](#postgresqlk8senterprisedbiov1) + +## postgresql.k8s.enterprisedb.io/v1 + +Package v1 contains API Schema definitions for the postgresql v1 API group + +### Resource Types + +- [Backup](#backup) +- [Cluster](#cluster) +- [ClusterImageCatalog](#clusterimagecatalog) +- [Database](#database) +- [FailoverQuorum](#failoverquorum) +- [ImageCatalog](#imagecatalog) +- [Pooler](#pooler) +- [Publication](#publication) +- [ScheduledBackup](#scheduledbackup) +- [Subscription](#subscription) + +#### AffinityConfiguration + +AffinityConfiguration contains the info we need to create the +affinity rules for Pods + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ---------- | +| `enablePodAntiAffinity` *boolean* | Activates anti-affinity for the pods. The operator will define pods
anti-affinity unless this field is explicitly set to false | | | | +| `topologyKey` *string* | TopologyKey to use for anti-affinity configuration. See k8s documentation
for more info on that | | | | +| `nodeSelector` *object (keys:string, values:string)* | NodeSelector is map of key-value pairs used to define the nodes on which
the pods can run.
More info: | | | | +| `nodeAffinity` *[NodeAffinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#nodeaffinity-v1-core)* | NodeAffinity describes node affinity scheduling rules for the pod.
More info: | | | | +| `tolerations` *[Toleration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#toleration-v1-core) array* | Tolerations is a list of Tolerations that should be set for all the pods, in order to allow them to run
on tainted nodes.
More info: | | | | +| `podAntiAffinityType` *string* | PodAntiAffinityType allows the user to decide whether pod anti-affinity between cluster instance has to be
considered a strong requirement during scheduling or not. Allowed values are: "preferred" (default if empty) or
"required". Setting it to "required", could lead to instances remaining pending until new kubernetes nodes are
added if all the existing nodes don't match the required pod anti-affinity rule.
More info:
| | | | +| `additionalPodAntiAffinity` *[PodAntiAffinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#podantiaffinity-v1-core)* | AdditionalPodAntiAffinity allows to specify pod anti-affinity terms to be added to the ones generated
by the operator if EnablePodAntiAffinity is set to true (default) or to be used exclusively if set to false. | | | | +| `additionalPodAffinity` *[PodAffinity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#podaffinity-v1-core)* | AdditionalPodAffinity allows to specify pod affinity terms to be passed to all the cluster's pods. | | | | + +#### AvailableArchitecture + +AvailableArchitecture represents the state of a cluster's architecture + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ----------------- | ------------------------------------------------- | -------- | ------- | ---------- | +| `goArch` *string* | GoArch is the name of the executable architecture | True | | | +| `hash` *string* | Hash is the hash of the executable | True | | | + +#### Backup + +A Backup resource is a request for a PostgreSQL backup by the user. + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `Backup` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[BackupSpec](#backupspec)* | Specification of the desired behavior of the backup.
More info: | True | | | +| `status` *[BackupStatus](#backupstatus)* | Most recently observed status of the backup. This data may not be up to
date. Populated by the system. Read-only.
More info: | | | | + +#### BackupConfiguration + +BackupConfiguration defines how the backup of the cluster are taken. +The supported backup methods are BarmanObjectStore and VolumeSnapshot. +For details and examples refer to the Backup and Recovery section of the +documentation + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------- | +| `volumeSnapshot` *[VolumeSnapshotConfiguration](#volumesnapshotconfiguration)* | VolumeSnapshot provides the configuration for the execution of volume snapshot backups. | | | | +| `barmanObjectStore` *[BarmanObjectStoreConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)* | The configuration for the barman-cloud tool suite | | | | +| `retentionPolicy` *string* | RetentionPolicy is the retention policy to be used for backups
and WALs (i.e. '60d'). The retention policy is expressed in the form
of `XXu` where `XX` is a positive integer and `u` is in `[dwm]` -
days, weeks, months.
It's currently only applicable when using the BarmanObjectStore method. | | | Pattern: `^[1-9][0-9]*[dwm]$`
| +| `target` *[BackupTarget](#backuptarget)* | The policy to decide which instance should perform backups. Available
options are empty string, which will default to `prefer-standby` policy,
`primary` to have backups run always on primary instances, `prefer-standby`
to have backups run preferably on the most updated standby, if available. | | | Enum: [primary prefer-standby]
| + +#### BackupMethod + +*Underlying type:* *string* + +BackupMethod defines the way of executing the physical base backups of +the selected PostgreSQL instance + +*Appears in:* + +- [BackupSpec](#backupspec) +- [BackupStatus](#backupstatus) +- [ClusterStatus](#clusterstatus) +- [ScheduledBackupSpec](#scheduledbackupspec) + +| Field | Description | +| ------------------- | -------------------------------------------------------------------------------------------- | +| `volumeSnapshot` | BackupMethodVolumeSnapshot means using the volume snapshot
Kubernetes feature
| +| `barmanObjectStore` | BackupMethodBarmanObjectStore means using barman to backup the
PostgreSQL cluster
| +| `plugin` | BackupMethodPlugin means that this backup should be handled by
a plugin
| + +#### BackupPhase + +*Underlying type:* *string* + +BackupPhase is the phase of the backup + +*Appears in:* + +- [BackupStatus](#backupstatus) + +#### BackupPluginConfiguration + +BackupPluginConfiguration contains the backup configuration used by +the backup plugin + +*Appears in:* + +- [BackupSpec](#backupspec) +- [ScheduledBackupSpec](#scheduledbackupspec) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `name` *string* | Name is the name of the plugin managing this backup | True | | | +| `parameters` *object (keys:string, values:string)* | Parameters are the configuration parameters passed to the backup
plugin for this backup | | | | + +#### BackupSnapshotElementStatus + +BackupSnapshotElementStatus is a volume snapshot that is part of a volume snapshot method backup + +*Appears in:* + +- [BackupSnapshotStatus](#backupsnapshotstatus) + +| Field | Description | Required | Default | Validation | +| ------------------------- | -------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `name` *string* | Name is the snapshot resource name | True | | | +| `type` *string* | Type is tho role of the snapshot in the cluster, such as PG_DATA, PG_WAL and PG_TABLESPACE | True | | | +| `tablespaceName` *string* | TablespaceName is the name of the snapshotted tablespace. Only set
when type is PG_TABLESPACE | | | | + +#### BackupSnapshotStatus + +BackupSnapshotStatus the fields exclusive to the volumeSnapshot method backup + +*Appears in:* + +- [BackupStatus](#backupstatus) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------ | --------------------------------------------------------------- | -------- | ------- | ---------- | +| `elements` *[BackupSnapshotElementStatus](#backupsnapshotelementstatus) array* | The elements list, populated with the gathered volume snapshots | | | | + +#### BackupSource + +BackupSource contains the backup we need to restore from, plus some +information that could be needed to correctly restore it. + +*Appears in:* + +- [BootstrapRecovery](#bootstraprecovery) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `name` *string* | Name of the referent. | True | | | +| `endpointCA` *[SecretKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#SecretKeySelector)* | EndpointCA store the CA bundle of the barman endpoint.
Useful when using self-signed certificates to avoid
errors with certificate issuer and barman-cloud-wal-archive. | | | | + +#### BackupSpec + +BackupSpec defines the desired state of Backup + +*Appears in:* + +- [Backup](#backup) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | ------------------------------------------------------ | +| `cluster` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | The cluster to backup | True | | | +| `target` *[BackupTarget](#backuptarget)* | The policy to decide which instance should perform this backup. If empty,
it defaults to `cluster.spec.backup.target`.
Available options are empty string, `primary` and `prefer-standby`.
`primary` to have backups run always on primary instances,
`prefer-standby` to have backups run preferably on the most updated
standby, if available. | | | Enum: [primary prefer-standby]
| +| `method` *[BackupMethod](#backupmethod)* | The backup method to be used, possible options are `barmanObjectStore`,
`volumeSnapshot` or `plugin`. Defaults to: `barmanObjectStore`. | | barmanObjectStore | Enum: [barmanObjectStore volumeSnapshot plugin]
| +| `pluginConfiguration` *[BackupPluginConfiguration](#backuppluginconfiguration)* | Configuration parameters passed to the plugin managing this backup | | | | +| `online` *boolean* | Whether the default type of backup with volume snapshots is
online/hot (`true`, default) or offline/cold (`false`)
Overrides the default setting specified in the cluster field '.spec.backup.volumeSnapshot.online' | | | | +| `onlineConfiguration` *[OnlineConfiguration](#onlineconfiguration)* | Configuration parameters to control the online/hot backup with volume snapshots
Overrides the default settings specified in the cluster '.backup.volumeSnapshot.onlineConfiguration' stanza | | | | + +#### BackupStatus + +BackupStatus defines the observed state of Backup + +*Appears in:* + +- [Backup](#backup) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `googleCredentials` *[GoogleCredentials](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#GoogleCredentials)* | The credentials to use to upload data to Google Cloud Storage | | | | +| `s3Credentials` *[S3Credentials](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#S3Credentials)* | The credentials to use to upload data to S3 | | | | +| `azureCredentials` *[AzureCredentials](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#AzureCredentials)* | The credentials to use to upload data to Azure Blob Storage | | | | +| `majorVersion` *integer* | The PostgreSQL major version that was running when the
backup was taken. | True | | | +| `endpointCA` *[SecretKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#SecretKeySelector)* | EndpointCA store the CA bundle of the barman endpoint.
Useful when using self-signed certificates to avoid
errors with certificate issuer and barman-cloud-wal-archive. | | | | +| `endpointURL` *string* | Endpoint to be used to upload data to the cloud,
overriding the automatic endpoint discovery | | | | +| `destinationPath` *string* | The path where to store the backup (i.e. s3://bucket/path/to/folder)
this path, with different destination folders, will be used for WALs
and for data. This may not be populated in case of errors. | | | | +| `serverName` *string* | The server name on S3, the cluster name is used if this
parameter is omitted | | | | +| `encryption` *string* | Encryption method required to S3 API | | | | +| `backupId` *string* | The ID of the Barman backup | | | | +| `backupName` *string* | The Name of the Barman backup | | | | +| `phase` *[BackupPhase](#backupphase)* | The last backup status | | | | +| `startedAt` *[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta)* | When the backup was started | | | | +| `stoppedAt` *[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta)* | When the backup was terminated | | | | +| `beginWal` *string* | The starting WAL | | | | +| `endWal` *string* | The ending WAL | | | | +| `beginLSN` *string* | The starting xlog | | | | +| `endLSN` *string* | The ending xlog | | | | +| `error` *string* | The detected error | | | | +| `commandOutput` *string* | Unused. Retained for compatibility with old versions. | | | | +| `commandError` *string* | The backup command output in case of error | | | | +| `backupLabelFile` *integer array* | Backup label file content as returned by Postgres in case of online (hot) backups | | | | +| `tablespaceMapFile` *integer array* | Tablespace map file content as returned by Postgres in case of online (hot) backups | | | | +| `instanceID` *[InstanceID](#instanceid)* | Information to identify the instance where the backup has been taken from | | | | +| `snapshotBackupStatus` *[BackupSnapshotStatus](#backupsnapshotstatus)* | Status of the volumeSnapshot backup | | | | +| `method` *[BackupMethod](#backupmethod)* | The backup method being used | | | | +| `online` *boolean* | Whether the backup was online/hot (`true`) or offline/cold (`false`) | | | | +| `pluginMetadata` *object (keys:string, values:string)* | A map containing the plugin metadata | | | | + +#### BackupTarget + +*Underlying type:* *string* + +BackupTarget describes the preferred targets for a backup + +*Appears in:* + +- [BackupConfiguration](#backupconfiguration) +- [BackupSpec](#backupspec) +- [ScheduledBackupSpec](#scheduledbackupspec) + +#### BootstrapConfiguration + +BootstrapConfiguration contains information about how to create the PostgreSQL +cluster. Only a single bootstrap method can be defined among the supported +ones. `initdb` will be used as the bootstrap method if left +unspecified. Refer to the Bootstrap page of the documentation for more +information. + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `initdb` *[BootstrapInitDB](#bootstrapinitdb)* | Bootstrap the cluster via initdb | | | | +| `recovery` *[BootstrapRecovery](#bootstraprecovery)* | Bootstrap the cluster from a backup | | | | +| `pg_basebackup` *[BootstrapPgBaseBackup](#bootstrappgbasebackup)* | Bootstrap the cluster taking a physical backup of another compatible
PostgreSQL instance | | | | + +#### BootstrapInitDB + +BootstrapInitDB is the configuration of the bootstrap process when +initdb is used +Refer to the Bootstrap page of the documentation for more information. + +*Appears in:* + +- [BootstrapConfiguration](#bootstrapconfiguration) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------- | +| `database` *string* | Name of the database used by the application. Default: `app`. | | | | +| `owner` *string* | Name of the owner of the database in the instance to be used
by applications. Defaults to the value of the `database` key. | | | | +| `secret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | Name of the secret containing the initial credentials for the
owner of the user database. If empty a new secret will be
created from scratch | | | | +| `redwood` *boolean* | If we need to enable/disable Redwood compatibility. Requires
EPAS and for EPAS defaults to true | | | | +| `options` *string array* | The list of options that must be passed to initdb when creating the cluster.
Deprecated: This could lead to inconsistent configurations,
please use the explicit provided parameters instead.
If defined, explicit values will be ignored. | | | | +| `dataChecksums` *boolean* | Whether the `-k` option should be passed to initdb,
enabling checksums on data pages (default: `false`) | | | | +| `encoding` *string* | The value to be passed as option `--encoding` for initdb (default:`UTF8`) | | | | +| `localeCollate` *string* | The value to be passed as option `--lc-collate` for initdb (default:`C`) | | | | +| `localeCType` *string* | The value to be passed as option `--lc-ctype` for initdb (default:`C`) | | | | +| `locale` *string* | Sets the default collation order and character classification in the new database. | | | | +| `localeProvider` *string* | This option sets the locale provider for databases created in the new cluster.
Available from PostgreSQL 16. | | | | +| `icuLocale` *string* | Specifies the ICU locale when the ICU provider is used.
This option requires `localeProvider` to be set to `icu`.
Available from PostgreSQL 15. | | | | +| `icuRules` *string* | Specifies additional collation rules to customize the behavior of the default collation.
This option requires `localeProvider` to be set to `icu`.
Available from PostgreSQL 16. | | | | +| `builtinLocale` *string* | Specifies the locale name when the builtin provider is used.
This option requires `localeProvider` to be set to `builtin`.
Available from PostgreSQL 17. | | | | +| `walSegmentSize` *integer* | The value in megabytes (1 to 1024) to be passed to the `--wal-segsize`
option for initdb (default: empty, resulting in PostgreSQL default: 16MB) | | | Maximum: 1024
Minimum: 1
| +| `postInitSQL` *string array* | List of SQL queries to be executed as a superuser in the `postgres`
database right after the cluster has been created - to be used with extreme care
(by default empty) | | | | +| `postInitApplicationSQL` *string array* | List of SQL queries to be executed as a superuser in the application
database right after the cluster has been created - to be used with extreme care
(by default empty) | | | | +| `postInitTemplateSQL` *string array* | List of SQL queries to be executed as a superuser in the `template1`
database right after the cluster has been created - to be used with extreme care
(by default empty) | | | | +| `import` *[Import](#import)* | Bootstraps the new cluster by importing data from an existing PostgreSQL
instance using logical backup (`pg_dump` and `pg_restore`) | | | | +| `postInitApplicationSQLRefs` *[SQLRefs](#sqlrefs)* | List of references to ConfigMaps or Secrets containing SQL files
to be executed as a superuser in the application database right after
the cluster has been created. The references are processed in a specific order:
first, all Secrets are processed, followed by all ConfigMaps.
Within each group, the processing order follows the sequence specified
in their respective arrays.
(by default empty) | | | | +| `postInitTemplateSQLRefs` *[SQLRefs](#sqlrefs)* | List of references to ConfigMaps or Secrets containing SQL files
to be executed as a superuser in the `template1` database right after
the cluster has been created. The references are processed in a specific order:
first, all Secrets are processed, followed by all ConfigMaps.
Within each group, the processing order follows the sequence specified
in their respective arrays.
(by default empty) | | | | +| `postInitSQLRefs` *[SQLRefs](#sqlrefs)* | List of references to ConfigMaps or Secrets containing SQL files
to be executed as a superuser in the `postgres` database right after
the cluster has been created. The references are processed in a specific order:
first, all Secrets are processed, followed by all ConfigMaps.
Within each group, the processing order follows the sequence specified
in their respective arrays.
(by default empty) | | | | + +#### BootstrapPgBaseBackup + +BootstrapPgBaseBackup contains the configuration required to take +a physical backup of an existing PostgreSQL cluster + +*Appears in:* + +- [BootstrapConfiguration](#bootstrapconfiguration) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ------------------- | +| `source` *string* | The name of the server of which we need to take a physical backup | True | | MinLength: 1
| +| `database` *string* | Name of the database used by the application. Default: `app`. | | | | +| `owner` *string* | Name of the owner of the database in the instance to be used
by applications. Defaults to the value of the `database` key. | | | | +| `secret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | Name of the secret containing the initial credentials for the
owner of the user database. If empty a new secret will be
created from scratch | | | | + +#### BootstrapRecovery + +BootstrapRecovery contains the configuration required to restore +from an existing cluster using 3 methodologies: external cluster, +volume snapshots or backup objects. Full recovery and Point-In-Time +Recovery are supported. +The method can be also be used to create clusters in continuous recovery +(replica clusters), also supporting cascading replication when `instances` > + +1. Once the cluster exits recovery, the password for the superuser + will be changed through the provided secret. + Refer to the Bootstrap page of the documentation for more information. + +*Appears in:* + +- [BootstrapConfiguration](#bootstrapconfiguration) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `backup` *[BackupSource](#backupsource)* | The backup object containing the physical base backup from which to
initiate the recovery procedure.
Mutually exclusive with `source` and `volumeSnapshots`. | | | | +| `source` *string* | The external cluster whose backup we will restore. This is also
used as the name of the folder under which the backup is stored,
so it must be set to the name of the source cluster
Mutually exclusive with `backup`. | | | | +| `volumeSnapshots` *[DataSource](#datasource)* | The static PVC data source(s) from which to initiate the
recovery procedure. Currently supporting `VolumeSnapshot`
and `PersistentVolumeClaim` resources that map an existing
PVC group, compatible with {{name.ln}}, and taken with
a cold backup copy on a fenced Postgres instance (limitation
which will be removed in the future when online backup
will be implemented).
Mutually exclusive with `backup`. | | | | +| `recoveryTarget` *[RecoveryTarget](#recoverytarget)* | By default, the recovery process applies all the available
WAL files in the archive (full recovery). However, you can also
end the recovery as soon as a consistent state is reached or
recover to a point-in-time (PITR) by specifying a `RecoveryTarget` object,
as expected by PostgreSQL (i.e., timestamp, transaction Id, LSN, ...).
More info: | | | | +| `database` *string* | Name of the database used by the application. Default: `app`. | | | | +| `owner` *string* | Name of the owner of the database in the instance to be used
by applications. Defaults to the value of the `database` key. | | | | +| `secret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | Name of the secret containing the initial credentials for the
owner of the user database. If empty a new secret will be
created from scratch | | | | + +#### CatalogComponentImage + +CatalogComponentImage is a named image entry for a non-PostgreSQL component. + +*Appears in:* + +- [ImageCatalogSpec](#imagecatalogspec) + +| Field | Description | Required | Default | Validation | +| ---------------- | --------------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------- | +| `key` *string* | Key is the unique identifier for this image within the catalog. | True | | MaxLength: 63
Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
| +| `image` *string* | Image is the container image reference. | True | | | + +#### CatalogImage + +CatalogImage defines the image and major version + +*Appears in:* + +- [ImageCatalogSpec](#imagecatalogspec) + +| Field | Description | Required | Default | Validation | +| ----------------- | ----------------------------------------------------------------------------- | -------- | ------- | ------------------ | +| `image` *string* | The image reference | True | | | +| `major` *integer* | The PostgreSQL major version of the image. Must be unique within the catalog. | True | | Minimum: 10
| + +#### CertificatesConfiguration + +CertificatesConfiguration contains the needed configurations to handle server certificates. + +*Appears in:* + +- [CertificatesStatus](#certificatesstatus) +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `serverCASecret` *string* | The secret containing the Server CA certificate. If not defined, a new secret will be created
with a self-signed CA and will be used to generate the TLS certificate ServerTLSSecret.

Contains:

- `ca.crt`: CA that should be used to validate the server certificate,
used as `sslrootcert` in client connection strings.
- `ca.key`: key used to generate Server SSL certs, if ServerTLSSecret is provided,
this can be omitted.
| | | | +| `serverTLSSecret` *string* | The secret of type kubernetes.io/tls containing the server TLS certificate and key that will be set as
`ssl_cert_file` and `ssl_key_file` so that clients can connect to postgres securely.
If not defined, ServerCASecret must provide also `ca.key` and a new secret will be
created using the provided CA. | | | | +| `replicationTLSSecret` *string* | The secret of type kubernetes.io/tls containing the client certificate to authenticate as
the `streaming_replica` user.
If not defined, ClientCASecret must provide also `ca.key`, and a new secret will be
created using the provided CA. | | | | +| `clientCASecret` *string* | The secret containing the Client CA certificate. If not defined, a new secret will be created
with a self-signed CA and will be used to generate all the client certificates.

Contains:

- `ca.crt`: CA that should be used to validate the client certificates,
used as `ssl_ca_file` of all the instances.
- `ca.key`: key used to generate client certificates, if ReplicationTLSSecret is provided,
this can be omitted.
| | | | +| `serverAltDNSNames` *string array* | The list of the server alternative DNS names to be added to the generated server TLS certificates, when required. | | | | + +#### CertificatesStatus + +CertificatesStatus contains configuration certificates and related expiration dates. + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `serverCASecret` *string* | The secret containing the Server CA certificate. If not defined, a new secret will be created
with a self-signed CA and will be used to generate the TLS certificate ServerTLSSecret.

Contains:

- `ca.crt`: CA that should be used to validate the server certificate,
used as `sslrootcert` in client connection strings.
- `ca.key`: key used to generate Server SSL certs, if ServerTLSSecret is provided,
this can be omitted.
| | | | +| `serverTLSSecret` *string* | The secret of type kubernetes.io/tls containing the server TLS certificate and key that will be set as
`ssl_cert_file` and `ssl_key_file` so that clients can connect to postgres securely.
If not defined, ServerCASecret must provide also `ca.key` and a new secret will be
created using the provided CA. | | | | +| `replicationTLSSecret` *string* | The secret of type kubernetes.io/tls containing the client certificate to authenticate as
the `streaming_replica` user.
If not defined, ClientCASecret must provide also `ca.key`, and a new secret will be
created using the provided CA. | | | | +| `clientCASecret` *string* | The secret containing the Client CA certificate. If not defined, a new secret will be created
with a self-signed CA and will be used to generate all the client certificates.

Contains:

- `ca.crt`: CA that should be used to validate the client certificates,
used as `ssl_ca_file` of all the instances.
- `ca.key`: key used to generate client certificates, if ReplicationTLSSecret is provided,
this can be omitted.
| | | | +| `serverAltDNSNames` *string array* | The list of the server alternative DNS names to be added to the generated server TLS certificates, when required. | | | | +| `expirations` *object (keys:string, values:string)* | Expiration dates for all certificates. | | | | + +#### Cluster + +Cluster defines the API schema for a highly available PostgreSQL database cluster +managed by {{name.ln}}. + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `Cluster` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[ClusterSpec](#clusterspec)* | Specification of the desired behavior of the cluster.
More info: | True | | | +| `status` *[ClusterStatus](#clusterstatus)* | Most recently observed status of the cluster. This data may not be up
to date. Populated by the system. Read-only.
More info: | | | | + +#### ClusterImageCatalog + +ClusterImageCatalog is the Schema for the clusterimagecatalogs API + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `ClusterImageCatalog` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[ImageCatalogSpec](#imagecatalogspec)* | Specification of the desired behavior of the ClusterImageCatalog.
More info: | True | | | + +#### ClusterMonitoringTLSConfiguration + +ClusterMonitoringTLSConfiguration is the type containing the TLS configuration +for the cluster's monitoring + +*Appears in:* + +- [MonitoringConfiguration](#monitoringconfiguration) + +| Field | Description | Required | Default | Validation | +| ------------------- | -------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `enabled` *boolean* | Enable TLS for the monitoring endpoint.
Changing this option will force a rollout of all instances. | | false | | + +#### ClusterSpec + +ClusterSpec defines the desired state of a PostgreSQL cluster managed by +{{name.ln}}. + +*Appears in:* + +- [Cluster](#cluster) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------ | --------------------------------------------- | +| `description` *string* | Description of this PostgreSQL cluster | | | | +| `inheritedMetadata` *[EmbeddedObjectMetadata](#embeddedobjectmetadata)* | Metadata that will be inherited by all objects related to the Cluster | | | | +| `imageName` *string* | Name of the container image, supporting both tags (`:`)
and digests for deterministic and repeatable deployments
(`:@sha256:`) | | | | +| `imageCatalogRef` *[ImageCatalogRef](#imagecatalogref)* | Defines the major PostgreSQL version we want to use within an ImageCatalog | | | | +| `imagePullPolicy` *[PullPolicy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#pullpolicy-v1-core)* | Image pull policy.
One of `Always`, `Never` or `IfNotPresent`.
If not defined, it defaults to `IfNotPresent`.
Cannot be updated.
More info: | | | | +| `schedulerName` *string* | If specified, the pod will be dispatched by specified Kubernetes
scheduler. If not specified, the pod will be dispatched by the default
scheduler. More info:
| | | | +| `postgresUID` *integer* | The UID of the `postgres` user inside the image, defaults to `26` | | 26 | | +| `postgresGID` *integer* | The GID of the `postgres` user inside the image, defaults to `26` | | 26 | | +| `instances` *integer* | Number of instances required in the cluster | True | 1 | Minimum: 1
| +| `minSyncReplicas` *integer* | Minimum number of instances required in synchronous replication with the
primary. Undefined or 0 allow writes to complete when no standby is
available. | | 0 | Minimum: 0
| +| `maxSyncReplicas` *integer* | The target value for the synchronous replication quorum, that can be
decreased if the number of ready standbys is lower than this.
Undefined or 0 disable synchronous replication. | | 0 | Minimum: 0
| +| `postgresql` *[PostgresConfiguration](#postgresconfiguration)* | Configuration of the PostgreSQL server | | | | +| `replicationSlots` *[ReplicationSlotsConfiguration](#replicationslotsconfiguration)* | Replication slots management configuration | | | | +| `bootstrap` *[BootstrapConfiguration](#bootstrapconfiguration)* | Instructions to bootstrap this cluster | | | | +| `replica` *[ReplicaClusterConfiguration](#replicaclusterconfiguration)* | Replica cluster configuration | | | | +| `superuserSecret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | The secret containing the superuser password. If not defined a new
secret will be created with a randomly generated password | | | | +| `enableSuperuserAccess` *boolean* | When this option is enabled, the operator will use the `SuperuserSecret`
to update the `postgres` user password (if the secret is
not present, the operator will automatically create one). When this
option is disabled, the operator will ignore the `SuperuserSecret` content, delete
it when automatically created, and then blank the password of the `postgres`
user by setting it to `NULL`. Disabled by default. | | | | +| `certificates` *[CertificatesConfiguration](#certificatesconfiguration)* | The configuration for the CA and related certificates | | | | +| `imagePullSecrets` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference) array* | The list of pull secrets to be used to pull the images. If the license key
contains a pull secret that secret will be automatically included. | | | | +| `storage` *[StorageConfiguration](#storageconfiguration)* | Configuration of the storage of the instances | | | | +| `serviceAccountTemplate` *[ServiceAccountTemplate](#serviceaccounttemplate)* | Configure the generation of the service account | | | | +| `walStorage` *[StorageConfiguration](#storageconfiguration)* | Configuration of the storage for PostgreSQL WAL (Write-Ahead Log) | | | | +| `ephemeralVolumeSource` *[EphemeralVolumeSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#ephemeralvolumesource-v1-core)* | EphemeralVolumeSource allows the user to configure the source of ephemeral volumes. | | | | +| `startDelay` *integer* | The time in seconds that is allowed for a PostgreSQL instance to
successfully start up (default 3600).
The startup probe failure threshold is derived from this value using the formula:
ceiling(startDelay / 10). | | 3600 | | +| `stopDelay` *integer* | The time in seconds that is allowed for a PostgreSQL instance to
gracefully shutdown (default 1800) | | 1800 | | +| `smartStopDelay` *integer* | Deprecated: please use SmartShutdownTimeout instead | | | | +| `smartShutdownTimeout` *integer* | The time in seconds that controls the window of time reserved for the smart shutdown of Postgres to complete.
Make sure you reserve enough time for the operator to request a fast shutdown of Postgres
(that is: `stopDelay` - `smartShutdownTimeout`). Default is 180 seconds. | | 180 | | +| `switchoverDelay` *integer* | The time in seconds that is allowed for a primary PostgreSQL instance
to gracefully shutdown during a switchover.
Default value is 3600 seconds (1 hour). | | 3600 | | +| `failoverDelay` *integer* | The amount of time (in seconds) to wait before triggering a failover
after the primary PostgreSQL instance in the cluster was detected
to be unhealthy | | 0 | | +| `livenessProbeTimeout` *integer* | LivenessProbeTimeout is the time (in seconds) that is allowed for a PostgreSQL instance
to successfully respond to the liveness probe (default 30).
The Liveness probe failure threshold is derived from this value using the formula:
ceiling(livenessProbe / 10). | | | | +| `affinity` *[AffinityConfiguration](#affinityconfiguration)* | Affinity/Anti-affinity rules for Pods | | | | +| `topologySpreadConstraints` *[TopologySpreadConstraint](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#topologyspreadconstraint-v1-core) array* | TopologySpreadConstraints specifies how to spread matching pods among the given topology.
More info:
| | | | +| `resources` *[ResourceRequirements](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#resourcerequirements-v1-core)* | Resources requirements of every generated Pod. Please refer to

for more information. | | | | +| `ephemeralVolumesSizeLimit` *[EphemeralVolumesSizeLimitConfiguration](#ephemeralvolumessizelimitconfiguration)* | EphemeralVolumesSizeLimit allows the user to set the limits for the ephemeral
volumes | | | | +| `priorityClassName` *string* | Name of the priority class which will be used in every generated Pod, if the PriorityClass
specified does not exist, the pod will not be able to schedule. Please refer to

for more information | | | | +| `primaryUpdateStrategy` *[PrimaryUpdateStrategy](#primaryupdatestrategy)* | Deployment strategy to follow to upgrade the primary server during a rolling
update procedure, after all replicas have been successfully updated:
it can be automated (`unsupervised` - default) or manual (`supervised`) | | unsupervised | Enum: [unsupervised supervised]
| +| `primaryUpdateMethod` *[PrimaryUpdateMethod](#primaryupdatemethod)* | Method to follow to upgrade the primary server during a rolling
update procedure, after all replicas have been successfully updated:
it can be with a switchover (`switchover`) or in-place (`restart` - default) | | | Enum: [switchover restart]
| +| `backup` *[BackupConfiguration](#backupconfiguration)* | The configuration to be used for backups | | | | +| `nodeMaintenanceWindow` *[NodeMaintenanceWindow](#nodemaintenancewindow)* | Define a maintenance window for the Kubernetes nodes | | | | +| `licenseKey` *string* | The license key of the cluster. When empty, the cluster operates in
trial mode and after the expiry date (default 30 days) the operator
will cease any reconciliation attempt. For details, please refer to
the license agreement that comes with the operator. | | | | +| `licenseKeySecret` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | The reference to the license key. When this is set it take precedence over LicenseKey. | | | | +| `monitoring` *[MonitoringConfiguration](#monitoringconfiguration)* | The configuration of the monitoring infrastructure of this cluster | | | | +| `externalClusters` *[ExternalCluster](#externalcluster) array* | The list of external clusters which are used in the configuration | | | | +| `logLevel` *string* | The instances' log level, one of the following values: error, warning, info (default), debug, trace | | info | Enum: [error warning info debug trace]
| +| `projectedVolumeTemplate` *[ProjectedVolumeSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#projectedvolumesource-v1-core)* | Template to be used to define projected volumes, projected volumes will be mounted
under `/projected` base folder | | | | +| `env` *[EnvVar](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#envvar-v1-core) array* | Env follows the Env format to pass environment variables
to the pods created in the cluster | | | | +| `envFrom` *[EnvFromSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#envfromsource-v1-core) array* | EnvFrom follows the EnvFrom format to pass environment variables
sources to the pods to be used by Env | | | | +| `managed` *[ManagedConfiguration](#managedconfiguration)* | The configuration that is used by the portions of PostgreSQL that are managed by the instance manager | | | | +| `seccompProfile` *[SeccompProfile](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#seccompprofile-v1-core)* | The SeccompProfile applied to every Pod and Container.
Defaults to: `RuntimeDefault` | | | | +| `podSecurityContext` *[PodSecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#podsecuritycontext-v1-core)* | Override the PodSecurityContext applied to every Pod of the cluster.
When set, this overrides the operator's default PodSecurityContext for the cluster.
If omitted, the operator defaults are used.
This field doesn't have any effect if SecurityContextConstraints are present.
Only available in 1.28 or later | | | | +| `securityContext` *[SecurityContext](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#securitycontext-v1-core)* | Override the SecurityContext applied to every Container in the Pod of the cluster.
When set, this overrides the operator's default Container SecurityContext.
If omitted, the operator defaults are used.
Only available in 1.28 or later | | | | +| `tablespaces` *[TablespaceConfiguration](#tablespaceconfiguration) array* | The tablespaces configuration | | | | +| `enablePDB` *boolean* | Manage the `PodDisruptionBudget` resources within the cluster. When
configured as `true` (default setting), the pod disruption budgets
will safeguard the primary node from being terminated. Conversely,
setting it to `false` will result in the absence of any
`PodDisruptionBudget` resource, permitting the shutdown of all nodes
hosting the PostgreSQL cluster. This latter configuration is
advisable for any PostgreSQL cluster employed for
development/staging purposes. | | true | | +| `plugins` *[PluginConfiguration](#pluginconfiguration) array* | The plugins configuration, containing
any plugin to be loaded with the corresponding configuration | | | | +| `probes` *[ProbesConfiguration](#probesconfiguration)* | The configuration of the probes to be injected
in the PostgreSQL Pods. | | | | + +#### ClusterStatus + +ClusterStatus defines the observed state of a PostgreSQL cluster managed by +{{name.ln}}. + +*Appears in:* + +- [Cluster](#cluster) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `instances` *integer* | The total number of PVC Groups detected in the cluster. It may differ from the number of existing instance pods. | | | | +| `readyInstances` *integer* | The total number of ready instances in the cluster. It is equal to the number of ready instance pods. | | | | +| `selector` *string* | Selector is the serialized form of the label selector that identifies
the pods managed by this cluster. Populated by the operator and exposed
through the scale sub-resource so an autoscaler (such as HPA or VPA)
can discover the managed instance pods. | | | | +| `instancesStatus` *object (keys:[PodStatus](#podstatus), values:string array)* | InstancesStatus indicates in which status the instances are | | | | +| `instancesReportedState` *object (keys:[PodName](#podname), values:[InstanceReportedState](#instancereportedstate))* | The reported state of the instances during the last reconciliation loop | | | | +| `managedRolesStatus` *[ManagedRoles](#managedroles)* | ManagedRolesStatus reports the state of the managed roles in the cluster | | | | +| `tablespacesStatus` *[TablespaceState](#tablespacestate) array* | TablespacesStatus reports the state of the declarative tablespaces in the cluster | | | | +| `timelineID` *integer* | The timeline of the Postgres cluster | | | | +| `topology` *[Topology](#topology)* | Instances topology. | | | | +| `latestGeneratedNode` *integer* | ID of the latest generated node (used to avoid node name clashing) | | | | +| `currentPrimary` *string* | Current primary instance | | | | +| `targetPrimary` *string* | Target primary instance, this is different from the previous one
during a switchover or a failover | | | | +| `lastPromotionToken` *string* | LastPromotionToken is the last verified promotion token that
was used to promote a replica cluster | | | | +| `pvcCount` *integer* | How many PVCs have been created by this cluster | | | | +| `jobCount` *integer* | How many Jobs have been created by this cluster | | | | +| `danglingPVC` *string array* | List of all the PVCs created by this cluster and still available
which are not attached to a Pod | | | | +| `resizingPVC` *string array* | List of all the PVCs that have ResizingPVC condition. | | | | +| `initializingPVC` *string array* | List of all the PVCs that are being initialized by this cluster | | | | +| `healthyPVC` *string array* | List of all the PVCs not dangling nor initializing | | | | +| `unusablePVC` *string array* | List of all the PVCs that are unusable because another PVC is missing | | | | +| `licenseStatus` *[Status](#status)* | Status of the license | | | | +| `writeService` *string* | Current write pod | | | | +| `readService` *string* | Current list of read pods | | | | +| `phase` *string* | Current phase of the cluster | | | | +| `phaseReason` *string* | Reason for the current phase | | | | +| `secretsResourceVersion` *[SecretsResourceVersion](#secretsresourceversion)* | The list of resource versions of the secrets
managed by the operator. Every change here is done in the
interest of the instance manager, which will refresh the
secret data | | | | +| `configMapResourceVersion` *[ConfigMapResourceVersion](#configmapresourceversion)* | The list of resource versions of the configmaps,
managed by the operator. Every change here is done in the
interest of the instance manager, which will refresh the
configmap data | | | | +| `certificates` *[CertificatesStatus](#certificatesstatus)* | The configuration for the CA and related certificates, initialized with defaults. | | | | +| `firstRecoverabilityPoint` *string* | The first recoverability point, stored as a date in RFC3339 format.
This field is calculated from the content of FirstRecoverabilityPointByMethod.
Deprecated: the field is not set for backup plugins. | | | | +| `firstRecoverabilityPointByMethod` *object (keys:[BackupMethod](#backupmethod), values:[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta))* | The first recoverability point, stored as a date in RFC3339 format, per backup method type.
Deprecated: the field is not set for backup plugins. | | | | +| `lastSuccessfulBackup` *string* | Last successful backup, stored as a date in RFC3339 format.
This field is calculated from the content of LastSuccessfulBackupByMethod.
Deprecated: the field is not set for backup plugins. | | | | +| `lastSuccessfulBackupByMethod` *object (keys:[BackupMethod](#backupmethod), values:[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta))* | Last successful backup, stored as a date in RFC3339 format, per backup method type.
Deprecated: the field is not set for backup plugins. | | | | +| `lastFailedBackup` *string* | Last failed backup, stored as a date in RFC3339 format.
Deprecated: the field is not set for backup plugins. | | | | +| `cloudNativePostgresqlCommitHash` *string* | The commit hash number of which this operator running | | | | +| `currentPrimaryTimestamp` *string* | The timestamp when the last actual promotion to primary has occurred | | | | +| `currentPrimaryFailingSinceTimestamp` *string* | The timestamp when the primary was detected to be unhealthy
This field is reported when `.spec.failoverDelay` is populated or during online upgrades | | | | +| `targetPrimaryTimestamp` *string* | The timestamp when the last request for a new primary has occurred | | | | +| `poolerIntegrations` *[PoolerIntegrations](#poolerintegrations)* | The integration needed by poolers referencing the cluster | | | | +| `cloudNativePostgresqlOperatorHash` *string* | The hash of the binary of the operator | | | | +| `availableArchitectures` *[AvailableArchitecture](#availablearchitecture) array* | AvailableArchitectures reports the available architectures of a cluster | | | | +| `conditions` *[Condition](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#condition-v1-meta) array* | Conditions for cluster object | | | | +| `instanceNames` *string array* | List of instance names in the cluster | | | | +| `onlineUpdateEnabled` *boolean* | OnlineUpdateEnabled shows if the online upgrade is enabled inside the cluster | | | | +| `azurePVCUpdateEnabled` *boolean* | AzurePVCUpdateEnabled shows if the PVC online upgrade is enabled for this cluster | | | | +| `image` *string* | Image contains the image name used by the pods | | | | +| `pgDataImageInfo` *[ImageInfo](#imageinfo)* | PGDataImageInfo contains the details of the latest image that has run on the current data directory. | | | | +| `pluginStatus` *[PluginStatus](#pluginstatus) array* | PluginStatus is the status of the loaded plugins | | | | +| `switchReplicaClusterStatus` *[SwitchReplicaClusterStatus](#switchreplicaclusterstatus)* | SwitchReplicaClusterStatus is the status of the switch to replica cluster | | | | +| `demotionToken` *string* | DemotionToken is a JSON token containing the information
from pg_controldata such as Database system identifier, Latest checkpoint's
TimeLineID, Latest checkpoint's REDO location, Latest checkpoint's REDO
WAL file, and Time of latest checkpoint | | | | +| `systemID` *string* | SystemID is the latest detected PostgreSQL SystemID | | | | + +#### ConfigMapResourceVersion + +ConfigMapResourceVersion is the resource versions of the secrets +managed by the operator + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `metrics` *object (keys:string, values:string)* | A map with the versions of all the config maps used to pass metrics.
Map keys are the config map names, map values are the versions | | | | + +#### DataDurabilityLevel + +*Underlying type:* *string* + +DataDurabilityLevel specifies how strictly to enforce synchronous replication +when cluster instances are unavailable. Options are `required` or `preferred`. + +*Appears in:* + +- [SynchronousReplicaConfiguration](#synchronousreplicaconfiguration) + +| Field | Description | +| ----------- | ----------------------------------------------------------------------------------------------------------------------- | +| `required` | DataDurabilityLevelRequired means that data durability is strictly enforced
| +| `preferred` | DataDurabilityLevelPreferred means that data durability is enforced
only when healthy replicas are available
| + +#### DataSource + +DataSource contains the configuration required to bootstrap a +PostgreSQL cluster from an existing storage + +*Appears in:* + +- [BootstrapRecovery](#bootstraprecovery) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | -------- | ------- | ---------- | +| `storage` *[TypedLocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#typedlocalobjectreference-v1-core)* | Configuration of the storage of the instances | True | | | +| `walStorage` *[TypedLocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#typedlocalobjectreference-v1-core)* | Configuration of the storage for PostgreSQL WAL (Write-Ahead Log) | | | | +| `tablespaceStorage` *object (keys:string, values:[TypedLocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#typedlocalobjectreference-v1-core))* | Configuration of the storage for PostgreSQL tablespaces | | | | + +#### Database + +Database is the Schema for the databases API + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `Database` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[DatabaseSpec](#databasespec)* | Specification of the desired Database.
More info: | True | | | +| `status` *[DatabaseStatus](#databasestatus)* | Most recently observed status of the Database. This data may not be up to
date. Populated by the system. Read-only.
More info: | | | | + +#### DatabaseObjectSpec + +DatabaseObjectSpec contains the fields which are common to every +database object + +*Appears in:* + +- [ExtensionSpec](#extensionspec) +- [FDWSpec](#fdwspec) +- [SchemaSpec](#schemaspec) +- [ServerSpec](#serverspec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------- | +| `name` *string* | Name of the object (extension, schema, FDW, server) | True | | | +| `ensure` *[EnsureOption](#ensureoption)* | Specifies whether an object (e.g schema) should be present or absent
in the database. If set to `present`, the object will be created if
it does not exist. If set to `absent`, the extension/schema will be
removed if it exists. | | present | Enum: [present absent]
| + +#### DatabaseObjectStatus + +DatabaseObjectStatus is the status of the managed database objects + +*Appears in:* + +- [DatabaseStatus](#databasestatus) + +| Field | Description | Required | Default | Validation | +| ------------------- | ----------------------------------------------------------------------- | -------- | ------- | ---------- | +| `name` *string* | The name of the object | True | | | +| `applied` *boolean* | True of the object has been installed successfully in
the database | True | | | +| `message` *string* | Message is the object reconciliation message | | | | + +#### DatabaseReclaimPolicy + +*Underlying type:* *string* + +DatabaseReclaimPolicy describes a policy for end-of-life maintenance of databases. + +*Appears in:* + +- [DatabaseSpec](#databasespec) + +| Field | Description | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `delete` | DatabaseReclaimDelete means the database will be deleted from its PostgreSQL Cluster on release
from its claim.
| +| `retain` | DatabaseReclaimRetain means the database will be left in its current phase for manual
reclamation by the administrator. The default policy is Retain.
| + +#### DatabaseRoleRef + +DatabaseRoleRef is a reference an a role available inside PostgreSQL + +*Appears in:* + +- [TablespaceConfiguration](#tablespaceconfiguration) + +| Field | Description | Required | Default | Validation | +| --------------- | ----------- | -------- | ------- | ---------- | +| `name` *string* | | | | | + +#### DatabaseSpec + +DatabaseSpec is the specification of a Postgresql Database, built around the +`CREATE DATABASE`, `ALTER DATABASE`, and `DROP DATABASE` SQL commands of +PostgreSQL. + +*Appears in:* + +- [Database](#database) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------- | +| `cluster` *[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#localobjectreference-v1-core)* | The name of the PostgreSQL cluster hosting the database. | True | | | +| `ensure` *[EnsureOption](#ensureoption)* | Ensure the PostgreSQL database is `present` or `absent` - defaults to "present". | | present | Enum: [present absent]
| +| `name` *string* | The name of the database to create inside PostgreSQL. This setting cannot be changed. | True | | | +| `owner` *string* | Maps to the `OWNER` parameter of `CREATE DATABASE`.
Maps to the `OWNER TO` command of `ALTER DATABASE`.
The role name of the user who owns the database inside PostgreSQL. | True | | | +| `template` *string* | Maps to the `TEMPLATE` parameter of `CREATE DATABASE`. This setting
cannot be changed. The name of the template from which to create
this database. | | | | +| `encoding` *string* | Maps to the `ENCODING` parameter of `CREATE DATABASE`. This setting
cannot be changed. Character set encoding to use in the database. | | | | +| `locale` *string* | Maps to the `LOCALE` parameter of `CREATE DATABASE`. This setting
cannot be changed. Sets the default collation order and character
classification in the new database. | | | | +| `localeProvider` *string* | Maps to the `LOCALE_PROVIDER` parameter of `CREATE DATABASE`. This
setting cannot be changed. This option sets the locale provider for
databases created in the new cluster. Available from PostgreSQL 16. | | | | +| `localeCollate` *string* | Maps to the `LC_COLLATE` parameter of `CREATE DATABASE`. This
setting cannot be changed. | | | | +| `localeCType` *string* | Maps to the `LC_CTYPE` parameter of `CREATE DATABASE`. This setting
cannot be changed. | | | | +| `icuLocale` *string* | Maps to the `ICU_LOCALE` parameter of `CREATE DATABASE`. This
setting cannot be changed. Specifies the ICU locale when the ICU
provider is used. This option requires `localeProvider` to be set to
`icu`. Available from PostgreSQL 15. | | | | +| `icuRules` *string* | Maps to the `ICU_RULES` parameter of `CREATE DATABASE`. This setting
cannot be changed. Specifies additional collation rules to customize
the behavior of the default collation. This option requires
`localeProvider` to be set to `icu`. Available from PostgreSQL 16. | | | | +| `builtinLocale` *string* | Maps to the `BUILTIN_LOCALE` parameter of `CREATE DATABASE`. This
setting cannot be changed. Specifies the locale name when the
builtin provider is used. This option requires `localeProvider` to
be set to `builtin`. Available from PostgreSQL 17. | | | | +| `collationVersion` *string* | Maps to the `COLLATION_VERSION` parameter of `CREATE DATABASE`. This
setting cannot be changed. | | | | +| `isTemplate` *boolean* | Maps to the `IS_TEMPLATE` parameter of `CREATE DATABASE` and `ALTER
DATABASE`. If true, this database is considered a template and can
be cloned by any user with `CREATEDB` privileges. | | | | +| `allowConnections` *boolean* | Maps to the `ALLOW_CONNECTIONS` parameter of `CREATE DATABASE` and
`ALTER DATABASE`. If false then no one can connect to this database. | | | | +| `connectionLimit` *integer* | Maps to the `CONNECTION LIMIT` clause of `CREATE DATABASE` and
`ALTER DATABASE`. How many concurrent connections can be made to
this database. -1 (the default) means no limit. | | | | +| `tablespace` *string* | Maps to the `TABLESPACE` parameter of `CREATE DATABASE`.
Maps to the `SET TABLESPACE` command of `ALTER DATABASE`.
The name of the tablespace (in PostgreSQL) that will be associated
with the new database. This tablespace will be the default
tablespace used for objects created in this database. | | | | +| `databaseReclaimPolicy` *[DatabaseReclaimPolicy](#databasereclaimpolicy)* | The policy for end-of-life maintenance of this database. | | retain | Enum: [delete retain]
| +| `schemas` *[SchemaSpec](#schemaspec) array* | The list of schemas to be managed in the database
Only available in 1.27 or later | | | | +| `extensions` *[ExtensionSpec](#extensionspec) array* | The list of extensions to be managed in the database
Only available in 1.27 or later | | | | +| `fdws` *[FDWSpec](#fdwspec) array* | The list of foreign data wrappers to be managed in the database
Only available in 1.27 or later | | | | +| `servers` *[ServerSpec](#serverspec) array* | The list of foreign servers to be managed in the database
Only available in 1.27 or later | | | | + +#### DatabaseStatus + +DatabaseStatus defines the observed state of Database + +*Appears in:* + +- [Database](#database) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `observedGeneration` *integer* | A sequence number representing the latest
desired state that was synchronized | | | | +| `applied` *boolean* | Applied is true if the database was reconciled correctly | | | | +| `message` *string* | Message is the reconciliation output message | | | | +| `schemas` *[DatabaseObjectStatus](#databaseobjectstatus) array* | Schemas is the status of the managed schemas | | | | +| `extensions` *[DatabaseObjectStatus](#databaseobjectstatus) array* | Extensions is the status of the managed extensions | | | | +| `fdws` *[DatabaseObjectStatus](#databaseobjectstatus) array* | FDWs is the status of the managed FDWs | | | | +| `servers` *[DatabaseObjectStatus](#databaseobjectstatus) array* | Servers is the status of the managed servers | | | | + +#### EPASConfiguration + +EPASConfiguration contains EDB Postgres Advanced Server specific configurations + +*Appears in:* + +- [PostgresConfiguration](#postgresconfiguration) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------- | --------------------------------- | -------- | ------- | ---------- | +| `audit` *boolean* | If true enables edb_audit logging | | | | +| `tde` *[TDEConfiguration](#tdeconfiguration)* | TDE configuration | | | | + +#### EmbeddedObjectMetadata + +EmbeddedObjectMetadata contains metadata to be inherited by all resources related to a Cluster + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------- | ----------- | -------- | ------- | ---------- | +| `labels` *object (keys:string, values:string)* | | | | | +| `annotations` *object (keys:string, values:string)* | | | | | + +#### EnsureOption + +*Underlying type:* *string* + +EnsureOption represents whether we should enforce the presence or absence of +a Role in a PostgreSQL instance + +*Appears in:* + +- [DatabaseObjectSpec](#databaseobjectspec) +- [DatabaseSpec](#databasespec) +- [ExtensionSpec](#extensionspec) +- [FDWSpec](#fdwspec) +- [OptionSpec](#optionspec) +- [RoleConfiguration](#roleconfiguration) +- [SchemaSpec](#schemaspec) +- [ServerSpec](#serverspec) + +| Field | Description | +| --------- | ----------- | +| `present` | | +| `absent` | | + +#### EphemeralVolumesSizeLimitConfiguration + +EphemeralVolumesSizeLimitConfiguration contains the configuration of the ephemeral +storage + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ------- | ---------- | +| `shm` *[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#quantity-resource-api)* | Shm is the size limit of the shared memory volume | | | | +| `temporaryData` *[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#quantity-resource-api)* | TemporaryData is the size limit of the temporary data volume | | | | + +#### ExtensionConfiguration + +ExtensionConfiguration is the configuration used to add +PostgreSQL extensions to the Cluster. + +*Appears in:* + +- [PostgresConfiguration](#postgresconfiguration) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | -------------------------------------------------------------------- | +| `name` *string* | The name of the extension, required | True | | MinLength: 1
Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
| +| `image` *[ImageVolumeSource](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#imagevolumesource-v1-core)* | The image containing the extension, required | True | | | +| `extension_control_path` *string array* | The list of directories inside the image which should be added to extension_control_path.
If not defined, defaults to "/share". | | | | +| `dynamic_library_path` *string array* | The list of directories inside the image which should be added to dynamic_library_path.
If not defined, defaults to "/lib". | | | | +| `ld_library_path` *string array* | The list of directories inside the image which should be added to ld_library_path. | | | | + +#### ExtensionSpec + +ExtensionSpec configures an extension in a database + +*Appears in:* + +- [DatabaseSpec](#databasespec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------- | +| `name` *string* | Name of the object (extension, schema, FDW, server) | True | | | +| `ensure` *[EnsureOption](#ensureoption)* | Specifies whether an object (e.g schema) should be present or absent
in the database. If set to `present`, the object will be created if
it does not exist. If set to `absent`, the extension/schema will be
removed if it exists. | | present | Enum: [present absent]
| +| `version` *string* | The version of the extension to install. If empty, the operator will
install the default version (whatever is specified in the
extension's control file) | True | | | +| `schema` *string* | The name of the schema in which to install the extension's objects,
in case the extension allows its contents to be relocated. If not
specified (default), and the extension's control file does not
specify a schema either, the current default object creation schema
is used. | True | | | + +#### ExternalCluster + +ExternalCluster represents the connection parameters to an +external cluster which is used in the other sections of the configuration + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `name` *string* | The server name, required | True | | | +| `connectionParameters` *object (keys:string, values:string)* | The list of connection parameters, such as dbname, host, username, etc | | | | +| `sslCert` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | The reference to an SSL certificate to be used to connect to this
instance | | | | +| `sslKey` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | The reference to an SSL private key to be used to connect to this
instance | | | | +| `sslRootCert` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | The reference to an SSL CA public key to be used to connect to this
instance | | | | +| `password` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | The reference to the password to be used to connect to the server.
If a password is provided, {{name.ln}} creates a PostgreSQL
passfile at `/controller/external/NAME/pass` (where "NAME" is the
cluster's name). This passfile is automatically referenced in the
connection string when establishing a connection to the remote
PostgreSQL server from the current PostgreSQL `Cluster`. This ensures
secure and efficient password management for external clusters. | | | | +| `barmanObjectStore` *[BarmanObjectStoreConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)* | The configuration for the barman-cloud tool suite | | | | +| `plugin` *[PluginConfiguration](#pluginconfiguration)* | The configuration of the plugin that is taking care
of WAL archiving and backups for this external cluster | True | | | + +#### FDWSpec + +FDWSpec configures an Foreign Data Wrapper in a database + +*Appears in:* + +- [DatabaseSpec](#databasespec) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------- | +| `name` *string* | Name of the object (extension, schema, FDW, server) | True | | | +| `ensure` *[EnsureOption](#ensureoption)* | Specifies whether an object (e.g schema) should be present or absent
in the database. If set to `present`, the object will be created if
it does not exist. If set to `absent`, the extension/schema will be
removed if it exists. | | present | Enum: [present absent]
| +| `handler` *string* | Name of the handler function (e.g., "postgres_fdw_handler").
This will be empty if no handler is specified. In that case,
the default handler is registered when the FDW extension is created. | | | | +| `validator` *string* | Name of the validator function (e.g., "postgres_fdw_validator").
This will be empty if no validator is specified. In that case,
the default validator is registered when the FDW extension is created. | | | | +| `owner` *string* | Owner specifies the database role that will own the Foreign Data Wrapper.
The role must have superuser privileges in the target database. | | | | +| `options` *[OptionSpec](#optionspec) array* | Options specifies the configuration options for the FDW. | | | | +| `usage` *[UsageSpec](#usagespec) array* | List of roles for which `USAGE` privileges on the FDW are granted or revoked. | | | | + +#### FailoverQuorum + +FailoverQuorum contains the information about the current failover +quorum status of a PG cluster. It is updated by the instance manager +of the primary node and reset to zero by the operator to trigger +an update. + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `FailoverQuorum` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `status` *[FailoverQuorumStatus](#failoverquorumstatus)* | Most recently observed status of the failover quorum. | | | | + +#### FailoverQuorumStatus + +FailoverQuorumStatus is the latest observed status of the failover +quorum of the PG cluster. + +*Appears in:* + +- [FailoverQuorum](#failoverquorum) + +| Field | Description | Required | Default | Validation | +| ----------------------------- | --------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `method` *string* | Contains the latest reported Method value. | | | | +| `standbyNames` *string array* | StandbyNames is the list of potentially synchronous
instance names. | | | | +| `standbyNumber` *integer* | StandbyNumber is the number of synchronous standbys that transactions
need to wait for replies from. | | | | +| `primary` *string* | Primary is the name of the primary instance that updated
this object the latest time. | | | | + +#### ImageCatalog + +ImageCatalog is the Schema for the imagecatalogs API + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `ImageCatalog` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[ImageCatalogSpec](#imagecatalogspec)* | Specification of the desired behavior of the ImageCatalog.
More info: | True | | | + +#### ImageCatalogRef + +ImageCatalogRef defines the reference to a major version in an ImageCatalog + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiGroup` *string* | APIGroup is the group for the resource being referenced.
If APIGroup is not specified, the specified Kind must be in the core API group.
For any other third-party types, APIGroup is required. | | | | +| `kind` *string* | Kind is the type of resource being referenced | True | | | +| `name` *string* | Name is the name of resource being referenced | True | | | +| `major` *integer* | The major version of PostgreSQL we want to use from the ImageCatalog | True | | | + +#### ImageCatalogSpec + +ImageCatalogSpec defines the desired ImageCatalog + +*Appears in:* + +- [ClusterImageCatalog](#clusterimagecatalog) +- [ImageCatalog](#imagecatalog) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------ | +| `images` *[CatalogImage](#catalogimage) array* | List of CatalogImages available in the catalog | True | | MaxItems: 8
MinItems: 1
| +| `componentImages` *[CatalogComponentImage](#catalogcomponentimage) array* | ComponentImages is a list of named images for components other than PostgreSQL
(e.g. pgbouncer). Keys must be unique within a catalog. | | | MaxItems: 32
| + +#### ImageInfo + +ImageInfo contains the information about a PostgreSQL image + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ------------------------ | ---------------------------------------------- | -------- | ------- | ---------- | +| `image` *string* | Image is the image name | True | | | +| `majorVersion` *integer* | MajorVersion is the major version of the image | True | | | + +#### Import + +Import contains the configuration to init a database from a logic snapshot of an externalCluster + +*Appears in:* + +- [BootstrapInitDB](#bootstrapinitdb) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------ | +| `source` *[ImportSource](#importsource)* | The source of the import | True | | | +| `type` *[SnapshotType](#snapshottype)* | The import type. Can be `microservice` or `monolith`. | True | | Enum: [microservice monolith]
| +| `databases` *string array* | The databases to import | True | | | +| `roles` *string array* | The roles to import | | | | +| `postImportApplicationSQL` *string array* | List of SQL queries to be executed as a superuser in the application
database right after is imported - to be used with extreme care
(by default empty). Only available in microservice type. | | | | +| `schemaOnly` *boolean* | When set to true, only the `pre-data` and `post-data` sections of
`pg_restore` are invoked, avoiding data import. Default: `false`. | | | | +| `pgDumpExtraOptions` *string array* | List of custom options to pass to the `pg_dump` command.
IMPORTANT: Use with caution. The operator does not validate these options,
and certain flags may interfere with its intended functionality or design.
You are responsible for ensuring that the provided options are compatible
with your environment and desired behavior. | | | | +| `pgRestoreExtraOptions` *string array* | List of custom options to pass to the `pg_restore` command.
IMPORTANT: Use with caution. The operator does not validate these options,
and certain flags may interfere with its intended functionality or design.
You are responsible for ensuring that the provided options are compatible
with your environment and desired behavior. | | | | +| `pgRestorePredataOptions` *string array* | Custom options to pass to the `pg_restore` command during the `pre-data`
section. This setting overrides the generic `pgRestoreExtraOptions` value.
IMPORTANT: Use with caution. The operator does not validate these options,
and certain flags may interfere with its intended functionality or design.
You are responsible for ensuring that the provided options are compatible
with your environment and desired behavior.
Only available in 1.28 or later | | | | +| `pgRestoreDataOptions` *string array* | Custom options to pass to the `pg_restore` command during the `data`
section. This setting overrides the generic `pgRestoreExtraOptions` value.
IMPORTANT: Use with caution. The operator does not validate these options,
and certain flags may interfere with its intended functionality or design.
You are responsible for ensuring that the provided options are compatible
with your environment and desired behavior.
Only available in 1.28 or later | | | | +| `pgRestorePostdataOptions` *string array* | Custom options to pass to the `pg_restore` command during the `post-data`
section. This setting overrides the generic `pgRestoreExtraOptions` value.
IMPORTANT: Use with caution. The operator does not validate these options,
and certain flags may interfere with its intended functionality or design.
You are responsible for ensuring that the provided options are compatible
with your environment and desired behavior.
Only available in 1.28 or later | | | | + +#### ImportSource + +ImportSource describes the source for the logical snapshot + +*Appears in:* + +- [Import](#import) + +| Field | Description | Required | Default | Validation | +| -------------------------- | ----------------------------------------------- | -------- | ------- | ---------- | +| `externalCluster` *string* | The name of the externalCluster used for import | True | | | + +#### InstanceID + +InstanceID contains the information to identify an instance + +*Appears in:* + +- [BackupStatus](#backupstatus) + +| Field | Description | Required | Default | Validation | +| ---------------------- | ---------------- | -------- | ------- | ---------- | +| `podName` *string* | The pod name | | | | +| `ContainerID` *string* | The container ID | | | | + +#### InstanceReportedState + +InstanceReportedState describes the last reported state of an instance during a reconciliation loop + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ---------------------- | --------------------------------------------- | -------- | ------- | ---------- | +| `isPrimary` *boolean* | indicates if an instance is the primary one | True | | | +| `timeLineID` *integer* | indicates on which TimelineId the instance is | | | | +| `ip` *string* | IP address of the instance | True | | | + +#### IsolationCheckConfiguration + +IsolationCheckConfiguration contains the configuration for the isolation check +functionality in the liveness probe + +*Appears in:* + +- [LivenessProbe](#livenessprobe) + +| Field | Description | Required | Default | Validation | +| ----------------------------- | -------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `enabled` *boolean* | Whether primary isolation checking is enabled for the liveness probe | | true | | +| `requestTimeout` *integer* | Timeout in milliseconds for requests during the primary isolation check | | 1000 | | +| `connectionTimeout` *integer* | Timeout in milliseconds for connections during the primary isolation check | | 1000 | | + +#### LDAPBindAsAuth + +LDAPBindAsAuth provides the required fields to use the +bind authentication for LDAP + +*Appears in:* + +- [LDAPConfig](#ldapconfig) + +| Field | Description | Required | Default | Validation | +| ----------------- | ----------------------------------------- | -------- | ------- | ---------- | +| `prefix` *string* | Prefix for the bind authentication option | | | | +| `suffix` *string* | Suffix for the bind authentication option | | | | + +#### LDAPBindSearchAuth + +LDAPBindSearchAuth provides the required fields to use +the bind+search LDAP authentication process + +*Appears in:* + +- [LDAPConfig](#ldapconfig) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | -------- | ------- | ---------- | +| `baseDN` *string* | Root DN to begin the user search | | | | +| `bindDN` *string* | DN of the user to bind to the directory | | | | +| `bindPassword` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | Secret with the password for the user to bind to the directory | | | | +| `searchAttribute` *string* | Attribute to match against the username | | | | +| `searchFilter` *string* | Search filter to use when doing the search+bind authentication | | | | + +#### LDAPConfig + +LDAPConfig contains the parameters needed for LDAP authentication + +*Appears in:* + +- [PostgresConfiguration](#postgresconfiguration) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------ | --------------------------------------------------------------- | -------- | ------- | ------------------------- | +| `server` *string* | LDAP hostname or IP address | | | | +| `port` *integer* | LDAP server port | | | | +| `scheme` *[LDAPScheme](#ldapscheme)* | LDAP schema to be used, possible options are `ldap` and `ldaps` | | | Enum: [ldap ldaps]
| +| `bindAsAuth` *[LDAPBindAsAuth](#ldapbindasauth)* | Bind as authentication configuration | | | | +| `bindSearchAuth` *[LDAPBindSearchAuth](#ldapbindsearchauth)* | Bind+Search authentication configuration | | | | +| `tls` *boolean* | Set to 'true' to enable LDAP over TLS. 'false' is default | | | | + +#### LDAPScheme + +*Underlying type:* *string* + +LDAPScheme defines the possible schemes for LDAP + +*Appears in:* + +- [LDAPConfig](#ldapconfig) + +| Field | Description | +| ------- | ----------- | +| `ldap` | | +| `ldaps` | | + +#### LivenessProbe + +LivenessProbe is the configuration of the liveness probe + +*Appears in:* + +- [ProbesConfiguration](#probesconfiguration) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `initialDelaySeconds` *integer* | Number of seconds after the container has started before liveness probes are initiated.
More info: | | | | +| `timeoutSeconds` *integer* | Number of seconds after which the probe times out.
Defaults to 1 second. Minimum value is 1.
More info: | | | | +| `periodSeconds` *integer* | How often (in seconds) to perform the probe.
Default to 10 seconds. Minimum value is 1. | | | | +| `successThreshold` *integer* | Minimum consecutive successes for the probe to be considered successful after having failed.
Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | | | | +| `failureThreshold` *integer* | Minimum consecutive failures for the probe to be considered failed after having succeeded.
Defaults to 3. Minimum value is 1. | | | | +| `terminationGracePeriodSeconds` *integer* | Optional duration in seconds the pod needs to terminate gracefully upon probe failure.
The grace period is the duration in seconds after the processes running in the pod are sent
a termination signal and the time when the processes are forcibly halted with a kill signal.
Set this value longer than the expected cleanup time for your process.
If this value is nil, the pod's terminationGracePeriodSeconds will be used. Otherwise, this
value overrides the value provided by the pod spec.
Value must be non-negative integer. The value zero indicates stop immediately via
the kill signal (no opportunity to shut down).
This is a beta field and requires enabling ProbeTerminationGracePeriod feature gate.
Minimum value is 1. spec.terminationGracePeriodSeconds is used if unset. | | | | +| `isolationCheck` *[IsolationCheckConfiguration](#isolationcheckconfiguration)* | Configure the feature that extends the liveness probe for a primary
instance. In addition to the basic checks, this verifies whether the
primary is isolated from the Kubernetes API server and from its
replicas, ensuring that it can be safely shut down if network
partition or API unavailability is detected. Enabled by default.
Only available in 1.27 or later | | | | + +#### ManagedConfiguration + +ManagedConfiguration represents the portions of PostgreSQL that are managed +by the instance manager + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------- | --------------------------------------- | -------- | ------- | ---------- | +| `roles` *[RoleConfiguration](#roleconfiguration) array* | Database roles managed by the `Cluster` | | | | +| `services` *[ManagedServices](#managedservices)* | Services roles managed by the `Cluster` | | | | + +#### ManagedRoles + +ManagedRoles tracks the status of a cluster's managed roles + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `byStatus` *object (keys:[RoleStatus](#rolestatus), values:string array)* | ByStatus gives the list of roles in each state | | | | +| `cannotReconcile` *object (keys:string, values:string array)* | CannotReconcile lists roles that cannot be reconciled, with an
explanation of the cause. Failures may originate in PostgreSQL
(e.g. dropping a role that owns objects) or in Kubernetes (e.g.
the referenced password Secret cannot be fetched). | | | | +| `passwordStatus` *object (keys:string, values:[PasswordState](#passwordstate))* | PasswordStatus gives the last transaction id and password secret version for each managed role | | | | + +#### ManagedService + +ManagedService represents a specific service managed by the cluster. +It includes the type of service and its associated template specification. + +*Appears in:* + +- [ManagedServices](#managedservices) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------- | +| `selectorType` *[ServiceSelectorType](#serviceselectortype)* | SelectorType specifies the type of selectors that the service will have.
Valid values are "rw", "r", and "ro", representing read-write, read, and read-only services. | True | | Enum: [rw r ro]
| +| `updateStrategy` *[ServiceUpdateStrategy](#serviceupdatestrategy)* | UpdateStrategy describes how the service differences should be reconciled | | patch | Enum: [patch replace]
| +| `serviceTemplate` *[ServiceTemplateSpec](#servicetemplatespec)* | ServiceTemplate is the template specification for the service. | True | | | + +#### ManagedServices + +ManagedServices represents the services managed by the cluster. + +*Appears in:* + +- [ManagedConfiguration](#managedconfiguration) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------- | +| `disabledDefaultServices` *[ServiceSelectorType](#serviceselectortype) array* | DisabledDefaultServices is a list of service types that are disabled by default.
Valid values are "r", and "ro", representing read, and read-only services. | | | Enum: [rw r ro]
| +| `additional` *[ManagedService](#managedservice) array* | Additional is a list of additional managed services specified by the user. | | | | + +#### Metadata + +Metadata is a structure similar to the metav1.ObjectMeta, but still +parseable by controller-gen to create a suitable CRD for the user. +The comment of PodTemplateSpec has an explanation of why we are +not using the core data types. + +*Appears in:* + +- [PodTemplateSpec](#podtemplatespec) +- [ServiceAccountTemplate](#serviceaccounttemplate) +- [ServiceTemplateSpec](#servicetemplatespec) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `name` *string* | The name of the resource. Only supported for certain types | | | | +| `labels` *object (keys:string, values:string)* | Map of string keys and values that can be used to organize and categorize
(scope and select) objects. May match selectors of replication controllers
and services.
More info: | | | | +| `annotations` *object (keys:string, values:string)* | Annotations is an unstructured key value map stored with a resource that may be
set by external tools to store and retrieve arbitrary metadata. They are not
queryable and should be preserved when modifying objects.
More info: | | | | + +#### MonitoringConfiguration + +MonitoringConfiguration is the type containing all the monitoring +configuration for a certain cluster + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `disableDefaultQueries` *boolean* | Whether the default queries should be injected.
Set it to `true` if you don't want to inject default queries into the cluster.
Default: false. | | false | | +| `customQueriesConfigMap` *[ConfigMapKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#ConfigMapKeySelector) array* | The list of config maps containing the custom queries | | | | +| `customQueriesSecret` *[SecretKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#SecretKeySelector) array* | The list of secrets containing the custom queries | | | | +| `enablePodMonitor` *boolean* | Enable or disable the `PodMonitor`
Deprecated: This feature will be removed in an upcoming release. If
you need this functionality, you can create a PodMonitor manually. | | false | | +| `tls` *[ClusterMonitoringTLSConfiguration](#clustermonitoringtlsconfiguration)* | Configure TLS communication for the metrics endpoint.
Changing tls.enabled option will force a rollout of all instances. | | | | +| `podMonitorMetricRelabelings` *[RelabelConfig](https://pkg.go.dev/github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1#RelabelConfig) array* | The list of metric relabelings for the `PodMonitor`. Applied to samples before ingestion.
Deprecated: This feature will be removed in an upcoming release. If
you need this functionality, you can create a PodMonitor manually. | | | | +| `podMonitorRelabelings` *[RelabelConfig](https://pkg.go.dev/github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1#RelabelConfig) array* | The list of relabelings for the `PodMonitor`. Applied to samples before scraping.
Deprecated: This feature will be removed in an upcoming release. If
you need this functionality, you can create a PodMonitor manually. | | | | +| `metricsQueriesTTL` *[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#duration-v1-meta)* | The interval during which metrics computed from queries are considered current.
Once it is exceeded, a new scrape will trigger a rerun
of the queries.
If not set, defaults to 30 seconds, in line with Prometheus scraping defaults.
Setting this to zero disables the caching mechanism and can cause heavy load on the PostgreSQL server.
Only available in 1.28 or later | | | | + +#### NodeMaintenanceWindow + +NodeMaintenanceWindow contains information that the operator +will use while upgrading the underlying node. + +This option is only useful when the chosen storage prevents the Pods +from being freely moved across nodes. + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ---------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `reusePVC` *boolean* | Reuse the existing PVC (wait for the node to come
up again) or not (recreate it elsewhere - when `instances` >1) | | true | | +| `inProgress` *boolean* | Is there a node maintenance activity in progress? | | false | | + +#### OnlineConfiguration + +OnlineConfiguration contains the configuration parameters for the online volume snapshot + +*Appears in:* + +- [BackupSpec](#backupspec) +- [ScheduledBackupSpec](#scheduledbackupspec) +- [VolumeSnapshotConfiguration](#volumesnapshotconfiguration) + +| Field | Description | Required | Default | Validation | +| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `waitForArchive` *boolean* | If false, the function will return immediately after the backup is completed,
without waiting for WAL to be archived.
This behavior is only useful with backup software that independently monitors WAL archiving.
Otherwise, WAL required to make the backup consistent might be missing and make the backup useless.
By default, or when this parameter is true, pg_backup_stop will wait for WAL to be archived when archiving is
enabled.
On a standby, this means that it will wait only when archive_mode = always.
If write activity on the primary is low, it may be useful to run pg_switch_wal on the primary in order to trigger
an immediate segment switch. | | true | | +| `immediateCheckpoint` *boolean* | Control whether the I/O workload for the backup initial checkpoint will
be limited, according to the `checkpoint_completion_target` setting on
the PostgreSQL server. If set to true, an immediate checkpoint will be
used, meaning PostgreSQL will complete the checkpoint as soon as
possible. `false` by default. | | | | + +#### OptionSpec + +OptionSpec holds the name, value and the ensure field for an option + +*Appears in:* + +- [FDWSpec](#fdwspec) +- [ServerSpec](#serverspec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------- | +| `name` *string* | Name of the option | True | | | +| `value` *string* | Value of the option | True | | | +| `ensure` *[EnsureOption](#ensureoption)* | Specifies whether an option should be present or absent in
the database. If set to `present`, the option will be
created if it does not exist. If set to `absent`, the
option will be removed if it exists. | | present | Enum: [present absent]
| + +#### PasswordState + +PasswordState represents the state of the password of a managed RoleConfiguration + +*Appears in:* + +- [ManagedRoles](#managedroles) + +| Field | Description | Required | Default | Validation | +| -------------------------- | ------------------------------------------------------------------- | -------- | ------- | ---------- | +| `transactionID` *integer* | the last transaction ID to affect the role definition in PostgreSQL | | | | +| `resourceVersion` *string* | the resource version of the password secret | | | | + +#### PgBouncerIntegrationStatus + +PgBouncerIntegrationStatus encapsulates the needed integration for the pgbouncer poolers referencing the cluster + +*Appears in:* + +- [PoolerIntegrations](#poolerintegrations) + +| Field | Description | Required | Default | Validation | +| ------------------------ | ----------- | -------- | ------- | ---------- | +| `secrets` *string array* | | | | | + +#### PgBouncerPoolMode + +*Underlying type:* *string* + +PgBouncerPoolMode is the mode of PgBouncer + +*Validation:* + +- Enum: [session transaction] + +*Appears in:* + +- [PgBouncerSpec](#pgbouncerspec) + +#### PgBouncerSecrets + +PgBouncerSecrets contains the versions of the secrets used +by pgbouncer + +*Appears in:* + +- [PoolerSecrets](#poolersecrets) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------- | ----------------------------- | -------- | ------- | ---------- | +| `authQuery` *[SecretVersion](#secretversion)* | The auth query secret version | | | | + +#### PgBouncerSpec + +PgBouncerSpec defines how to configure PgBouncer + +*Appears in:* + +- [PoolerSpec](#poolerspec) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------------- | +| `poolMode` *[PgBouncerPoolMode](#pgbouncerpoolmode)* | The pool mode. Default: `session`. | | session | Enum: [session transaction]
| +| `serverTLSSecret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | ServerTLSSecret, when pointing to a TLS secret, provides pgbouncer's
`server_tls_key_file` and `server_tls_cert_file`, used when
authenticating against PostgreSQL.
Only available in 1.28 or later | | | | +| `serverCASecret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | ServerCASecret provides PgBouncer’s server_tls_ca_file, the root
CA for validating PostgreSQL certificates
Only available in 1.28 or later | | | | +| `clientCASecret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | ClientCASecret provides PgBouncer’s client_tls_ca_file, the root
CA for validating client certificates
Only available in 1.28 or later | | | | +| `clientTLSSecret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | ClientTLSSecret provides PgBouncer’s client_tls_key_file (private key)
and client_tls_cert_file (certificate) used to accept client connections
Only available in 1.28 or later | | | | +| `authQuerySecret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | The credentials of the user that need to be used for the authentication
query. In case it is specified, also an AuthQuery
(e.g. "SELECT usename, passwd FROM pg_catalog.pg_shadow WHERE usename=$1")
has to be specified and no automatic CNP Cluster integration will be triggered.
Deprecated. | | | | +| `authQuery` *string* | The query that will be used to download the hash of the password
of a certain user. Default: "SELECT usename, passwd FROM public.user_search($1)".
In case it is specified, also an AuthQuerySecret has to be specified and
no automatic CNP Cluster integration will be triggered. | | | | +| `parameters` *object (keys:string, values:string)* | Additional parameters to be passed to PgBouncer - please check
the CNP documentation for a list of options you can configure | | | | +| `pg_hba` *string array* | PostgreSQL Host Based Authentication rules (lines to be appended
to the pg_hba.conf file) | | | | +| `paused` *boolean* | When set to `true`, PgBouncer will disconnect from the PostgreSQL
server, first waiting for all queries to complete, and pause all new
client connections until this value is set to `false` (default). Internally,
the operator calls PgBouncer's `PAUSE` and `RESUME` commands. | | false | | + +#### PluginConfiguration + +PluginConfiguration specifies a plugin that need to be loaded for this +cluster to be reconciled + +*Appears in:* + +- [ClusterSpec](#clusterspec) +- [ExternalCluster](#externalcluster) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ---------- | +| `name` *string* | Name is the plugin name | True | | | +| `enabled` *boolean* | Enabled is true if this plugin will be used | | true | | +| `isWALArchiver` *boolean* | Marks the plugin as the WAL archiver. At most one plugin can be
designated as a WAL archiver. This cannot be enabled if the
`.spec.backup.barmanObjectStore` configuration is present. | | false | | +| `parameters` *object (keys:string, values:string)* | Parameters is the configuration of the plugin | | | | + +#### PluginStatus + +PluginStatus is the status of a loaded plugin + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ---------- | +| `name` *string* | Name is the name of the plugin | True | | | +| `version` *string* | Version is the version of the plugin loaded by the
latest reconciliation loop | True | | | +| `capabilities` *string array* | Capabilities are the list of capabilities of the
plugin | | | | +| `operatorCapabilities` *string array* | OperatorCapabilities are the list of capabilities of the
plugin regarding the reconciler | | | | +| `walCapabilities` *string array* | WALCapabilities are the list of capabilities of the
plugin regarding the WAL management | | | | +| `backupCapabilities` *string array* | BackupCapabilities are the list of capabilities of the
plugin regarding the Backup management | | | | +| `restoreJobHookCapabilities` *string array* | RestoreJobHookCapabilities are the list of capabilities of the
plugin regarding the RestoreJobHook management | | | | +| `status` *string* | Status contain the status reported by the plugin through the SetStatusInCluster interface | | | | + +#### PodName + +*Underlying type:* *string* + +PodName is the name of a Pod + +*Appears in:* + +- [ClusterStatus](#clusterstatus) +- [Topology](#topology) + +#### PodStatus + +*Underlying type:* *string* + +PodStatus represent the possible status of pods + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +#### PodTemplateSpec + +PodTemplateSpec is a structure allowing the user to set +a template for Pod generation. + +Unfortunately we can't use the corev1.PodTemplateSpec +type because the generated CRD won't have the field for the +metadata section. + +References: + + + + +*Appears in:* + +- [PoolerSpec](#poolerspec) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `metadata` *[Metadata](#metadata)* | Refer to Kubernetes API documentation for fields of `metadata`. | | | | +| `spec` *[PodSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#podspec-v1-core)* | Specification of the desired behavior of the pod.
More info: | | | | + +#### PodTopologyLabels + +*Underlying type:* *object* + +PodTopologyLabels represent the topology of a Pod. map[labelName]labelValue + +*Appears in:* + +- [Topology](#topology) + +#### Pooler + +Pooler is the Schema for the poolers API + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `Pooler` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[PoolerSpec](#poolerspec)* | Specification of the desired behavior of the Pooler.
More info: | True | | | +| `status` *[PoolerStatus](#poolerstatus)* | Most recently observed status of the Pooler. This data may not be up to
date. Populated by the system. Read-only.
More info: | | | | + +#### PoolerIntegrations + +PoolerIntegrations encapsulates the needed integration for the poolers referencing the cluster + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------------- | ----------- | -------- | ------- | ---------- | +| `pgBouncerIntegration` *[PgBouncerIntegrationStatus](#pgbouncerintegrationstatus)* | | | | | + +#### PoolerMonitoringConfiguration + +PoolerMonitoringConfiguration is the type containing all the monitoring +configuration for a certain Pooler. + +Mirrors the Cluster's MonitoringConfiguration but without the custom queries +part for now. + +*Appears in:* + +- [PoolerSpec](#poolerspec) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `enablePodMonitor` *boolean* | Enable or disable the `PodMonitor` | | false | | +| `podMonitorMetricRelabelings` *[RelabelConfig](https://pkg.go.dev/github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1#RelabelConfig) array* | The list of metric relabelings for the `PodMonitor`. Applied to samples before ingestion. | | | | +| `podMonitorRelabelings` *[RelabelConfig](https://pkg.go.dev/github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1#RelabelConfig) array* | The list of relabelings for the `PodMonitor`. Applied to samples before scraping. | | | | + +#### PoolerSecrets + +PoolerSecrets contains the versions of all the secrets used + +*Appears in:* + +- [PoolerStatus](#poolerstatus) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------- | -------------------------------------------- | -------- | ------- | ---------- | +| `clientTLS` *[SecretVersion](#secretversion)* | The client TLS secret version | | | | +| `serverTLS` *[SecretVersion](#secretversion)* | The server TLS secret version | | | | +| `serverCA` *[SecretVersion](#secretversion)* | The server CA secret version | | | | +| `clientCA` *[SecretVersion](#secretversion)* | The client CA secret version | | | | +| `pgBouncerSecrets` *[PgBouncerSecrets](#pgbouncersecrets)* | The version of the secrets used by PgBouncer | | | | + +#### PoolerSpec + +PoolerSpec defines the desired state of Pooler + +*Appears in:* + +- [Pooler](#pooler) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------- | +| `cluster` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | This is the cluster reference on which the Pooler will work.
Pooler name should never match with any cluster name within the same namespace. | True | | | +| `type` *[PoolerType](#poolertype)* | Type of service to forward traffic to. Default: `rw`. | | rw | Enum: [rw ro r]
| +| `instances` *integer* | The number of replicas we want. Default: 1. | | 1 | | +| `template` *[PodTemplateSpec](#podtemplatespec)* | The template of the Pod to be created | | | | +| `pgbouncer` *[PgBouncerSpec](#pgbouncerspec)* | The PgBouncer configuration | True | | | +| `deploymentStrategy` *[DeploymentStrategy](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#deploymentstrategy-v1-apps)* | The deployment strategy to use for pgbouncer to replace existing pods with new ones | | | | +| `monitoring` *[PoolerMonitoringConfiguration](#poolermonitoringconfiguration)* | The configuration of the monitoring infrastructure of this pooler.
Deprecated: This feature will be removed in an upcoming release. If
you need this functionality, you can create a PodMonitor manually. | | | | +| `serviceTemplate` *[ServiceTemplateSpec](#servicetemplatespec)* | Template for the Service to be created | | | | + +#### PoolerStatus + +PoolerStatus defines the observed state of Pooler + +*Appears in:* + +- [Pooler](#pooler) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------- | ----------------------------------------- | -------- | ------- | ---------- | +| `secrets` *[PoolerSecrets](#poolersecrets)* | The resource version of the config object | | | | +| `instances` *integer* | The number of pods trying to be scheduled | | | | + +#### PoolerType + +*Underlying type:* *string* + +PoolerType is the type of the connection pool, meaning the service +we are targeting. Allowed values are `rw` and `ro`. + +*Validation:* + +- Enum: [rw ro r] + +*Appears in:* + +- [PoolerSpec](#poolerspec) + +#### PostgresConfiguration + +PostgresConfiguration defines the PostgreSQL configuration + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `parameters` *object (keys:string, values:string)* | PostgreSQL configuration options (postgresql.conf) | | | | +| `synchronous` *[SynchronousReplicaConfiguration](#synchronousreplicaconfiguration)* | Configuration of the PostgreSQL synchronous replication feature | | | | +| `pg_hba` *string array* | PostgreSQL Host Based Authentication rules (lines to be appended
to the pg_hba.conf file) | | | | +| `pg_ident` *string array* | PostgreSQL User Name Maps rules (lines to be appended
to the pg_ident.conf file) | | | | +| `epas` *[EPASConfiguration](#epasconfiguration)* | EDB Postgres Advanced Server specific configurations | | | | +| `syncReplicaElectionConstraint` *[SyncReplicaElectionConstraints](#syncreplicaelectionconstraints)* | Requirements to be met by sync replicas. This will affect how the "synchronous_standby_names" parameter will be
set up. | | | | +| `shared_preload_libraries` *string array* | Lists of shared preload libraries to add to the default ones | | | | +| `ldap` *[LDAPConfig](#ldapconfig)* | Options to specify LDAP configuration | | | | +| `promotionTimeout` *integer* | Specifies the maximum number of seconds to wait when promoting an instance to primary.
Default value is 40000000, greater than one year in seconds,
big enough to simulate an infinite timeout | | | | +| `enableAlterSystem` *boolean* | If this parameter is true, the user will be able to invoke `ALTER SYSTEM`
on this {{name.ln}} Cluster.
This should only be used for debugging and troubleshooting.
Defaults to false. | | | | +| `extensions` *[ExtensionConfiguration](#extensionconfiguration) array* | The configuration of the extensions to be added
Only available in 1.28 or later | | | | + +#### PrimaryUpdateMethod + +*Underlying type:* *string* + +PrimaryUpdateMethod defines the method to use when upgrading +the primary instance of the cluster as part of rolling updates. +The default method is "restart" + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | +| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `switchover` | PrimaryUpdateMethodSwitchover means that the operator will switchover to another updated
replica when it needs to upgrade the primary instance
| +| `restart` | PrimaryUpdateMethodRestart means that the operator will restart the primary instance in-place
when it needs to upgrade it
| + +#### PrimaryUpdateStrategy + +*Underlying type:* *string* + +PrimaryUpdateStrategy contains the strategy to follow when upgrading +the primary server of the cluster as part of rolling updates + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | +| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `supervised` | PrimaryUpdateStrategySupervised means that the operator need to wait for the
user to manually issue a switchover request before updating the primary
server (`supervised`)
| +| `unsupervised` | PrimaryUpdateStrategyUnsupervised means that the operator will proceed with the
selected PrimaryUpdateMethod to another updated replica and then automatically update
the primary server (`unsupervised`, default)
| + +#### Probe + +Probe describes a health check to be performed against a container to determine whether it is +alive or ready to receive traffic. + +*Appears in:* + +- [LivenessProbe](#livenessprobe) +- [ProbeWithStrategy](#probewithstrategy) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `initialDelaySeconds` *integer* | Number of seconds after the container has started before liveness probes are initiated.
More info: | | | | +| `timeoutSeconds` *integer* | Number of seconds after which the probe times out.
Defaults to 1 second. Minimum value is 1.
More info: | | | | +| `periodSeconds` *integer* | How often (in seconds) to perform the probe.
Default to 10 seconds. Minimum value is 1. | | | | +| `successThreshold` *integer* | Minimum consecutive successes for the probe to be considered successful after having failed.
Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | | | | +| `failureThreshold` *integer* | Minimum consecutive failures for the probe to be considered failed after having succeeded.
Defaults to 3. Minimum value is 1. | | | | +| `terminationGracePeriodSeconds` *integer* | Optional duration in seconds the pod needs to terminate gracefully upon probe failure.
The grace period is the duration in seconds after the processes running in the pod are sent
a termination signal and the time when the processes are forcibly halted with a kill signal.
Set this value longer than the expected cleanup time for your process.
If this value is nil, the pod's terminationGracePeriodSeconds will be used. Otherwise, this
value overrides the value provided by the pod spec.
Value must be non-negative integer. The value zero indicates stop immediately via
the kill signal (no opportunity to shut down).
This is a beta field and requires enabling ProbeTerminationGracePeriod feature gate.
Minimum value is 1. spec.terminationGracePeriodSeconds is used if unset. | | | | + +#### ProbeStrategyType + +*Underlying type:* *string* + +ProbeStrategyType is the type of the strategy used to declare a PostgreSQL instance +ready + +*Appears in:* + +- [ProbeWithStrategy](#probewithstrategy) + +| Field | Description | +| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `pg_isready` | ProbeStrategyPgIsReady means that the pg_isready tool is used to determine
whether PostgreSQL is started up
| +| `streaming` | ProbeStrategyStreaming means that pg_isready is positive and the replica is
connected via streaming replication to the current primary and the lag is, if specified,
within the limit.
| +| `query` | ProbeStrategyQuery means that the server is able to connect to the superuser database
and able to execute a simple query like "-- ping"
| + +#### ProbeWithStrategy + +ProbeWithStrategy is the configuration of the startup probe + +*Appears in:* + +- [ProbesConfiguration](#probesconfiguration) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------------------- | +| `initialDelaySeconds` *integer* | Number of seconds after the container has started before liveness probes are initiated.
More info: | | | | +| `timeoutSeconds` *integer* | Number of seconds after which the probe times out.
Defaults to 1 second. Minimum value is 1.
More info: | | | | +| `periodSeconds` *integer* | How often (in seconds) to perform the probe.
Default to 10 seconds. Minimum value is 1. | | | | +| `successThreshold` *integer* | Minimum consecutive successes for the probe to be considered successful after having failed.
Defaults to 1. Must be 1 for liveness and startup. Minimum value is 1. | | | | +| `failureThreshold` *integer* | Minimum consecutive failures for the probe to be considered failed after having succeeded.
Defaults to 3. Minimum value is 1. | | | | +| `terminationGracePeriodSeconds` *integer* | Optional duration in seconds the pod needs to terminate gracefully upon probe failure.
The grace period is the duration in seconds after the processes running in the pod are sent
a termination signal and the time when the processes are forcibly halted with a kill signal.
Set this value longer than the expected cleanup time for your process.
If this value is nil, the pod's terminationGracePeriodSeconds will be used. Otherwise, this
value overrides the value provided by the pod spec.
Value must be non-negative integer. The value zero indicates stop immediately via
the kill signal (no opportunity to shut down).
This is a beta field and requires enabling ProbeTerminationGracePeriod feature gate.
Minimum value is 1. spec.terminationGracePeriodSeconds is used if unset. | | | | +| `type` *[ProbeStrategyType](#probestrategytype)* | The probe strategy
Only available in 1.287or later | | | Enum: [pg_isready streaming query]
| +| `maximumLag` *[Quantity](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#quantity-resource-api)* | Lag limit. Used only for `streaming` strategy
Only available in 1.27 or later | | | | + +#### ProbesConfiguration + +ProbesConfiguration represent the configuration for the probes +to be injected in the PostgreSQL Pods + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------- | --------------------------------- | -------- | ------- | ---------- | +| `startup` *[ProbeWithStrategy](#probewithstrategy)* | The startup probe configuration | True | | | +| `liveness` *[LivenessProbe](#livenessprobe)* | The liveness probe configuration | True | | | +| `readiness` *[ProbeWithStrategy](#probewithstrategy)* | The readiness probe configuration | True | | | + +#### Publication + +Publication is the Schema for the publications API + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `Publication` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[PublicationSpec](#publicationspec)* | | True | | | +| `status` *[PublicationStatus](#publicationstatus)* | | True | | | + +#### PublicationReclaimPolicy + +*Underlying type:* *string* + +PublicationReclaimPolicy defines a policy for end-of-life maintenance of Publications. + +*Appears in:* + +- [PublicationSpec](#publicationspec) + +| Field | Description | +| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `delete` | PublicationReclaimDelete means the publication will be deleted from Kubernetes on release
from its claim.
| +| `retain` | PublicationReclaimRetain means the publication will be left in its current phase for manual
reclamation by the administrator. The default policy is Retain.
| + +#### PublicationSpec + +PublicationSpec defines the desired state of Publication + +*Appears in:* + +- [Publication](#publication) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------- | ------- | ---------------------------- | +| `cluster` *[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#localobjectreference-v1-core)* | The name of the PostgreSQL cluster that identifies the "publisher" | True | | | +| `name` *string* | The name of the publication inside PostgreSQL | True | | | +| `dbname` *string* | The name of the database where the publication will be installed in
the "publisher" cluster | True | | | +| `parameters` *object (keys:string, values:string)* | Publication parameters part of the `WITH` clause as expected by
PostgreSQL `CREATE PUBLICATION` command | | | | +| `target` *[PublicationTarget](#publicationtarget)* | Target of the publication as expected by PostgreSQL `CREATE PUBLICATION` command | True | | | +| `publicationReclaimPolicy` *[PublicationReclaimPolicy](#publicationreclaimpolicy)* | The policy for end-of-life maintenance of this publication | | retain | Enum: [delete retain]
| + +#### PublicationStatus + +PublicationStatus defines the observed state of Publication + +*Appears in:* + +- [Publication](#publication) + +| Field | Description | Required | Default | Validation | +| ------------------------------ | ---------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `observedGeneration` *integer* | A sequence number representing the latest
desired state that was synchronized | | | | +| `applied` *boolean* | Applied is true if the publication was reconciled correctly | | | | +| `message` *string* | Message is the reconciliation output message | | | | + +#### PublicationTarget + +PublicationTarget is what this publication should publish + +*Appears in:* + +- [PublicationSpec](#publicationspec) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------- | +| `allTables` *boolean* | Marks the publication as one that replicates changes for all tables
in the database, including tables created in the future.
Corresponding to `FOR ALL TABLES` in PostgreSQL. | | | | +| `objects` *[PublicationTargetObject](#publicationtargetobject) array* | Just the following schema objects | | | MaxItems: 100000
| + +#### PublicationTargetObject + +PublicationTargetObject is an object to publish + +*Appears in:* + +- [PublicationTarget](#publicationtarget) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `tablesInSchema` *string* | Marks the publication as one that replicates changes for all tables
in the specified list of schemas, including tables created in the
future. Corresponding to `FOR TABLES IN SCHEMA` in PostgreSQL. | | | | +| `table` *[PublicationTargetTable](#publicationtargettable)* | Specifies a list of tables to add to the publication. Corresponding
to `FOR TABLE` in PostgreSQL. | | | | + +#### PublicationTargetTable + +PublicationTargetTable is a table to publish + +*Appears in:* + +- [PublicationTargetObject](#publicationtargetobject) + +| Field | Description | Required | Default | Validation | +| ------------------------ | ----------------------------------------------------------------- | -------- | ------- | ---------- | +| `only` *boolean* | Whether to limit to the table only or include all its descendants | | | | +| `name` *string* | The table name | True | | | +| `schema` *string* | The schema name | | | | +| `columns` *string array* | The columns to publish | | | | + +#### RecoveryTarget + +RecoveryTarget allows to configure the moment where the recovery process +will stop. All the target options except TargetTLI are mutually exclusive. + +*Appears in:* + +- [BootstrapRecovery](#bootstraprecovery) + +| Field | Description | Required | Default | Validation | +| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `backupID` *string* | The ID of the backup from which to start the recovery process.
If empty (default) the operator will automatically detect the backup
based on targetTime or targetLSN if specified. Otherwise use the
latest available backup in chronological order. | | | | +| `targetTLI` *string* | The target timeline ("latest" or a positive integer) | | | | +| `targetXID` *string* | The target transaction ID | | | | +| `targetName` *string* | The target name (to be previously created
with `pg_create_restore_point`) | | | | +| `targetLSN` *string* | The target LSN (Log Sequence Number) | | | | +| `targetTime` *string* | The target time as a timestamp in RFC3339 format or PostgreSQL timestamp format.
Timestamps without an explicit timezone are interpreted as UTC. | | | | +| `targetImmediate` *boolean* | End recovery as soon as a consistent state is reached | | | | +| `exclusive` *boolean* | Set the target to be exclusive. If omitted, defaults to false, so that
in Postgres, `recovery_target_inclusive` will be true | | | | + +#### ReplicaClusterConfiguration + +ReplicaClusterConfiguration encapsulates the configuration of a replica +cluster + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------- | +| `self` *string* | Self defines the name of this cluster. It is used to determine if this is a primary
or a replica cluster, comparing it with `primary` | | | | +| `primary` *string* | Primary defines which Cluster is defined to be the primary in the distributed PostgreSQL cluster, based on the
topology specified in externalClusters | | | | +| `source` *string* | The name of the external cluster which is the replication origin | True | | MinLength: 1
| +| `enabled` *boolean* | If replica mode is enabled, this cluster will be a replica of an
existing cluster. Replica cluster can be created from a recovery
object store or via streaming through pg_basebackup.
Refer to the Replica clusters page of the documentation for more information. | | | | +| `promotionToken` *string* | A demotion token generated by an external cluster used to
check if the promotion requirements are met. | | | | +| `minApplyDelay` *[Duration](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#duration-v1-meta)* | When replica mode is enabled, this parameter allows you to replay
transactions only when the system time is at least the configured
time past the commit time. This provides an opportunity to correct
data loss errors. Note that when this parameter is set, a promotion
token cannot be used. | | | | + +#### ReplicationSlotsConfiguration + +ReplicationSlotsConfiguration encapsulates the configuration +of replication slots + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------- | +| `highAvailability` *[ReplicationSlotsHAConfiguration](#replicationslotshaconfiguration)* | Replication slots for high availability configuration | | | | +| `updateInterval` *integer* | Standby will update the status of the local replication slots
every `updateInterval` seconds (default 30). | | | Minimum: 1
| +| `synchronizeReplicas` *[SynchronizeReplicasConfiguration](#synchronizereplicasconfiguration)* | Configures the synchronization of the user defined physical replication slots | | | | + +#### ReplicationSlotsHAConfiguration + +ReplicationSlotsHAConfiguration encapsulates the configuration +of the replication slots that are automatically managed by +the operator to control the streaming replication connections +with the standby instances for high availability (HA) purposes. +Replication slots are a PostgreSQL feature that makes sure +that PostgreSQL automatically keeps WAL files in the primary +when a streaming client (in this specific case a replica that +is part of the HA cluster) gets disconnected. + +*Appears in:* + +- [ReplicationSlotsConfiguration](#replicationslotsconfiguration) + +| Field | Description | Required | Default | Validation | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ------------------------------ | +| `enabled` *boolean* | If enabled (default), the operator will automatically manage replication slots
on the primary instance and use them in streaming replication
connections with all the standby instances that are part of the HA
cluster. If disabled, the operator will not take advantage
of replication slots in streaming connections with the replicas.
This feature also controls replication slots in replica cluster,
from the designated primary to its cascading replicas. | | | | +| `slotPrefix` *string* | Prefix for replication slots managed by the operator for HA.
It may only contain lower case letters, numbers, and the underscore character.
This can only be set at creation time. By default set to `_cnp_`. | | | Pattern: `^[0-9a-z_]*$`
| +| `synchronizeLogicalDecoding` *boolean* | When enabled, the operator automatically manages synchronization of logical
decoding (replication) slots across high-availability clusters.
Requires one of the following conditions:
- PostgreSQL version 17 or later
- PostgreSQL version < 17 with pg_failover_slots extension enabled
Only available in 1.27 or later | | | | + +#### RoleConfiguration + +RoleConfiguration is the representation, in Kubernetes, of a PostgreSQL role +with the additional field Ensure specifying whether to ensure the presence or +absence of the role in the database + +The defaults of the CREATE ROLE command are applied +Reference: + +*Appears in:* + +- [ManagedConfiguration](#managedconfiguration) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------- | +| `name` *string* | Name of the role | True | | | +| `comment` *string* | Description of the role | | | | +| `ensure` *[EnsureOption](#ensureoption)* | Ensure the role is `present` or `absent` - defaults to "present" | | present | Enum: [present absent]
| +| `passwordSecret` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | Secret containing the password of the role (if present).
If null, the password will be ignored unless DisablePassword is set.
When set, the secret must follow the `kubernetes.io/basic-auth` format
and contain both a `username` and a `password` field. | | | | +| `connectionLimit` *integer* | If the role can log in, this specifies how many concurrent
connections the role can make. `-1` (the default) means no limit. | | -1 | | +| `validUntil` *[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta)* | Date and time after which the role's password is no longer valid.
When omitted, the password will never expire (default). | | | | +| `inRoles` *string array* | List of one or more existing roles to which this role will be
immediately added as a new member. Default empty. | | | | +| `inherit` *boolean* | Whether a role "inherits" the privileges of roles it is a member of.
Defaults is `true`. | | true | | +| `disablePassword` *boolean* | DisablePassword indicates that a role's password should be set to NULL in Postgres | | | | +| `superuser` *boolean* | Whether the role is a `superuser` who can override all access
restrictions within the database - superuser status is dangerous and
should be used only when really needed. You must yourself be a
superuser to create a new superuser. Defaults is `false`. | | | | +| `createdb` *boolean* | When set to `true`, the role being defined will be allowed to create
new databases. Specifying `false` (default) will deny a role the
ability to create databases. | | | | +| `createrole` *boolean* | Whether the role will be permitted to create, alter, drop, comment
on, change the security label for, and grant or revoke membership in
other roles. Default is `false`. | | | | +| `login` *boolean* | Whether the role is allowed to log in. A role having the `login`
attribute can be thought of as a user. Roles without this attribute
are useful for managing database privileges, but are not users in
the usual sense of the word. Default is `false`. | | | | +| `replication` *boolean* | Whether a role is a replication role. A role must have this
attribute (or be a superuser) in order to be able to connect to the
server in replication mode (physical or logical replication) and in
order to be able to create or drop replication slots. A role having
the `replication` attribute is a very highly privileged role, and
should only be used on roles actually used for replication. Default
is `false`. | | | | +| `bypassrls` *boolean* | Whether a role bypasses every row-level security (RLS) policy.
Default is `false`. | | | | + +#### RoleStatus + +*Underlying type:* *string* + +RoleStatus represents the status of a managed role in the cluster + +*Appears in:* + +- [ManagedRoles](#managedroles) + +| Field | Description | +| ------------------------ | ----------------------------------------------------------------------------------------------------- | +| `reconciled` | RoleStatusReconciled indicates the role in DB matches the Spec
| +| `not-managed` | RoleStatusNotManaged indicates the role is not in the Spec, therefore not managed
| +| `pending-reconciliation` | RoleStatusPendingReconciliation indicates the role in Spec requires updated/creation in DB
| +| `reserved` | RoleStatusReserved indicates this is one of the roles reserved by the operator. E.g. `postgres`
| + +#### SQLRefs + +SQLRefs holds references to ConfigMaps or Secrets +containing SQL files. The references are processed in a specific order: +first, all Secrets are processed, followed by all ConfigMaps. +Within each group, the processing order follows the sequence specified +in their respective arrays. + +*Appears in:* + +- [BootstrapInitDB](#bootstrapinitdb) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | -------- | ------- | ---------- | +| `secretRefs` *[SecretKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#SecretKeySelector) array* | SecretRefs holds a list of references to Secrets | | | | +| `configMapRefs` *[ConfigMapKeySelector](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#ConfigMapKeySelector) array* | ConfigMapRefs holds a list of references to ConfigMaps | | | | + +#### ScheduledBackup + +ScheduledBackup is the Schema for the scheduledbackups API + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `ScheduledBackup` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[ScheduledBackupSpec](#scheduledbackupspec)* | Specification of the desired behavior of the ScheduledBackup.
More info: | True | | | +| `status` *[ScheduledBackupStatus](#scheduledbackupstatus)* | Most recently observed status of the ScheduledBackup. This data may not be up
to date. Populated by the system. Read-only.
More info: | | | | + +#### ScheduledBackupSpec + +ScheduledBackupSpec defines the desired state of ScheduledBackup + +*Appears in:* + +- [ScheduledBackup](#scheduledbackup) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------- | ------------------------------------------------------ | +| `suspend` *boolean* | If this backup is suspended or not | | | | +| `immediate` *boolean* | If the first backup has to be immediately start after creation or not | | | | +| `schedule` *string* | The schedule does not follow the same format used in Kubernetes CronJobs
as it includes an additional seconds specifier,
see | True | | | +| `cluster` *[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)* | The cluster to backup | True | | | +| `backupOwnerReference` *string* | Indicates which ownerReference should be put inside the created backup resources.
- none: no owner reference for created backup objects (same behavior as before the field was introduced)
- self: sets the Scheduled backup object as owner of the backup
- cluster: set the cluster as owner of the backup
| | none | Enum: [none self cluster]
| +| `target` *[BackupTarget](#backuptarget)* | The policy to decide which instance should perform this backup. If empty,
it defaults to `cluster.spec.backup.target`.
Available options are empty string, `primary` and `prefer-standby`.
`primary` to have backups run always on primary instances,
`prefer-standby` to have backups run preferably on the most updated
standby, if available. | | | Enum: [primary prefer-standby]
| +| `method` *[BackupMethod](#backupmethod)* | The backup method to be used, possible options are `barmanObjectStore`,
`volumeSnapshot` or `plugin`. Defaults to: `barmanObjectStore`. | | barmanObjectStore | Enum: [barmanObjectStore volumeSnapshot plugin]
| +| `pluginConfiguration` *[BackupPluginConfiguration](#backuppluginconfiguration)* | Configuration parameters passed to the plugin managing this backup | | | | +| `online` *boolean* | Whether the default type of backup with volume snapshots is
online/hot (`true`, default) or offline/cold (`false`)
Overrides the default setting specified in the cluster field '.spec.backup.volumeSnapshot.online' | | | | +| `onlineConfiguration` *[OnlineConfiguration](#onlineconfiguration)* | Configuration parameters to control the online/hot backup with volume snapshots
Overrides the default settings specified in the cluster '.backup.volumeSnapshot.onlineConfiguration' stanza | | | | + +#### ScheduledBackupStatus + +ScheduledBackupStatus defines the observed state of ScheduledBackup + +*Appears in:* + +- [ScheduledBackup](#scheduledbackup) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `lastCheckTime` *[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta)* | The latest time the schedule | | | | +| `lastScheduleTime` *[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta)* | Information when was the last time that backup was successfully scheduled. | | | | +| `nextScheduleTime` *[Time](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#time-v1-meta)* | Next time we will run a backup | | | | + +#### SchemaSpec + +SchemaSpec configures a schema in a database + +*Appears in:* + +- [DatabaseSpec](#databasespec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------- | +| `name` *string* | Name of the object (extension, schema, FDW, server) | True | | | +| `ensure` *[EnsureOption](#ensureoption)* | Specifies whether an object (e.g schema) should be present or absent
in the database. If set to `present`, the object will be created if
it does not exist. If set to `absent`, the extension/schema will be
removed if it exists. | | present | Enum: [present absent]
| +| `owner` *string* | The role name of the user who owns the schema inside PostgreSQL.
It maps to the `AUTHORIZATION` parameter of `CREATE SCHEMA` and the
`OWNER TO` command of `ALTER SCHEMA`. | True | | | + +#### SecretVersion + +SecretVersion contains a secret name and its ResourceVersion + +*Appears in:* + +- [PgBouncerSecrets](#pgbouncersecrets) +- [PoolerSecrets](#poolersecrets) + +| Field | Description | Required | Default | Validation | +| ------------------ | --------------------------------- | -------- | ------- | ---------- | +| `name` *string* | The name of the secret | | | | +| `version` *string* | The ResourceVersion of the secret | | | | + +#### SecretsResourceVersion + +SecretsResourceVersion is the resource versions of the secrets +managed by the operator + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `superuserSecretVersion` *string* | The resource version of the "postgres" user secret | | | | +| `replicationSecretVersion` *string* | The resource version of the "streaming_replica" user secret | | | | +| `applicationSecretVersion` *string* | The resource version of the "app" user secret | | | | +| `managedRoleSecretVersion` *object (keys:string, values:string)* | The resource versions of the managed roles secrets | | | | +| `caSecretVersion` *string* | Unused. Retained for compatibility with old versions. | | | | +| `clientCaSecretVersion` *string* | The resource version of the PostgreSQL client-side CA secret version | | | | +| `serverCaSecretVersion` *string* | The resource version of the PostgreSQL server-side CA secret version | | | | +| `serverSecretVersion` *string* | The resource version of the PostgreSQL server-side secret version | | | | +| `barmanEndpointCA` *string* | The resource version of the Barman Endpoint CA if provided | | | | +| `externalClusterSecretVersion` *object (keys:string, values:string)* | The resource versions of the external cluster secrets | | | | +| `metrics` *object (keys:string, values:string)* | A map with the versions of all the secrets used to pass metrics.
Map keys are the secret names, map values are the versions | | | | + +#### ServerSpec + +ServerSpec configures a server of a foreign data wrapper + +*Appears in:* + +- [DatabaseSpec](#databasespec) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------------------------- | +| `name` *string* | Name of the object (extension, schema, FDW, server) | True | | | +| `ensure` *[EnsureOption](#ensureoption)* | Specifies whether an object (e.g schema) should be present or absent
in the database. If set to `present`, the object will be created if
it does not exist. If set to `absent`, the extension/schema will be
removed if it exists. | | present | Enum: [present absent]
| +| `fdw` *string* | The name of the Foreign Data Wrapper (FDW) | True | | | +| `options` *[OptionSpec](#optionspec) array* | Options specifies the configuration options for the server
(key is the option name, value is the option value). | | | | +| `usage` *[UsageSpec](#usagespec) array* | List of roles for which `USAGE` privileges on the server are granted or revoked. | | | | + +#### ServiceAccountTemplate + +ServiceAccountTemplate contains the template needed to generate the service accounts + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------- | --------------------------------------------------------------- | -------- | ------- | ---------- | +| `metadata` *[Metadata](#metadata)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | + +#### ServiceSelectorType + +*Underlying type:* *string* + +ServiceSelectorType describes a valid value for generating the service selectors. +It indicates which type of service the selector applies to, such as read-write, read, or read-only + +*Validation:* + +- Enum: [rw r ro] + +*Appears in:* + +- [ManagedService](#managedservice) +- [ManagedServices](#managedservices) + +| Field | Description | +| ----- | ----------------------------------------------------------- | +| `rw` | ServiceSelectorTypeRW selects the read-write service.
| +| `r` | ServiceSelectorTypeR selects the read service.
| +| `ro` | ServiceSelectorTypeRO selects the read-only service.
| + +#### ServiceTemplateSpec + +ServiceTemplateSpec is a structure allowing the user to set +a template for Service generation. + +*Appears in:* + +- [ManagedService](#managedservice) +- [PoolerSpec](#poolerspec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `metadata` *[Metadata](#metadata)* | Refer to Kubernetes API documentation for fields of `metadata`. | | | | +| `spec` *[ServiceSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#servicespec-v1-core)* | Specification of the desired behavior of the service.
More info: | | | | + +#### ServiceUpdateStrategy + +*Underlying type:* *string* + +ServiceUpdateStrategy describes how the changes to the managed service should be handled + +*Validation:* + +- Enum: [patch replace] + +*Appears in:* + +- [ManagedService](#managedservice) + +#### SnapshotOwnerReference + +*Underlying type:* *string* + +SnapshotOwnerReference defines the reference type for the owner of the snapshot. +This specifies which owner the processed resources should relate to. + +*Appears in:* + +- [VolumeSnapshotConfiguration](#volumesnapshotconfiguration) + +| Field | Description | +| --------- | ------------------------------------------------------------------------------------------------- | +| `none` | SnapshotOwnerReferenceNone indicates that the snapshot does not have any owner reference.
| +| `backup` | SnapshotOwnerReferenceBackup indicates that the snapshot is owned by the backup resource.
| +| `cluster` | SnapshotOwnerReferenceCluster indicates that the snapshot is owned by the cluster resource.
| + +#### SnapshotType + +*Underlying type:* *string* + +SnapshotType is a type of allowed import + +*Appears in:* + +- [Import](#import) + +| Field | Description | +| -------------- | ----------------------------------------------------------------------------------- | +| `monolith` | MonolithSnapshotType indicates to execute the monolith clone typology
| +| `microservice` | MicroserviceSnapshotType indicates to execute the microservice clone typology
| + +#### StorageConfiguration + +StorageConfiguration is the configuration used to create and reconcile PVCs, +usable for WAL volumes, PGDATA volumes, or tablespaces + +*Appears in:* + +- [ClusterSpec](#clusterspec) +- [TablespaceConfiguration](#tablespaceconfiguration) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `storageClass` *string* | StorageClass to use for PVCs. Applied after
evaluating the PVC template, if available.
If not specified, the generated PVCs will use the
default storage class | | | | +| `size` *string* | Size of the storage. Required if not already specified in the PVC template.
Changes to this field are automatically reapplied to the created PVCs.
Size cannot be decreased. | | | | +| `resizeInUseVolumes` *boolean* | Resize existent PVCs, defaults to true | | true | | +| `pvcTemplate` *[PersistentVolumeClaimSpec](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#persistentvolumeclaimspec-v1-core)* | Template to be used to generate the Persistent Volume Claim | | | | + +#### Subscription + +Subscription is the Schema for the subscriptions API + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- | -------- | ------- | ---------- | +| `apiVersion` *string* | `postgresql.k8s.enterprisedb.io/v1` | True | | | +| `kind` *string* | `Subscription` | True | | | +| `metadata` *[ObjectMeta](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#objectmeta-v1-meta)* | Refer to Kubernetes API documentation for fields of `metadata`. | True | | | +| `spec` *[SubscriptionSpec](#subscriptionspec)* | | True | | | +| `status` *[SubscriptionStatus](#subscriptionstatus)* | | True | | | + +#### SubscriptionReclaimPolicy + +*Underlying type:* *string* + +SubscriptionReclaimPolicy describes a policy for end-of-life maintenance of Subscriptions. + +*Appears in:* + +- [SubscriptionSpec](#subscriptionspec) + +| Field | Description | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `delete` | SubscriptionReclaimDelete means the subscription will be deleted from Kubernetes on release
from its claim.
| +| `retain` | SubscriptionReclaimRetain means the subscription will be left in its current phase for manual
reclamation by the administrator. The default policy is Retain.
| + +#### SubscriptionSpec + +SubscriptionSpec defines the desired state of Subscription + +*Appears in:* + +- [Subscription](#subscription) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------------------------- | +| `cluster` *[LocalObjectReference](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#localobjectreference-v1-core)* | The name of the PostgreSQL cluster that identifies the "subscriber" | True | | | +| `name` *string* | The name of the subscription inside PostgreSQL | True | | | +| `dbname` *string* | The name of the database where the publication will be installed in
the "subscriber" cluster | True | | | +| `parameters` *object (keys:string, values:string)* | Subscription parameters included in the `WITH` clause of the PostgreSQL
`CREATE SUBSCRIPTION` command. Most parameters cannot be changed
after the subscription is created and will be ignored if modified
later, except for a limited set documented at:
| | | | +| `publicationName` *string* | The name of the publication inside the PostgreSQL database in the
"publisher" | True | | | +| `publicationDBName` *string* | The name of the database containing the publication on the external
cluster. Defaults to the one in the external cluster definition. | | | | +| `externalClusterName` *string* | The name of the external cluster with the publication ("publisher") | True | | | +| `subscriptionReclaimPolicy` *[SubscriptionReclaimPolicy](#subscriptionreclaimpolicy)* | The policy for end-of-life maintenance of this subscription | | retain | Enum: [delete retain]
| + +#### SubscriptionStatus + +SubscriptionStatus defines the observed state of Subscription + +*Appears in:* + +- [Subscription](#subscription) + +| Field | Description | Required | Default | Validation | +| ------------------------------ | ---------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `observedGeneration` *integer* | A sequence number representing the latest
desired state that was synchronized | | | | +| `applied` *boolean* | Applied is true if the subscription was reconciled correctly | | | | +| `message` *string* | Message is the reconciliation output message | | | | + +#### SwitchReplicaClusterStatus + +SwitchReplicaClusterStatus contains all the statuses regarding the switch of a cluster to a replica cluster + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ---------------------- | -------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `inProgress` *boolean* | InProgress indicates if there is an ongoing procedure of switching a cluster to a replica cluster. | | | | + +#### SyncReplicaElectionConstraints + +SyncReplicaElectionConstraints contains the constraints for sync replicas election. + +For anti-affinity parameters two instances are considered in the same location +if all the labels values match. + +In future synchronous replica election restriction by name will be supported. + +*Appears in:* + +- [PostgresConfiguration](#postgresconfiguration) + +| Field | Description | Required | Default | Validation | +| --------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `nodeLabelsAntiAffinity` *string array* | A list of node labels values to extract and compare to evaluate if the pods reside in the same topology or not | | | | +| `enabled` *boolean* | This flag enables the constraints for sync replicas | True | | | + +#### SynchronizeReplicasConfiguration + +SynchronizeReplicasConfiguration contains the configuration for the synchronization of user defined +physical replication slots + +*Appears in:* + +- [ReplicationSlotsConfiguration](#replicationslotsconfiguration) + +| Field | Description | Required | Default | Validation | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `enabled` *boolean* | When set to true, every replication slot that is on the primary is synchronized on each standby | True | | | +| `excludePatterns` *string array* | List of regular expression patterns to match the names of replication slots to be excluded (by default empty) | | | | + +#### SynchronousReplicaConfiguration + +SynchronousReplicaConfiguration contains the configuration of the +PostgreSQL synchronous replication feature. +Important: at this moment, also `.spec.minSyncReplicas` and `.spec.maxSyncReplicas` +need to be considered. + +*Appears in:* + +- [PostgresConfiguration](#postgresconfiguration) + +| Field | Description | Required | Default | Validation | +| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | --------------------------------- | +| `method` *[SynchronousReplicaConfigurationMethod](#synchronousreplicaconfigurationmethod)* | Method to select synchronous replication standbys from the listed
servers, accepting 'any' (quorum-based synchronous replication) or
'first' (priority-based synchronous replication) as values. | True | | Enum: [any first]
| +| `number` *integer* | Specifies the number of synchronous standby servers that
transactions must wait for responses from. | True | | | +| `maxStandbyNamesFromCluster` *integer* | Specifies the maximum number of local cluster pods that can be
automatically included in the `synchronous_standby_names` option in
PostgreSQL. | | | | +| `standbyNamesPre` *string array* | A user-defined list of application names to be added to
`synchronous_standby_names` before local cluster pods (the order is
only useful for priority-based synchronous replication). | | | | +| `standbyNamesPost` *string array* | A user-defined list of application names to be added to
`synchronous_standby_names` after local cluster pods (the order is
only useful for priority-based synchronous replication). | | | | +| `dataDurability` *[DataDurabilityLevel](#datadurabilitylevel)* | If set to "required", data durability is strictly enforced. Write operations
with synchronous commit settings (`on`, `remote_write`, or `remote_apply`) will
block if there are insufficient healthy replicas, ensuring data persistence.
If set to "preferred", data durability is maintained when healthy replicas
are available, but the required number of instances will adjust dynamically
if replicas become unavailable. This setting relaxes strict durability enforcement
to allow for operational continuity. This setting is only applicable if both
`standbyNamesPre` and `standbyNamesPost` are unset (empty). | | | Enum: [required preferred]
| +| `failoverQuorum` *boolean* | FailoverQuorum enables a quorum-based check before failover, improving
data durability and safety during failover events in {{name.ln}}-managed
PostgreSQL clusters.
Only available in 1.28 or later | | | | + +#### SynchronousReplicaConfigurationMethod + +*Underlying type:* *string* + +SynchronousReplicaConfigurationMethod configures whether to use +quorum based replication or a priority list + +*Appears in:* + +- [SynchronousReplicaConfiguration](#synchronousreplicaconfiguration) + +#### TDEConfiguration + +TDEConfiguration contains the Transparent Data Encryption configuration + +*Appears in:* + +- [EPASConfiguration](#epasconfiguration) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `enabled` *boolean* | True if we want to have TDE enabled | | | | +| `secretKeyRef` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | Reference to the secret that contains the encryption key | | | | +| `wrapCommand` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | WrapCommand is the encrypt command provided by the user | | | | +| `unwrapCommand` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | UnwrapCommand is the decryption command provided by the user | | | | +| `passphraseCommand` *[SecretKeySelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.34/#secretkeyselector-v1-core)* | PassphraseCommand is the command executed to get the passphrase that will be
passed to the OpenSSL command to encrypt and decrypt | | | | + +#### TablespaceConfiguration + +TablespaceConfiguration is the configuration of a tablespace, and includes +the storage specification for the tablespace + +*Appears in:* + +- [ClusterSpec](#clusterspec) + +| Field | Description | Required | Default | Validation | +| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `name` *string* | The name of the tablespace | True | | | +| `storage` *[StorageConfiguration](#storageconfiguration)* | The storage configuration for the tablespace | True | | | +| `owner` *[DatabaseRoleRef](#databaseroleref)* | Owner is the PostgreSQL user owning the tablespace | | | | +| `temporary` *boolean* | When set to true, the tablespace will be added as a `temp_tablespaces`
entry in PostgreSQL, and will be available to automatically house temp
database objects, or other temporary files. Please refer to PostgreSQL
documentation for more information on the `temp_tablespaces` GUC. | | false | | + +#### TablespaceState + +TablespaceState represents the state of a tablespace in a cluster + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------- | -------------------------------------------------- | -------- | ------- | ---------- | +| `name` *string* | Name is the name of the tablespace | True | | | +| `owner` *string* | Owner is the PostgreSQL user owning the tablespace | | | | +| `state` *[TablespaceStatus](#tablespacestatus)* | State is the latest reconciliation state | True | | | +| `error` *string* | Error is the reconciliation error, if any | | | | + +#### TablespaceStatus + +*Underlying type:* *string* + +TablespaceStatus represents the status of a tablespace in the cluster + +*Appears in:* + +- [TablespaceState](#tablespacestate) + +| Field | Description | +| ------------ | -------------------------------------------------------------------------------------------------------- | +| `reconciled` | TablespaceStatusReconciled indicates the tablespace in DB matches the Spec
| +| `pending` | TablespaceStatusPendingReconciliation indicates the tablespace in Spec requires creation in the DB
| + +#### Topology + +Topology contains the cluster topology + +*Appears in:* + +- [ClusterStatus](#clusterstatus) + +| Field | Description | Required | Default | Validation | +| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ---------- | +| `instances` *object (keys:[PodName](#podname), values:[PodTopologyLabels](#podtopologylabels))* | Instances contains the pod topology of the instances | | | | +| `nodesUsed` *integer* | NodesUsed represents the count of distinct nodes accommodating the instances.
A value of '1' suggests that all instances are hosted on a single node,
implying the absence of High Availability (HA). Ideally, this value should
be the same as the number of instances in the Postgres HA cluster, implying
shared nothing architecture on the compute side. | | | | +| `successfullyExtracted` *boolean* | SuccessfullyExtracted indicates if the topology data was extract. It is useful to enact fallback behaviors
in synchronous replica election in case of failures | | | | + +#### UsageSpec + +UsageSpec configures a usage for a foreign data wrapper + +*Appears in:* + +- [FDWSpec](#fdwspec) +- [ServerSpec](#serverspec) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------- | ----------------- | -------- | ------- | --------------------------- | +| `name` *string* | Name of the usage | True | | | +| `type` *[UsageSpecType](#usagespectype)* | The type of usage | | grant | Enum: [grant revoke]
| + +#### UsageSpecType + +*Underlying type:* *string* + +UsageSpecType describes the type of usage specified in the `usage` field of the +`Database` object. + +*Appears in:* + +- [UsageSpec](#usagespec) + +| Field | Description | +| -------- | -------------------------------------------------------------------------------------------------------- | +| `grant` | GrantUsageSpecType indicates a grant usage permission.
The default usage permission is grant.
| +| `revoke` | RevokeUsageSpecType indicates a revoke usage permission.
| + +#### VolumeSnapshotConfiguration + +VolumeSnapshotConfiguration represents the configuration for the execution of snapshot backups. + +*Appears in:* + +- [BackupConfiguration](#backupconfiguration) + +| Field | Description | Required | Default | Validation | +| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------- | ---------------------------------- | +| `labels` *object (keys:string, values:string)* | Labels are key-value pairs that will be added to .metadata.labels snapshot resources. | | | | +| `annotations` *object (keys:string, values:string)* | Annotations key-value pairs that will be added to .metadata.annotations snapshot resources. | | | | +| `className` *string* | ClassName specifies the Snapshot Class to be used for PG_DATA PersistentVolumeClaim.
It is the default class for the other types if no specific class is present | | | | +| `walClassName` *string* | WalClassName specifies the Snapshot Class to be used for the PG_WAL PersistentVolumeClaim. | | | | +| `tablespaceClassName` *object (keys:string, values:string)* | TablespaceClassName specifies the Snapshot Class to be used for the tablespaces.
defaults to the PGDATA Snapshot Class, if set | | | | +| `snapshotOwnerReference` *[SnapshotOwnerReference](#snapshotownerreference)* | SnapshotOwnerReference indicates the type of owner reference the snapshot should have | | none | Enum: [none cluster backup]
| +| `online` *boolean* | Whether the default type of backup with volume snapshots is
online/hot (`true`, default) or offline/cold (`false`) | | true | | +| `onlineConfiguration` *[OnlineConfiguration](#onlineconfiguration)* | Configuration parameters to control the online/hot backup with volume snapshots | | { immediateCheckpoint:false waitForArchive:true } | | diff --git a/product_docs/docs/postgres_for_kubernetes/1/postgis.mdx b/product_docs/docs/postgres_for_kubernetes/1/postgis.mdx index 1b31ce49dd..f8280475f2 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/postgis.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/postgis.mdx @@ -8,6 +8,7 @@ for PostgreSQL that introduces support for storing GIS (Geographic Information Systems) objects in the database and be queried via SQL. !!!info Important + This section assumes you are familiar with PostGIS and provides some basic information about how to create a new PostgreSQL cluster with a PostGIS database in Kubernetes via {{name.ln}}. @@ -53,6 +54,7 @@ do this in two ways: architecture where the instance is shared by multiple databases !!!info + For more information on the microservice vs monolith architecture in the database, please refer to the ["How many databases should be hosted in a single PostgreSQL instance?" FAQ](faq.md) or the ["Database import" section](database_import.md). @@ -70,6 +72,7 @@ The [`postgis-example.yaml` manifest](../samples/postgis-example.yaml) below provides some guidance on how the creation of a PostGIS cluster can be done. !!!warning + Please consider that, although convention over configuration applies in {{name.ln}}, you should spend time configuring and tuning your system for production. Also, the `imageName` in the example below deliberately points @@ -111,20 +114,18 @@ The example leverages the `Database` resource's declarative extension management to add the specified extensions to the `app` database. !!!info + Take some time and look at the available options in `.spec.bootstrap.initdb` -from the [API reference](pg4k.v1.md#bootstrapinitdb), such as +from the [API reference](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-BootstrapInitDB), such as `postInitApplicationSQL`. !!! !!!info + For more details, see the ["Managing Extensions in a Database" section](declarative_database_management.md#managing-extensions-in-a-database). !!! -!!! Info - For more details, see the - ["Managing Extensions in a Database" section](declarative_database_management.md#managing-extensions-in-a-database). - You can easily verify the available version of PostGIS that is in the container, by connecting to the `app` database (you might obtain different values from the ones in this document): diff --git a/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx b/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx index 8063c04326..4ff08e1ac3 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx @@ -21,6 +21,7 @@ via the `parameters`, the `pg_hba`, and the `pg_ident` keys. These settings are the same across all instances. !!!warning + Please don't use the `ALTER SYSTEM` query to change the configuration of the PostgreSQL instances in an imperative way. Changing some of the options that are normally controlled by the operator might indeed lead to an @@ -33,6 +34,7 @@ A reference for custom settings usage is included in the samples, see [`cluster-example-custom.yaml`](../samples/cluster-example-custom.yaml). !!!warning + **OpenShift users:** due to a current limitation of the OpenShift user interface, it is possible to change PostgreSQL settings from the YAML pane only. !!! @@ -59,6 +61,7 @@ The `custom.conf` file will contain the user-defined settings in the ``` !!!note PostgreSQL GUCs: Grand Unified Configuration + Refer to the PostgreSQL documentation for [more information on the available parameters](https://www.postgresql.org/docs/current/runtime-config.html), also known as GUC (Grand Unified Configuration). @@ -101,6 +104,7 @@ wal_receiver_timeout = '5s' ``` !!!warning + It is your duty to plan for WAL segments retention in your PostgreSQL cluster and properly configure either `wal_keep_size` or `wal_keep_segments`, depending on the server version, based on the expected and observed workloads. @@ -168,6 +172,30 @@ single-instance clusters with WAL archiving disabled. ### Replication Settings +The [`wal_level`](https://www.postgresql.org/docs/current/runtime-config-wal.html) +parameter in PostgreSQL determines the amount of information written to the +Write-Ahead Log (WAL). It accepts the following values: + +- `minimal`: Writes only the information required for crash recovery. +- `replica`: Adds sufficient information to support WAL archiving and streaming + replication, including the ability to run read-only queries on standby + instances. +- `logical`: Includes all information from `replica`, plus additional information + required for logical decoding and replication. + +By default, upstream PostgreSQL sets `wal_level` to `replica`. {{name.ln}}, +instead, sets `wal_level` to `logical` by default to enable logical replication +out of the box. This makes it easier to support use cases such as migrations +from external PostgreSQL servers. + +If your cluster does not require logical replication, it is recommended to set +`wal_level` to `replica` to reduce WAL volume and overhead. + +Finally, {{name.ln}} allows `wal_level` to be set to `minimal` only for +single-instance clusters with WAL archiving disabled. + +### Replication Settings + The `primary_conninfo`, `restore_command`, and `recovery_target_timeline` parameters are automatically managed by the operator based on the instance's role within the cluster. These parameters are effectively applied only when the @@ -212,6 +240,7 @@ default. Although you can override the content of `shared_preload_libraries`, we recommend that only expert Postgres users take advantage of this option. !!!info Important + In case a specified library is not found, the server fails to start, preventing {{name.ln}} from any self-healing attempt and requiring manual intervention. Please make sure you always test both the extensions and @@ -230,6 +259,7 @@ library. The operator will also remove the library as soon as no actual paramete requires it. !!!info Important + Please always keep in mind that removing libraries from `shared_preload_libraries` requires a restart of all instances in the cluster in order to be effective. @@ -264,14 +294,8 @@ SELECT datname FROM pg_database WHERE datallowconn ``` !!!note -The above query also includes template databases like `template1`. -!!! -!!!info Important -With the introduction of [declarative extensions](declarative_database_management.md#managing-extensions-in-a-database) -in the `Database` CRD, you can now manage extensions directly. As a result, -the managed extensions feature may undergo significant changes in future -versions of {{name.ln}}, and some functionalities might be deprecated. +The above query also includes template databases like `template1`. !!! #### Enabling `auto_explain` @@ -295,6 +319,7 @@ to complete): ``` !!!note + Enabling auto_explain can lead to performance issues. Please refer to [`the auto explain documentation`](https://www.postgresql.org/docs/current/auto-explain.html) !!! @@ -375,6 +400,7 @@ you need to add this entry in the `pg_hba` section: used to create the `pg_hba.conf` used by the pods. !!!info Important + See the PostgreSQL documentation for [more information on `pg_hba.conf`](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html). !!! @@ -551,6 +577,7 @@ generate and maintain the ident map file (known as `pg_ident.conf`) inside the data directory. !!!info Important + See the PostgreSQL documentation for [more information on `pg_ident.conf`](https://www.postgresql.org/docs/current/auth-username-maps.html). !!! @@ -619,6 +646,7 @@ potential risks associated with this command. To enable the use of `ALTER SYSTEM you can explicitly set `.spec.postgresql.enableAlterSystem` to `true`. !!!warning + Proceed with caution when utilizing `ALTER SYSTEM`. This command operates directly on the connected instance and does not undergo replication. {{name.ln}} assumes responsibility for certain fixed parameters and complete diff --git a/product_docs/docs/postgres_for_kubernetes/1/preview_version.mdx b/product_docs/docs/postgres_for_kubernetes/1/preview_version.mdx index 8d9e2a2480..7f28091a4f 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/preview_version.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/preview_version.mdx @@ -11,21 +11,11 @@ These versions are feature-frozen, meaning no new features are added, and are intended for public testing prior to the final release. !!!warning Important + {{name.ln}} release candidates are **not intended for use in production** systems. They should only be deployed in staging or dedicated testing environments. !!! -## Current Preview Version - -The current preview version is **1.30.0-rc1**. - -For more information on the current preview version and how to test, please view the links below: - - -- [Announcement](/postgres_for_kubernetes/preview/rel_notes/1_30_0-rc1_rel_notes) -- [Documentation](/postgres_for_kubernetes/preview/) - - ## Purpose of Release Candidates Release candidates are provided to the community for extensive testing before @@ -52,6 +42,23 @@ is invaluable for validating real-world scenarios, such as:** ## Community Involvement: How to Help +The primary purpose of an RC is to catch serious defects and regressions that our +automated testing and internal manual checks might miss. **Specifically, community testing +is invaluable for validating real-world scenarios, such as:** + +- **Upgrade Paths:** Testing the process of upgrading an existing {{name.ln}} + cluster from the previous stable minor version to the RC version. This often + uncovers critical compatibility or migration issues, like those that affect PVC + ownership, which can only be reliably tested with diverse existing user setups. +- **Unique Configurations:** Validating compatibility with specific Kubernetes + versions, storage providers, networking setups, or custom PostgreSQL + extensions not covered by our standard test matrix. +- **Real-world Workloads:** Running the RC with your actual application + workload and traffic patterns to expose performance regressions or race + conditions. + +## Community Involvement: How to Help + The stability of each {{name.ln}} minor release significantly depends on the community's efforts to test the upcoming version with their workloads and tools. Identifying bugs and regressions through user testing is crucial in @@ -72,7 +79,7 @@ non-production environment: - **Report Issues:** **Immediately report any issues or unexpected behavior** by opening a GitHub issue and clearly marking it with a **`Release Candidate`** tag or label, along with the RC version number - (e.g., `1.29.0-rc1`). + (e.g., `1.28.0-rc1`). ## Usage Advisory @@ -84,3 +91,8 @@ are not backwards compatible and could be removed entirely. **By testing the Release Candidate, you are helping to prevent a potentially critical bug from affecting the entire community upon the GA release.** + +## Current Preview Version + +There are currently no preview versions available. + diff --git a/product_docs/docs/postgres_for_kubernetes/1/private_edb_registries.mdx b/product_docs/docs/postgres_for_kubernetes/1/private_edb_registries.mdx index e052bfb38a..9153ce46c5 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/private_edb_registries.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/private_edb_registries.mdx @@ -31,9 +31,9 @@ When installing the operator and operands from the private registry, the Collect the following information: -1. Your [EDB account token](/repos/getting_started/get_your_token/) -1. The name of the repository, which will be `k8s` -1. The repository server, which will be `docker.enterprisedb.com` +1. Your [EDB account token](/repos/getting_started/with_web/get_your_token/) +2. The name of the repository, which will be `k8s` +3. The repository server, which will be `docker.enterprisedb.com` For clarity, the following examples assume your token is in an environment variable named `EDB_SUBSCRIPTION_TOKEN`. @@ -97,7 +97,7 @@ kubectl create secret docker-registry registry-pullsecret \ As mentioned above, the `docker-username` is the name of your registry, i.e. `k8s`. The `docker-password` is the token retrieved -from the [EDB portal](/repos/getting_started/get_your_token/). +from the [EDB portal](/repos/getting_started/with_web/get_your_token/). Once your pull secret is created, remember to set the `imagePullSecrets` field in the cluster manifest in addition to the `imageName`. diff --git a/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx b/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx index 10e0e7de16..b94b7e51b1 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx @@ -3,6 +3,8 @@ title: 'Quickstart' originalFilePath: 'src/quickstart.md' --- + + This section guides you through testing a PostgreSQL cluster on your local machine by deploying {{name.ln}} on a local Kubernetes cluster using either [Kind](https://kind.sigs.k8s.io/) or @@ -12,6 +14,7 @@ Red Hat OpenShift Container Platform users can test the certified operator for {{name.ln}} on the [Red Hat OpenShift Local](https://developers.redhat.com/products/openshift-local/overview) (formerly Red Hat CodeReady Containers). !!!warning + The instructions contained in this section are for demonstration, testing, and practice purposes only and must not be used in production. !!! @@ -23,6 +26,7 @@ By following these instructions you should be able to start a PostgreSQL cluster on your local Kubernetes/Openshift installation and experiment with it. !!!info Important + Make sure that you have `kubectl` installed on your machine in order to connect to the Kubernetes cluster, or `oc` if using OpenShift Local. Please follow the Kubernetes documentation on [how to install `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/) @@ -30,6 +34,7 @@ or the Openshift documentation on [how to install `oc`](https://docs.openshift.c !!! !!!note + If you are running Openshift, use `oc` every time `kubectl` is mentioned in this documentation. `kubectl` commands are compatible with `oc` ones. !!! @@ -138,6 +143,7 @@ spec: ``` !!!note There's more + For more detailed information about the available options, please refer to the ["API Reference" section](pg4k.v1.md). !!! @@ -165,6 +171,7 @@ kubectl get pods -l k8s.enterprisedb.io/cluster= ``` !!!info Important + Note that we are using `k8s.enterprisedb.io/cluster` as the label. In the past you may have seen or used `postgresql`. This label is being deprecated, and will be dropped in the future. Please use `k8s.enterprisedb.io/cluster`. @@ -202,6 +209,7 @@ spec: ``` !!!info Important + The immutable infrastructure paradigm requires that you always point to a specific version of the container image. Never use tags like `latest` or `13` in a production environment @@ -212,6 +220,7 @@ to the image name, through the `:@sha256:` format. !!! !!!note There's more + There are some examples cluster configurations bundled with the operator. Please refer to the ["Examples" section](samples.md). !!! @@ -219,6 +228,7 @@ Please refer to the ["Examples" section](samples.md). ## Part 4: Monitor clusters with Prometheus and Grafana !!!info Important + Installing Prometheus and Grafana is beyond the scope of this project. The instructions in this section are provided for experimentation and illustration only. @@ -269,6 +279,7 @@ configured with the `kube-stack-config.yaml` file: - Alert Manager and Grafana are both enabled. !!!note Seealso + For further information about the above helm commands, refer to the [helm install](https://helm.sh/docs/helm/helm_install/) documentation. @@ -385,11 +396,12 @@ providing the credentials `admin` as username, `prom-operator` as password You can download the file [grafana-dashboard.json](https://github.com/cloudnative-pg/grafana-dashboards/blob/main/charts/cluster/grafana-dashboard.json) and manually import it via the GUI (menu: Dashboards > New > Import). -You can now click on the `{{name.ln}}` dashboard just created: +You can now click on the `EDB Postgres for Kubernetes` dashboard just created: ![local grafana](images/grafana-local.png) !!!warning + Some graphs in the previous dashboard make use of metrics that are in alpha stage by the time this was created, like `kubelet_volume_stats_available_bytes` and `kubelet_volume_stats_capacity_bytes` producing some graphs to show `No data`. diff --git a/product_docs/docs/postgres_for_kubernetes/1/recovery.mdx b/product_docs/docs/postgres_for_kubernetes/1/recovery.mdx index c1f69c241e..20a9e01185 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/recovery.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/recovery.mdx @@ -5,11 +5,19 @@ originalFilePath: 'src/recovery.md' -In PostgreSQL, **recovery** refers to the process of starting an instance from -an existing physical backup. PostgreSQL's recovery system is robust and -feature-rich, supporting **Point-In-Time Recovery (PITR)**—the ability to -restore a cluster to any specific moment, from the earliest available backup to -the latest archived WAL file. +In PostgreSQL terminology, recovery is the process of starting a PostgreSQL +instance using an existing backup. The PostgreSQL recovery mechanism +is very solid and rich. It also supports point-in-time recovery (PITR), which allows +you to restore a given cluster up to any point in time, from the first available +backup in your catalog to the last archived WAL. (The WAL +archive is mandatory in this case.) + + +!!!note + +For details on the `bootstrap` stanza, see +[Bootstrap](bootstrap.md). +!!! !!!info Important A valid WAL archive is required to perform PITR. @@ -24,9 +32,12 @@ For more details on configuring the `bootstrap` stanza, refer to [Bootstrap](bootstrap.md). !!! -The `recovery` bootstrap mode allows you to initialize a cluster from a -physical base backup and replay the associated WAL files to bring the system to -a consistent and optionally point-in-time state. +!!!info + +Starting with version 1.25, {{name.ln}} includes experimental support for +backup and recovery using plugins, such as the +[Barman Cloud plugin](https://github.com/cloudnative-pg/plugin-barman-cloud). +!!! {{name.ln}} supports recovery via: @@ -43,8 +54,10 @@ Plugin** for recovery from object stores, and the **native interface** for recovery from volume snapshots. !!!info Important -For legacy documentation, see -[Appendix B – Recovery from an Object Store](backup_barmanobjectstore.md#recovery-from-an-object-store). + +If using replica mode, make sure that the PostgreSQL configuration +(`.spec.postgresql.parameters`) of the recovered cluster is compatible with +the original one from a physical replication standpoint. !!! ## Recovery from an Object Store with the Barman Cloud Plugin @@ -117,27 +130,41 @@ spec: ## Recovery from `VolumeSnapshot` Objects -!!!warning -When creating replicas after recovering a primary instance from a -`VolumeSnapshot`, the operator may fall back to using `pg_basebackup` to -synchronize them. This process can be significantly slower—especially for large -databases—because it involves a full base backup. This limitation will be -addressed in the future with support for online backups and PVC cloning in -the scale-up process. +!!!info Important + +By default, the `recovery` method strictly uses the `name` of the +cluster in the `externalClusters` section as the name of the main folder +of the backup data within the object store. This name is normally reserved +for the name of the server. You can specify a different folder name +using the `barmanObjectStore.serverName` property. !!! -{{name.ln}} allows you to create a new cluster from a `VolumeSnapshot` of a -`PersistentVolumeClaim` (PVC) that belongs to an existing `Cluster`. -These snapshots are created using the declarative API for -[volume snapshot backups](backup_volumesnapshot.md). +!!!note + +This example takes advantage of the parallel WAL restore feature, +dedicating up to 8 jobs to concurrently fetch the required WAL files from the +archive. This feature can appreciably reduce the recovery time. Make sure that +you plan ahead for this scenario and correctly tune the value of this parameter +for your environment. It will make a difference when you need it, and you will. +!!! To complete the recovery process, the new cluster must also reference an external cluster that provides access to the WAL archive needed to reapply changes and finalize the recovery. -The following example shows a cluster being recovered using both a -`VolumeSnapshot` for the base backup and a WAL archive accessed through the -Barman Cloud Plugin: +!!!warning + +When creating replicas after recovering the primary instance from +the volume snapshot, the operator might end up using `pg_basebackup` +to synchronize them. This behavior results in a slower process, depending +on the size of the database. This limitation will be lifted in the future when +support for online backups and PVC cloning are introduced. +!!! + +EDB Postgres for Kubernetes can create a new cluster from a `VolumeSnapshot` of a PVC of an +existing `Cluster` that's been taken using the declarative API for [volume +snapshot backups](backup_volumesnapshot.md). You must specify the name of the +snapshot, as in the following example: ```yaml apiVersion: postgresql.k8s.enterprisedb.io/v1 @@ -196,6 +223,7 @@ different names, you must specify these names before exiting the recovery phase, as documented in ["Configure the application database"](#configure-the-application-database). !!!warning + If bootstrapping a replica-mode cluster from snapshots, to leverage snapshots for the standby instances and not just the primary, we recommend that you: @@ -257,6 +285,7 @@ target timeline (`latest`). You can optionally specify a `recoveryTarget` to perform a point-in-time recovery (see [Point in Time Recovery (PITR)](#point-in-time-recovery-pitr)). !!!info Important + Consider using the `barmanObjectStore.wal.maxParallel` option to speed up WAL fetching from the archive by concurrently downloading the transaction logs from the recovery object store. @@ -270,6 +299,7 @@ time. PostgreSQL uses this technique to achieve PITR. The presence of a WAL archive is mandatory. !!!info Important + PITR requires you to specify a recovery target by using the options described in [Recovery targets](#recovery-targets). !!! @@ -323,6 +353,7 @@ If you assign a value to it (in the form of a Barman backup ID), the operator uses that backup as the base for the recovery. !!!info Important + You need to make sure that such a backup exists and is accessible. !!! @@ -375,22 +406,21 @@ spec: serverName: cluster-example ``` -This setup enables {{name.ln}} to restore the base data from a volume -snapshot and apply WAL segments from the object store to reach the desired -recovery target. - !!!note + If the backed-up cluster had `walStorage` enabled, you also must specify the volume snapshot containing the `PGWAL` directory, as mentioned in [Recovery from VolumeSnapshot objects](#recovery-from-volumesnapshot-objects). !!! !!!warning + It's your responsibility to ensure that the end time of the base backup in the volume snapshot is before the recovery target timestamp. !!! !!!warning + If you added or removed a [tablespace](tablespaces.md) in your cluster since the last base backup, replaying the WAL will fail. You need a base backup between the time of the tablespace change and the recovery target @@ -408,17 +438,20 @@ targetTime (The precise stopping point is also influenced by the `exclusive` option.) !!!note + Timestamps without an explicit timezone suffix (e.g., `2023-07-06 08:00:39`) are interpreted as UTC. !!! !!!warning + Always specify an explicit timezone in your timestamp to avoid ambiguity. For example, use `2023-07-06T08:00:39Z` or `2023-07-06T08:00:39+02:00` instead of `2023-07-06 08:00:39`. !!! !!!warning + PostgreSQL recovery will stop when it encounters the first transaction that occurs after the specified time. If no such transaction exists after the target time, the recovery process will fail. @@ -446,6 +479,7 @@ targetImmediate taking the backup ended. !!!info Important + The operator can retrieve the closest backup when you specify either `targetTime` or `targetLSN`. However, this isn't possible for the remaining targets: `targetName`, `targetXID`, and `targetImmediate`. In such cases, it's @@ -521,6 +555,7 @@ See [Bootstrap an empty cluster](bootstrap.md#bootstrap-an-empty-cluster-initdb) for more information about secrets. !!!info Important + While the `Cluster` is in recovery mode, no changes to the database, including the catalog, are permitted. This restriction includes any role overrides, which are deferred until the `Cluster` transitions to primary. @@ -572,6 +607,7 @@ For details and instructions on the `recovery` bootstrap method, see [Bootstrap from a backup](bootstrap.md#bootstrap-from-a-backup-recovery). !!!info Important + If you're not familiar with how [PostgreSQL PITR](https://www.postgresql.org/docs/current/continuous-archiving.html#BACKUP-PITR-RECOVERY) works, we suggest that you configure the recovery cluster as the original @@ -584,6 +620,7 @@ instance of the new cluster, and the init container starts recovering the backup from the object storage. !!!info Important + The duration of the base backup copy in the new PVC depends on the size of the backup, as well as the speed of both the network and the storage. @@ -628,10 +665,52 @@ fail with an error. The pod logs will display: `ERROR: WAL archive check failed for server recoveredCluster: Expected empty archive`. !!! +For example, this section is part of a manifest for a cluster bootstrapping +from the cluster `cluster-example-backup`. In the storage bucket, it creates a +folder named `recoveredCluster`, where the base backups and WALs of the +recovered cluster are stored. + +```yaml + backup: + barmanObjectStore: + destinationPath: s3://backups/ + endpointURL: http://minio:9000 + serverName: "recoveredCluster" + s3Credentials: + accessKeyId: + name: minio + key: ACCESS_KEY_ID + secretAccessKey: + name: minio + key: ACCESS_SECRET_KEY + retentionPolicy: "30d" + + externalClusters: + - name: cluster-example-backup + barmanObjectStore: + destinationPath: s3://backups/ + endpointURL: http://minio:9000 + s3Credentials: +``` + +Don't reuse the same `barmanObjectStore` configuration for different clusters. +There might be cases where the existing information in the storage buckets +could be overwritten by the new cluster. + +!!!warning + +The operator includes a safety check to ensure a cluster doesn't overwrite +a storage bucket that contained information. A cluster that would overwrite +existing storage remains in the state `Setting up primary` with pods in an +error state. The pod logs show: `ERROR: WAL archive check failed for server +recoveredCluster: Expected empty archive`. +!!! + !!!info Important -You can bypass this safety check by setting the -`k8s.enterprisedb.io/skipEmptyWalArchiveCheck` annotation to `enabled` on the recovered -cluster. However, this is strongly discouraged unless you are highly -familiar with PostgreSQL's recovery process. Skipping the check incorrectly can -lead to severe data loss. Use with caution and only in expert scenarios. + +If you set the `k8s.enterprisedb.io/skipEmptyWalArchiveCheck` annotation to `enabled` +in the recovered cluster, you can skip the safety check. We don't recommend +skipping the check because, for the general use case, the check works fine. +Skip this check only if you're familiar with the PostgreSQL recovery system, as +severe data loss can occur. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/rel_notes/src/1.22.11_rel_notes.yml b/product_docs/docs/postgres_for_kubernetes/1/rel_notes/src/1.22.11_rel_notes.yml index 02ba3841c7..e34e20e87f 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/rel_notes/src/1.22.11_rel_notes.yml +++ b/product_docs/docs/postgres_for_kubernetes/1/rel_notes/src/1.22.11_rel_notes.yml @@ -3,55 +3,54 @@ product: EDB CloudNativePG Cluster version: 1.22.11 date: 25 July 2025 intro: | - EDB Postgres for Kubernetes version 1.22.11 is an LTS release of EDB Postgres for Kubernetes; - there is no corresponding upstream release of CloudNativePG. - - *In memory of [DJ Walker-Morgan](https://www.linkedin.com/in/codepope/).* - - !!! Warning - This is expected to be the last release in the 1.22.x series. - Users are strongly encouraged to upgrade to a newer minor version, as 1.22 - is no longer supported. - - This release of EDB CloudNativePG Cluster includes the following: + This release of EDB Postgres® AI for CloudNativePG™ Cluster includes the following: components: "Operator": 1.22.11 "CNP plugin": 1.22.11 - upstream-merge: None - + upstream-merge: Upstream [1.22.11](https://cloudnative-pg.io/docs/1.22/release_notes/v1.22/) relnotes: -- relnote: Removed `386` and ARM (v5/v6/v7) architectures from the `cnp` plugin build matrix - details: | - ...reducing the number of published binaries. - jira: - addresses: #7648 +- relnote: | + Removed `386` and ARM (v5/v6/v7) architectures from the `cnp` plugin build + matrix, reducing the number of published binaries + ([#7648](https://github.com/EnterpriseDB/cloud-native-postgres/pull/7648)). + jira: + addresses: type: Change impact: High -- relnote: Improved validation of `shared_buffers` by correctly considering `HugePages` settings - details: | - ...ensuring accurate memory configuration checks. - jira: - addresses: #7864 + +- relnote: | + Improved validation of `shared_buffers` by correctly considering `HugePages` + settings, ensuring accurate memory configuration checks + ([#7864](https://github.com/EnterpriseDB/cloud-native-postgres/pull/7864)). + jira: + addresses: type: Enhancement impact: High -- relnote: Set `oom_score_adj` for PostgreSQL worker processes - details: | - ...to improve prioritization during out-of-memory situations. - jira: - addresses: #7891 + +- relnote: | + Set `oom_score_adj` for PostgreSQL worker processes to improve prioritization + during out-of-memory situations + ([#7891](https://github.com/EnterpriseDB/cloud-native-postgres/pull/7891)). + jira: + addresses: type: Enhancement impact: High -- relnote: Added the `systemID` field and related condition in the `Cluster` status - details: | - ...to track the PostgreSQL system identifier. - jira: - addresses: #7717 + +- relnote: | + Added the `systemID` field and related condition in the `Cluster` status to + track the PostgreSQL system identifier. + ([#7717](https://github.com/EnterpriseDB/cloud-native-postgres/pull/7717)). + jira: + addresses: type: Enhancement impact: High -- relnote: Added a mutex in the connection pooler to protect concurrent access to the connections map - details: | - ...improving stability in high-concurrency environments. - jira: - addresses: #7804 - type: Bug fix + +- relnote: | + Added a mutex in the connection pooler to protect concurrent access to the + connections map, improving stability in high-concurrency environments + ([#7804](https://github.com/EnterpriseDB/cloud-native-postgres/pull/7804)). + jira: + addresses: + type: Bug Fix impact: High + diff --git a/product_docs/docs/postgres_for_kubernetes/1/rel_notes/src/1.25.9_rel_notes.yml b/product_docs/docs/postgres_for_kubernetes/1/rel_notes/src/1.25.9_rel_notes.yml new file mode 100644 index 0000000000..5dfceafd00 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/rel_notes/src/1.25.9_rel_notes.yml @@ -0,0 +1,424 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/EnterpriseDB/docs/refs/heads/develop/tools/automation/generators/relgen/relnote-schema.json +product: EDB CloudNativePG Cluster +version: 1.25.9 +date: 29 June 2026 +intro: | + This release of EDB CloudNativePG Cluster is part of the LTS series for 1.25.x. + EDB will continue providing LTS releases in the 1.25.x series according to our [Long-Term Support + policy](/postgres_for_kubernetes/1/#long-term-support). + + !!! Warning EDB CloudNativePG Cluster 1.25 approaches End-of-Life. + + Users are encouraged to start planning their upgrade to a newer minor + version before that date. + + !!! + + This release of EDB CloudNativePG Cluster includes the following: +components: + "Operator": 1.25.9 + "CNP plugin": 1.25.9 + upstream-merge: None +highlights: | + The `cluster` reference is now immutable on the `Database`, `Pooler`, + `Publication`, `Subscription`, and `ScheduledBackup` resources. Pointing one + of these objects at a different cluster has no well-defined semantics and + previously left the controllers in an inconsistent state; the update is now + rejected at the API server via a CEL validation rule. + ([#10743](https://github.com/cloudnative-pg/cloudnative-pg/pull/10743)) +relnotes: +- relnote: | + Added a label selector to the `Cluster` scale subresource (`status.selector`), + making a `Cluster` a valid `targetRef` for the Vertical Pod Autoscaler (VPA) + and Horizontal Pod Autoscaler (HPA), which can now map a `Cluster` to its + instance pods. + details: | + Contributed by @sebv004. + jira: + addresses: #8996 + type: Enhancement + impact: High + +- relnote: | + The operator now emits a `Warning` `PrimaryStatusCheckFailed` event on the + `Cluster` when the primary pod is `Ready` from the kubelet perspective but the + operator's `/pg/status` check fails and failover is deferred, giving users + visibility into the deferral via `kubectl describe cluster`. + jira: + addresses: #10509 + type: Enhancement + impact: High + +- relnote: | + The operator now reloads a CNPG-i plugin automatically when its pods are + rolled: it watches the `EndpointSlices` backing plugin `Services` and + re-enqueues every cluster using the plugin once the new pods become `Ready`, + so an upgraded plugin is picked up without waiting for the next resync. + jira: + addresses: #10836 + type: Enhancement + impact: High + +- relnote: | + `CVE-2026-55769` / `GHSA-x8c2-3p4r-v9r6`: `search_path` pinning on + operator-issued connections + details: | + a database owner could plant overloaded built-in operators in the `public` + schema and alter the `search_path` so that operator introspection probes, + running as the cluster superuser, resolved those overloads before + `pg_catalog`, a `CWE-426` privilege-escalation chain (same class as + `CVE-2018-1058`) that could lead to in-pod RCE via `COPY ... FROM PROGRAM`. + The operator now pins `search_path = pg_catalog, public, pg_temp` on every + pooled connection so it ships in the startup message and takes precedence over + tenant-controlled defaults. + jira: + addresses: #10774, GHSA-x8c2-3p4r-v9r6 + type: Security + impact: High + +- relnote: | + `CVE-2026-55765` / `GHSA-w3gf-xc94-wvmj`: operator-side SCRAM-SHA-256 password + encoding + details: | + the operator now SCRAM-SHA-256 encodes cleartext role passwords before issuing + `CREATE`/`ALTER ROLE ... PASSWORD`, so the literal PostgreSQL parses (and that + extensions such as `pg_stat_statements` or `pgaudit` may capture) is the SCRAM + verifier rather than the cleartext secret. Pre-hashed (MD5 or SCRAM) values + are forwarded unchanged, and the per-Secret annotation + `k8s.enterprisedb.io/passwordPassthrough: "enabled"` opts out. + jira: + addresses: #10724, GHSA-w3gf-xc94-wvmj + type: Security + impact: High + +- relnote: | + Updated the default PostgreSQL version to 18.4. + jira: + addresses: #10719 + type: Change + impact: High + +- relnote: | + Updated the Kubernetes versions used to test the operator on public cloud + providers. + jira: + addresses: #10720, #10563, #11033 + type: Change + impact: High + +- relnote: | + Fixed `spec.postgresql.parameters` accepting keys that are not valid + PostgreSQL parameter names, which could inject arbitrary directives into + `postgresql.conf`; key names are now validated by the webhook. + jira: + addresses: #11029 + type: Bug Fix + impact: High + +- relnote: | + Fixed declarative `Database`, `Publication`, and `Subscription` objects + reporting a stale primary-side status forever after their cluster was demoted + to a replica; the controller now re-checks the replica condition and watches + the `Cluster` so a demotion is detected promptly. + jira: + addresses: #10871 + type: Bug Fix + impact: High + +- relnote: | + Fixed non-sequential pod names (for example `-1`, `-3`) caused by the instance + serial counter being advanced before the corresponding `Job` and PVCs were + created; the bump is now persisted only after those resources exist. + jira: + addresses: #10491 + type: Bug Fix + impact: High + +- relnote: | + Fixed a switchover deadlock when a WAL-archiver plugin was enabled on an + existing cluster: with `primaryUpdateMethod: switchover` the primary could not + be rolled out because a clean demotion needs the archiver sidecar that is + still missing. + details: | + The operator now recreates the primary Pod in place so the sidecar is injected + and archiving resumes. The check also covers plugins that inject the archiver + as a native sidecar (an init container with `restartPolicy: Always`), such as + the Barman Cloud plugin. + jira: + addresses: #11032, #11059 + type: Bug Fix + impact: High + +- relnote: | + Fixed a cluster staying in `Setting up primary` indefinitely when the + instance-creation Job exhausted its backoff limit; the operator now detects + the terminal Job failure and marks the cluster unrecoverable, naming the + failed Job and pointing to its logs. + jira: + addresses: #11035 + type: Bug Fix + impact: High + +- relnote: | + Fixed deletion of a `Database`, `Publication`, or `Subscription` getting stuck + in `Terminating` on a replica cluster, where the replica gate ran before the + finalizer reconciler and the finalizer was never released. + details: | + On a replica the PostgreSQL object is left to the primary cluster. + jira: + addresses: #10853 + type: Bug Fix + impact: High + +- relnote: | + Fixed a conflicting duplicate `Database` or `Subscription` with a `delete` + reclaim policy dropping the PostgreSQL object owned by the surviving CR; the + drop is now gated on a recorded reconciliation. + jira: + addresses: #10870 + type: Bug Fix + impact: High + +- relnote: | + Fixed the `postgres` superuser being left locked out after superuser access + was disabled and then re-enabled, because the cached secret version was not + invalidated and the password was never re-applied. + details: | + Diagnosed by @mhartmann-jaconi. + jira: + addresses: #10834 + type: Bug Fix + impact: High + +- relnote: | + Fixed resource leaks when concurrent `Backup` objects raced: backups now run + in strict creation-time order, so an already-executing backup is never + preempted by a newer one and its replication slot and PostgreSQL session are + no longer orphaned on the primary. + details: | + Contributed by @GabriFedi97. + jira: + addresses: #10747 + type: Bug Fix + impact: High + +- relnote: | + Fixed role reconciliation clearing the password on a PostgreSQL role when the + referenced Secret could not be fetched; the role is now left untouched until + the Secret becomes available, and per-action errors are aggregated for better + visibility. + jira: + addresses: #10053 + type: Bug Fix + impact: High + +- relnote: | + Fixed a bootstrap failure where a metrics-exporter setup error (commonly a + duplicate-key race with the controller) rolled back `streaming_replica` + creation and wedged replica joins. + details: | + The metrics-exporter step now runs in a separate transaction. Contributed by + @BlaiseAntony. + jira: + addresses: #10749 + type: Bug Fix + impact: High + +- relnote: | + Fixed a `ScheduledBackup` controller loop that occurred when a `Backup` was + created but its status patch never landed; the controller now adopts an + existing `Backup` for the next iteration instead of looping on + `AlreadyExists`. + jira: + addresses: #10612 + type: Bug Fix + impact: High + +- relnote: | + Fixed bootstrap log handling so that all named log pipes (`postgres`, + `postgres.csv`, and `postgres.json`) get consumers during + `WithActiveInstance`, preventing regular files from being created in place of + the named pipes. + jira: + addresses: #10043 + type: Bug Fix + impact: High + +- relnote: | + Fixed generation of invalid IPv6 URLs by wrapping the address in square + brackets. + details: | + Contributed by @Infinoid. + jira: + addresses: #10682 + type: Bug Fix + impact: High + +- relnote: | + Fixed an external cluster plugin still being treated as active when its + configuration set `enabled: false`. + jira: + addresses: #10932 + type: Bug Fix + impact: High + +- relnote: | + Fixed a race during bootstrap recovery from an object store where the restore + job could read a stale `Cluster` (primary not yet recorded and timeline still + unset) and have its `.history` files rejected by the split-brain guard. + details: | + When this happened, recovery stopped at the base backup's timeline and + silently dropped transactions committed on later timelines. History files are + now allowed while the cluster timeline is unset. Contributed by @dennispidun. + jira: + addresses: #10818 + type: Bug Fix + impact: High + +- relnote: | + Fixed a cache race during cluster creation when the server and client CA + resolve to the same Secret (the default): a stale informer cache triggered a + redundant `Create` that failed with `AlreadyExists` and could leave the + cluster stuck in `Unable to create required cluster objects`. + details: | + The operator now reuses the already-fetched CA Secret when the names match. + jira: + addresses: #10989 + type: Bug Fix + impact: High + +- relnote: | + Fixed the `pg_basebackup` bootstrap path overwriting or failing on a + pre-existing `PGDATA` (for example after a replica Pod restart) by enforcing + the same pre-flight directory check already applied by the other bootstrap + methods; this also protects statically provisioned PVCs from being silently + overwritten. + jira: + addresses: #11006 + type: Bug Fix + impact: High + +- relnote: | + Fixed the `Cluster` phase flapping between `Healthy` and a plugin-failure + phase when a post-reconcile plugin hook returned an error; the `Healthy` phase + is now registered as the last step of a successful reconciliation, so a loop + that ends in a plugin error never reports `Healthy`. + details: | + Contributed by @GabriFedi97. + jira: + addresses: #10421 + type: Bug Fix + impact: High + +- relnote: | + Fixed stale certificate data and partial reads after an external server's + Secret was rotated (for example a CA bundle shrinking from two certificates to + one): the file is now written atomically, so libpq always reads either the old + or the new value, never a mix. + details: | + Contributed by @Anand-240. + jira: + addresses: #10975 + type: Bug Fix + impact: High + +- relnote: | + Fixed plugin connectivity to use the plugin `Service` FQDN instead of its + short name, avoiding failures when a cluster-level proxy is automatically + injected into pods. + details: | + Contributed by @kdautrey. + jira: + addresses: #10921 + type: Bug Fix + impact: High + +- relnote: | + Fixed excessive operator log noise from the per-request `Cluster` + create/update validation webhook messages, now logged at `debug` instead of + `info`. + jira: + addresses: #10984 + type: Bug Fix + impact: High + +- relnote: | + Fixed a first-primary bootstrap deadlock where a status-patch conflict after + the data PVC was created but before the initialization Job was started left + the orphan Pending PVC counted as an instance, blocking the bootstrap gate; + the PVC-state reconciler now recreates the bootstrap Job reusing the assigned + serial. + jira: + addresses: #11039 + type: Bug Fix + impact: High + +- relnote: | + Fixed external cluster names and secret selector references being joined into + filesystem paths without validation, letting a `..` component or path + separator escape the external secrets directory when the instance manager + dumps connection material; these values are now rejected at the validating + webhook and re-checked at the write site. + details: | + Reported by @r0binak. + jira: + addresses: #11045 + type: Bug Fix + impact: High + +- relnote: | + Fixed a declarative `VolumeSnapshot` backup being permanently marked as failed + when a stale cache made the operator re-create a snapshot it had already + provisioned, failing with `AlreadyExists`. + details: | + The operator now tolerates the collision when the existing snapshot carries + this backup's label and adopts it; a collision with a foreign snapshot still + surfaces as an error. + jira: + addresses: #11071 + type: Bug Fix + impact: High + +- relnote: | + Fixed a volume snapshot backup being discarded on a transient instance-manager + connection error (for example a dial timeout from a brief pod-network + disruption) during the finalize step, even when its snapshots were already + provisioned; such network errors are now retried instead of treated as + terminal. + jira: + addresses: #11069 + type: Bug Fix + impact: High + +- relnote: | + Fixed a replica switchover losing its `status.demotionToken` when a reconcile + was requeued between storing the token and cleaning up the transition metadata + (for example a cleanup patch failing against a flaky webhook); the empty + no-change token is no longer patched back over the stored value. + jira: + addresses: #11075 + type: Bug Fix + impact: High + +- relnote: | + Fixed `kubectl cnp psql` on Windows, where execution relied on a Unix-only + system call and failed with "not supported by windows"; Windows now launches + `kubectl exec` as a child process. + details: | + Contributed by @Utkarsh-sharma47. + jira: + addresses: #10972 + type: Bug Fix + impact: High + +- relnote: | + Fixed an unbounded memory leak in `kubectl cnp logs -f` on busy clusters, + where a per-log-group timer was never released; timers are now reused across + iterations. + details: | + Contributed by @Anand-240. + jira: + addresses: #10976 + type: Bug Fix + impact: High + diff --git a/product_docs/docs/postgres_for_kubernetes/1/replica_cluster.mdx b/product_docs/docs/postgres_for_kubernetes/1/replica_cluster.mdx index a3120c143a..b8dc7a068c 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/replica_cluster.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/replica_cluster.mdx @@ -267,6 +267,7 @@ involving: These processes are described in the next sections. !!!info Important + Before you proceed, ensure you review the ["About PostgreSQL Roles" section](#about-postgresql-roles) above and use identical role definitions, including secrets, in all `Cluster` objects participating in the distributed topology. @@ -324,6 +325,7 @@ You can obtain the `demotionToken` using the `cnp` plugin by checking the cluster's status. The token is listed under the `Demotion token` section. !!!note + The `demotionToken` obtained from `cluster-eu-south` will serve as the `promotionToken` for `cluster-eu-central`. !!! @@ -357,6 +359,7 @@ replica: ``` !!!warning + It is crucial to apply the changes to the `primary` and `promotionToken` fields simultaneously. If the promotion token is omitted, a failover will be triggered, necessitating a rebuild of the former primary. @@ -388,6 +391,7 @@ clusters. ## Standalone Replica Clusters !!!info Important + Standalone Replica Clusters were previously known as Replica Clusters before the introduction of the Distributed Topology strategy in {{name.ln}} 1.24. @@ -405,12 +409,14 @@ continuous recovery mode and becomes a primary cluster, completely detached from the original source. !!!warning + Disabling replication is an **irreversible** operation. Once replication is disabled and the designated primary is promoted to primary, the replica cluster and the source cluster become two independent clusters definitively. !!! !!!info Important + Standalone replica clusters are suitable for several use cases, primarily involving read-only workloads. If you are planning to setup a disaster recovery solution, look into "Distributed Topology" above. @@ -541,6 +547,7 @@ a backup of the source cluster has been created already. ``` !!!note + To use streaming replication between the source cluster and the replica cluster, we need to make sure there is network connectivity between the two clusters, and that all the necessary secrets which hold passwords or @@ -622,6 +629,7 @@ The main use cases of delayed replicas can be summarized into: undesirable changes. !!!warning + The `minApplyDelay` option of delayed replicas cannot be used in conjunction with `promotionToken`. !!! @@ -632,6 +640,7 @@ Adjust the delay duration based on your specific needs and the criticality of your data. !!!info Important + Always measure your goals. Depending on your environment, it might be more efficient to rely on volume snapshot-based recovery for faster outcomes. Evaluate and choose the approach that best aligns with your unique requirements diff --git a/product_docs/docs/postgres_for_kubernetes/1/replication.mdx b/product_docs/docs/postgres_for_kubernetes/1/replication.mdx index 9a6acc772e..e2d3124da7 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/replication.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/replication.mdx @@ -12,6 +12,7 @@ achieve high availability, physical replication also allows scale-out of read-only workloads and offloading of some work from the primary. !!!info Important + This section is about replication within the same `Cluster` resource managed in the same Kubernetes cluster. For information about how to replicate with another Postgres `Cluster` resource, even across different @@ -91,6 +92,7 @@ hostssl replication streaming_replica all cert map=cnp_streaming_replica ``` !!!note Certificates + For details on how {{name.ln}} manages certificates, please refer to the ["Certificates" section](certificates.md#client-streaming_replica-certificate) in the documentation. @@ -101,6 +103,7 @@ HA cluster, ensuring that WAL files required by each standby are retained on the primary's storage, even after a failover or switchover. !!!note Replication slots for High Availability + For details on how {{name.ln}} automatically manages replication slots for the High Availability replicas, please refer to the ["Replication slots for High Availability" section](#replication-slots-for-high-availability) @@ -120,6 +123,7 @@ fallback option whenever pulling WALs via streaming replication fails. [quorum-based and priority-based synchronous replication for PostgreSQL](https://www.postgresql.org/docs/current/warm-standby.html#SYNCHRONOUS-REPLICATION). !!!warning + By default, synchronous replication pauses write operations if the required number of standby nodes for WAL replication during transaction commits is unavailable. This behavior prioritizes data durability and aligns with @@ -129,12 +133,6 @@ details on managing this behavior, refer to the [Data Durability and Synchronous section. !!! -!!!info Important -The [*failover quorum* feature](failover.md#failover-quorum-quorum-based-failover) -can be used alongside synchronous replication to improve data durability -and safety during failover events. -!!! - Direct configuration of the `synchronous_standby_names` option is not permitted. However, {{name.ln}} automatically populates this option with the names of local pods, while also allowing customization to extend synchronous @@ -233,6 +231,7 @@ immediately replaced by the next-highest-priority standby. To use this method, set `method` to `first`. !!!info Important + Currently, this method is most useful when extending synchronous replication beyond the current cluster using the `maxStandbyNamesFromCluster`, `standbyNamesPre`, and `standbyNamesPost` @@ -259,6 +258,7 @@ the PostgreSQL cluster. You can customize the content of operator. !!!warning + You are responsible for ensuring the correct names in `standbyNamesPre` and `standbyNamesPost`. {{name.ln}} expects that you manage any standby with an `application_name` listed here, ensuring their high availability. @@ -334,6 +334,7 @@ replication. It can be set to `required` or `preferred`, with the default being `required` if not specified. !!!info Important + `preferred` can only be used when `standbyNamesPre` and `standbyNamesPost` are unset. !!! @@ -409,12 +410,11 @@ standbys, but write operations will continue even if fewer than the requested number of standbys are available. !!!info Important + Make sure you have a clear understanding of what *ready/available* means for a replica and set your expectations accordingly. By default, a replica is considered ready when it has successfully connected to the source at least -once. However, {{name.ln}} allows you to configure startup and readiness -probes for replicas based on maximum lag. For more details, please refer to -the ["Postgres instance manager" section](instance_manager.md). +once. !!! This setting balances data safety with availability, enabling applications to @@ -422,6 +422,7 @@ continue writing during temporary standby unavailability—hence, it’s also kn as *self-healing mode*. !!!warning + This mode may result in data loss if all standbys become unavailable. !!! @@ -477,6 +478,7 @@ spec: ## Synchronous Replication (Deprecated) !!!warning + Prior to {{name.ln}} 1.24, only the quorum-based synchronous replication implementation was supported. Although this method is now deprecated, it will not be removed anytime soon. @@ -488,6 +490,7 @@ synchronous replication, as explained in the previous paragraph. !!! !!!info Important + The deprecated method and the new method are mutually exclusive. !!! @@ -499,6 +502,7 @@ For self-healing purposes, the operator always compares these two values with the number of available replicas to determine the quorum. !!!info Important + By default, synchronous replication selects among all the available replicas indistinctively. You can limit on which nodes your synchronous replicas can be scheduled, by working on node labels through the @@ -522,6 +526,7 @@ Where: - `pod1, pod2, ...` is the list of all PostgreSQL pods in the cluster !!!warning + To provide self-healing capabilities, the operator can ignore `minSyncReplicas` if such value is higher than the currently available number of replicas. Synchronous replication is automatically disabled @@ -535,6 +540,7 @@ transaction commits wait until their WAL records are replicated to at least the requested number of synchronous standbys in the list*. !!!info Important + Even though the operator chooses self-healing over enforcement of synchronous replication settings, our recommendation is to plan for synchronous replication only in clusters with 3+ instances or, @@ -549,11 +555,13 @@ rules based on the node labels where the PVC holding the PGDATA and the Postgres pod are. !!!note Scheduling + For more information on the general pod affinity and anti-affinity rules, please check the ["Scheduling" section](scheduling.md). !!! !!!warning + The `.spec.postgresql.syncReplicaElectionConstraint` option only applies to the legacy implementation of synchronous replication (see ["Synchronous Replication (Deprecated)"](replication.md#synchronous-replication-deprecated)). @@ -575,6 +583,7 @@ where the primary is currently in execution. If no node matches such criteria, the replicas are eligible for synchronous replication. !!!info Important + The self-healing enforcement still applies while defining additional constraints for synchronous replica election (see ["Synchronous replication"](replication.md#synchronous-replication)). @@ -691,6 +700,7 @@ Although {{name.ln}} doesn't support a way to declaratively define physical replication slots, you can still [create your own slots via SQL](https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-REPLICATION). !!!note Information + At the moment, we don't have any plans to manage replication slots in a declarative way, but it might change depending on the feedback we receive from users. The reason is that replication slots exist @@ -737,6 +747,7 @@ Here follows a brief description of the main options: exclude specific slots based on naming conventions. !!!warning + Users utilizing this feature should carefully monitor user-defined replication slots to ensure they align with their operational requirements and do not interfere with the failover process. @@ -867,6 +878,7 @@ key information such as the name of the slot, the type, whether it is active, the lag from the primary. !!!note Monitoring + Please refer to the ["Monitoring" section](monitoring.md) for details on how to monitor a {{name.ln}} deployment. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/resource_management.mdx b/product_docs/docs/postgres_for_kubernetes/1/resource_management.mdx index 74ef4be2d8..909dc6a4dc 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/resource_management.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/resource_management.mdx @@ -45,6 +45,7 @@ section in the Kubernetes documentation. For a PostgreSQL workload it is recommended to set a "Guaranteed" QoS. !!!info + When the quality of service is set to "Guaranteed", {{name.ln}} sets the `PG_OOM_ADJUST_VALUE` for the `postmaster` process to `0`, in line with the [PostgreSQL documentation](https://www.postgresql.org/docs/current/kernel-resources.html#LINUX-MEMORY-OVERCOMMIT). @@ -110,7 +111,81 @@ For more details, please refer to the ["Resource Consumption"](https://www.postg section in the PostgreSQL documentation. !!!note Managing Compute Resources for Containers + For more details on resource management, please refer to the ["Managing Compute Resources for Containers"](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/) page from the Kubernetes documentation. !!! + +## Integration with the Vertical Pod Autoscaler (VPA) + +The `Cluster` CRD exposes the `scale` subresource together with the label +selector for its instance pods. This makes a `Cluster` a valid `targetRef` for the +[Vertical Pod Autoscaler](https://github.com/kubernetes/autoscaler/tree/master/vertical-pod-autoscaler) +(VPA), so VPA can observe the instance pods and emit CPU and memory +recommendations for them. + +We recommend running VPA in **recommendation-only** mode +(`updatePolicy.updateMode: Off`). In this mode VPA only reports its +recommendations, which an operator can then apply to `spec.resources` of the +`Cluster` through a normal manifest update; {{name.ln}} performs the rolling +update of the instances using its usual switchover-aware procedure. VPA +produces a recommendation per container: use the one for the `postgres` +container, since that is what `spec.resources` configures. + +Example targeting a `Cluster`: + +```yaml +apiVersion: autoscaling.k8s.io/v1 +kind: VerticalPodAutoscaler +metadata: + name: cluster-example-vpa +spec: + targetRef: + apiVersion: postgresql.k8s.enterprisedb.io/v1 + kind: Cluster + name: cluster-example + updatePolicy: + updateMode: "Off" +``` + +!!!warning + +Do not use `updateMode: Auto`, `Recreate`, or `Initial` against a +{{name.ln}}-managed `Cluster`. The operator owns the pod specification and +treats `spec.resources` of the `Cluster` as the source of truth: it does not +adopt the resources VPA writes onto a running pod, so the live pod and the +declared `spec.resources` silently diverge. Any tuning you sized against the +declared resources (for example a `shared_buffers` value the operator +validated against the memory request) no longer matches the pod's actual +limits. VPA also evicts pods through the Kubernetes eviction API, bypassing +the operator's switchover-aware sequencing; the default primary +`PodDisruptionBudget` then blocks eviction of the primary, so VPA stalls +instead of completing. Apply the VPA recommendations to the `Cluster` manifest +manually instead. +!!! + +## Integration with the Horizontal Pod Autoscaler (HPA) + +The `scale` subresource also exposes `spec.instances`, so a +[Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) +(HPA) can technically change the number of instances in a `Cluster`. +In practice this is **not recommended** for a PostgreSQL cluster, for several +reasons. + +Scaling a `Cluster` only adds or removes standby replicas; it never relieves +write load on the primary. The selector exposed through the scale subresource +matches the primary and all replicas, which have opposite workload profiles +(write-heavy primary, read-only replicas), so the per-pod average that HPA +computes from a CPU or memory metric is not a meaningful signal for any of +them. Adding a replica only dilutes that average further without addressing a +hot primary. + +HPA is also unaware of {{name.ln}}' own constraints on `spec.instances`. If +you configure synchronous replicas, a scale-down below `maxSyncReplicas + 1` +instances is rejected by the validating webhook, and HPA keeps retrying a +value it cannot satisfy. +If you nonetheless drive `spec.instances` from an HPA, base it on a custom +metric that actually reflects read replica load, and set `minReplicas` above +the synchronous-replica floor. Review the impact on replication and quorum +carefully first. diff --git a/product_docs/docs/postgres_for_kubernetes/1/rolling_update.mdx b/product_docs/docs/postgres_for_kubernetes/1/rolling_update.mdx index 53e19e73fd..771f16bcf7 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/rolling_update.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/rolling_update.mdx @@ -5,6 +5,14 @@ originalFilePath: 'src/rolling_update.md' +The operator allows changing the PostgreSQL version used in a cluster while +applications are running against it. + +!!!info Important + +Only upgrades for PostgreSQL minor releases are supported. +!!! + The operator allows you to change the PostgreSQL version used in a cluster while applications continue running against it. diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples.mdx b/product_docs/docs/postgres_for_kubernetes/1/samples.mdx index a8a5727ee6..90eef61b54 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/samples.mdx @@ -9,12 +9,14 @@ The examples show configuration files for setting up your PostgreSQL cluster. !!!info Important + These examples are for demonstration and experimentation purposes. You can execute them on a personal Kubernetes cluster with Minikube or Kind, as described in [Quick start](quickstart.md). !!! !!!note Reference + For a list of available options, see [API reference](pg4k.v1.md). !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-full.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-full.yaml index 988cd2596e..60f5fbac53 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-full.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-full.yaml @@ -35,7 +35,7 @@ metadata: name: cluster-example-full spec: description: "Example of cluster" - imageName: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 + imageName: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 # imagePullSecret is only required if the images are located in a private registry # imagePullSecrets: # - name: private_registry_access diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/postgis-example.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/postgis-example.yaml index 99491f8322..f2685c7b82 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/postgis-example.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/postgis-example.yaml @@ -3,8 +3,15 @@ kind: Cluster metadata: name: postgis-example spec: - imageName: docker.enterprisedb.com/k8s_enterprise/postgresql:18.3-minimal-ubi9 - instances: 1 + instances: 3 + imageName: ghcr.io/cloudnative-pg/postgis:18.4-3.6.2-standard-ubi9 + bootstrap: + initdb: + postInitTemplateSQL: + - CREATE EXTENSION postgis; + - CREATE EXTENSION postgis_topology; + - CREATE EXTENSION fuzzystrmatch; + - CREATE EXTENSION postgis_tiger_geocoder; storage: size: 1Gi diff --git a/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx b/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx index 30af886cee..cf169aef98 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx @@ -9,6 +9,7 @@ Scheduling, in Kubernetes, is the process responsible for placing a new pod on the best node possible, based on several criteria. !!!note Kubernetes documentation + Please refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/) for more information on scheduling, including all the available policies. On @@ -46,7 +47,7 @@ metadata: name: cluster-example spec: instances: 3 - imageName: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 + imageName: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 affinity: enablePodAntiAffinity: true # Default value @@ -95,6 +96,7 @@ if resources are insufficient—this is particularly relevant when using [Cluste for automated horizontal scaling in a Kubernetes cluster. !!!note Inter-pod Affinity and Anti-Affinity + For more details, refer to the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity). !!! @@ -119,6 +121,7 @@ be added to those generated by the operator, if enabled, or used directly if the operator-generated rules are disabled. !!!note + When using `additionalPodAntiAffinity` or `additionalPodAffinity`, you must provide the full `podAntiAffinity` or `podAffinity` structure expected by the Pod specification. The following YAML example demonstrates how to configure @@ -161,6 +164,7 @@ Tolerations can be configured for all the pods of a Cluster through the for tolerations. !!!note Taints and Tolerations + More information on taints and tolerations can be found in the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/). !!! @@ -168,6 +172,7 @@ More information on taints and tolerations can be found in the ## Isolating PostgreSQL workloads !!!info Important + Before proceeding, please ensure you have read the ["Architecture"](architecture.md) section of the documentation. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/service_management.mdx b/product_docs/docs/postgres_for_kubernetes/1/service_management.mdx index 852e8e95b7..feb9c81fba 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/service_management.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/service_management.mdx @@ -22,6 +22,7 @@ resource, with the following conventions: - All services are of type `ClusterIP`. !!!info Important + Default service names are reserved for {{name.ln}} usage. !!! @@ -45,6 +46,7 @@ You can disable any or all of the `ro` and `r` default services through the [`managed.services.disabledDefaultServices` option](pg4k.v1.md#managedservices). !!!info Important + The `rw` service is essential and cannot be disabled because {{name.ln}} relies on it to ensure PostgreSQL replication. !!! @@ -62,6 +64,7 @@ managed: ## Adding Your Own Services !!!info Important + When defining your own services, you cannot use any of the default reserved service names that follow the convention `-`. It is your responsibility to pick a unique name for the service in the Kubernetes @@ -81,6 +84,7 @@ You must provide a `name` to the service and avoid defining the `selector` field, as it is managed by the operator. !!!warning + Service templates give you unlimited possibilities in terms of configuring network access to your PostgreSQL database. This translates into greater responsibility on your end to ensure that services work as expected. @@ -95,6 +99,7 @@ Alternatively, the `replace` strategy deletes the existing service and recreates it from the template. !!!warning + The `replace` strategy will cause a service disruption with every change. However, it may be necessary for modifying certain parameters that can only be set during service creation. @@ -138,6 +143,7 @@ Be aware that allowing access to a database from the public network could expose your database to potential attacks from malicious users. !!!warning + Ensure you secure your database before granting external access, or make sure your Kubernetes cluster is only reachable from a private network. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/ssl_connections.mdx b/product_docs/docs/postgres_for_kubernetes/1/ssl_connections.mdx index 7db15e04a8..54ccbe8afd 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/ssl_connections.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/ssl_connections.mdx @@ -5,6 +5,13 @@ originalFilePath: 'src/ssl_connections.md' +!!!note Certificates + +See [Certificates](certificates.md) +for more details on how {{name.ln}} supports TLS certificates. +!!! + + !!!note Certificates See [Certificates](certificates.md) for more details on how {{name.ln}} supports TLS certificates. @@ -27,6 +34,7 @@ convention by way of the `initdb` configuration in the `bootstrap` section.) ## Issuing a new certificate !!!note About CNP plugin for kubectl + See the [Certificates in the {{name.ln}} plugin](kubectl-plugin.md#certificates) content for details on how to use the plugin for kubectl. !!! @@ -180,7 +188,7 @@ Output: version -------------------------------------------------------------------------------------- ------------------ -PostgreSQL 18.3 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 8.3.1 20191121 (Red Hat +PostgreSQL 18.4 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 8.3.1 20191121 (Red Hat 8.3.1-5), 64-bit (1 row) ``` diff --git a/product_docs/docs/postgres_for_kubernetes/1/storage.mdx b/product_docs/docs/postgres_for_kubernetes/1/storage.mdx index 050fa804d5..ce122cd1fb 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/storage.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/storage.mdx @@ -12,6 +12,7 @@ requirements that apply to traditional environments, such as virtual machines and bare metal, are also valid in container contexts managed by Kubernetes. !!!info Important + When it comes to dynamically provisioned storage, Kubernetes has its own specifics. These include *storage classes*, *persistent volumes*, and *Persistent Volume Claims (PVCs)*. You need to own these @@ -38,6 +39,7 @@ for high transactional and very large database (VLDB) workloads, as it guarantees higher and more predictable performance. !!!warning + Before you deploy a PostgreSQL cluster with {{name.ln}}, ensure that the storage you're using is recommended for database workloads. We recommend clearly setting performance expectations by @@ -46,6 +48,7 @@ and then the database using [pgbench](https://www.postgresql.org/docs/current/pg !!! !!!info + {{name.ln}} doesn't use `StatefulSet` for managing data persistence. Rather, it manages PVCs directly. If you want to know more, see @@ -59,6 +62,7 @@ we recommend that you also consider this aspect when you choose your storage solution, especially if you manage very large databases. !!!info Important + See the Kubernetes documentation for a list of all the supported [container storage interface (CSI) drivers](https://kubernetes-csi.github.io/docs/drivers.html) that provide snapshot capabilities. @@ -79,6 +83,7 @@ Briefly, we recommend operating at two levels: distributed with PostgreSQL !!!info Important + You must measure both the storage and database performance before putting the database into production. These results are extremely valuable not just in the planning phase (for example, capacity planning). They are also valuable in @@ -116,6 +121,7 @@ defined as a *PVC group*. ## Configuration via a storage class !!!info Important + {{name.ln}} was designed to work interchangeably with all storage classes. As usual, we recommend properly benchmarking the storage class in a controlled environment before deploying to production. @@ -185,6 +191,7 @@ form of segment files. (`pg_wal` is historically known as `pg_xlog` in PostgreSQL.) !!!info + Normally, each segment is 16MB in size, but you can configure the size using the `walSegmentSize` option. This option is applied at cluster initialization time, as described in @@ -215,6 +222,7 @@ volume has a few benefits: for example, `PGDATA` requires resizing. !!!note Write-Ahead Log (WAL) + See [Reliability and the Write-Ahead Log](https://www.postgresql.org/docs/current/wal.html) in the PostgreSQL documentation for more information. !!! @@ -237,6 +245,7 @@ spec: ``` !!!info Important + Removing `walStorage` isn't supported. Once added, a separate volume for WALs can't be removed from an existing Postgres cluster. !!! @@ -272,6 +281,112 @@ doesn't support that, you must delete the pod to trigger the resize. The best way to proceed is to delete one pod at a time, starting from replicas and waiting for each pod to be back up. +### Expanding PVC volumes on AKS + +Currently, [Azure can resize the PVC's volume without restarting the pod only on specific regions](https://learn.microsoft.com/en-us/azure/aks/azure-disk-csi#resize-a-persistent-volume-without-downtime). +EDB Postgres for Kubernetes has overcome this limitation through the +`ENABLE_AZURE_PVC_UPDATES` environment variable in the +[operator configuration](operator_conf.md#available-options). +When set to `true`, EDB Postgres for Kubernetes triggers a rolling update of the +Postgres cluster. + +Alternatively, you can use the following workaround to manually resize the +volume in AKS. + +#### Workaround for volume expansion on AKS + +You can manually resize a PVC on AKS. As an example, suppose you have a cluster +with three replicas: + +``` +$ kubectl get pods +NAME READY STATUS RESTARTS AGE +cluster-example-1 1/1 Running 0 2m37s +cluster-example-2 1/1 Running 0 2m22s +cluster-example-3 1/1 Running 0 2m10s +``` + +An Azure disk can be expanded only while in "unattached" state, as described in the +[Kubernetes documentation](https://github.com/kubernetes-sigs/azuredisk-csi-driver/blob/master/docs/known-issues/sizegrow.md). +This means that, to resize a disk used by a PostgreSQL cluster, you need to +perform a manual rollout, first cordoning the node that hosts the pod using the +PVC bound to the disk. This prevents the operator from re-creating the pod and +immediately reattaching it to its PVC before the background disk resizing is +complete. + +First, edit the cluster definition, applying the new size. In this example, the +new size is `2Gi`. + +``` +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: cluster-example +spec: + instances: 3 + + storage: + storageClass: default + size: 2Gi +``` + +Assuming the `cluster-example-1` pod is the cluster's primary, you can proceed +with the replicas first. For example, start with cordoning the Kubernetes node +that hosts the `cluster-example-3` pod: + +``` +kubectl cordon +``` + +Then delete the `cluster-example-3` pod: + +``` +$ kubectl delete pod/cluster-example-3 +``` + +Run the following command: + +``` +kubectl get pvc -w -o=jsonpath='{.status.conditions[].message}' cluster-example-3 +``` + +Wait until you see the following output: + +``` +Waiting for user to (re-)start a Pod to finish file system resize of volume on node. +``` + +Then, you can uncordon the node: + +``` +kubectl uncordon +``` + +Wait for the pod to be re-created correctly and get in a "Running and Ready" state: + +``` +kubectl get pods -w cluster-example-3 +cluster-example-3 0/1 Init:0/1 0 12m +cluster-example-3 1/1 Running 0 12m +``` + +Verify the PVC expansion by running the following command, which returns `2Gi` +as configured: + +``` +kubectl get pvc cluster-example-3 -o=jsonpath='{.status.capacity.storage}' +``` + +You can repeat these steps for the remaining pods. + +!!!info Important + +Leave the resizing of the disk associated with the primary instance as the +last disk, after promoting through a switchover a new resized pod, using +`kubectl cnp promote`. For example, use `kubectl cnp promote cluster-example 3` +to promote `cluster-example-3` to primary. +!!! + ### Re-creating storage If the storage class doesn't support volume expansion, you can still regenerate @@ -319,6 +434,7 @@ $ kubectl delete pvc/cluster-example-3 pod/cluster-example-3 ``` !!!info Important + If you created a dedicated WAL volume, both PVCs must be deleted during this process. The same procedure applies if you want to regenerate the WAL volume PVC. You can do this by also disabling `resizeInUseVolumes` for the @@ -343,6 +459,72 @@ cluster-example-4-join-v2 0/1 Completed 0 17s cluster-example-4 1/1 Running 0 10s ``` +## Volume reduction + +Kubernetes does not provide an API to shrink a PVC, and {{name.ln}}' +validating webhook rejects any attempt to decrease `.spec.storage.size`, +`.spec.walStorage.size` or any tablespace storage size in `.spec.tablespaces`. +You can still reduce the storage of a cluster, but only by recreating +each instance with a smaller volume, as described below. + +!!!warning + +{{name.ln}} does not support automated volume shrinking, as it is a +delicate operation that can lead to data loss if performed incorrectly. For +the time being, it can only be achieved manually, through the supervised +procedure described below. +This procedure requires you to temporarily disable the validating webhook. +While validation is disabled, the operator accepts spec changes that would +normally be rejected, including unsafe or destructive ones. Proceed with +caution and at your own risk, and re-enable validation as soon as possible. + +Before you start, make sure the cluster's current data, WAL, and any tablespace +data comfortably fit within the new, smaller sizes. If they don't, the instances +recreated on smaller volumes can fail to rejoin or quickly run out of space. +!!! + +To reduce the size of the persistent volumes: + +1. Disable the validating webhook by setting the `k8s.enterprisedb.io/validation: disabled` + annotation on the `Cluster`, set `.spec.storage.size` (and, if present, + `.spec.walStorage.size` or tablespace storage size in `.spec.tablespaces`) + to the new, smaller value, and increase `.spec.instances` by 1 to provide a + spare instance during the rollout. + +2. Re-enable validation by removing the `k8s.enterprisedb.io/validation` annotation (or + setting it to `enabled`). The new, smaller size is now stored in the spec + and is applied to every instance the operator recreates from this point on. + Existing instances keep their current volumes; for each one, the operator + logs an informational `cannot decrease storage requirement` message until + that instance is recreated. This is expected and harmless. + +3. Destroy one standby that still has a volume of the old size. The operator + provisions a replacement instance — created with the next available name, + not the one you destroyed — on the new, smaller volume: + + ```sh + kubectl-cnp destroy CLUSTER INSTANCE + ``` + +4. Wait for the operator to create the replacement instance and for it to + become healthy. + +5. Repeat steps 3 and 4 for every remaining standby that still has an + old-size volume. + +6. Promote one of the newly created standbys so that the current primary — + which still has an old-size volume — is demoted to a standby: + + ```sh + kubectl-cnp promote CLUSTER INSTANCE + ``` + +7. Destroy the former primary (now a standby with an old-size volume) so the + operator provisions its replacement on the new, smaller volume, and wait + until all instances are healthy. + +8. Decrease `.spec.instances` back to its original value. + ## Static provisioning of persistent volumes {{name.ln}} was designed to work with dynamic volume provisioning. This @@ -356,6 +538,7 @@ their representation inside the Kubernetes cluster. This is also known as *pre-provisioning* of volumes. !!!info Important + We recommend that you avoid pre-provisioning volumes, as it has an effect on the high availability and self-healing capabilities of the operator. It breaks the fully declarative model on which {{name.ln}} was built. @@ -373,6 +556,7 @@ To use a pre-provisioned volume in {{name.ln}}: and enable {{name.ln}} to create the needed `PersistentVolumeClaim`. !!!warning + With static provisioning, it's your responsibility to ensure that Postgres pods can be correctly scheduled by Kubernetes where a pre-provisioned volume exists. (The scheduling configuration is based on the affinity rules of your diff --git a/product_docs/docs/postgres_for_kubernetes/1/tablespaces.mdx b/product_docs/docs/postgres_for_kubernetes/1/tablespaces.mdx index db2f448862..cc199f8403 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/tablespaces.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/tablespaces.mdx @@ -181,6 +181,7 @@ CREATE TABLE facts_202312 PARTITION OF facts ``` !!!info Important + This example assumes you're familiar with [PostgreSQL declarative partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html). !!! @@ -207,6 +208,7 @@ the `postgres` user, like in the following excerpt: ``` !!!info Important + If you change the ownership of a tablespace, make sure that you're using an existing role. Otherwise, the status of the cluster reports the issue and stops reconciling tablespaces until fixed. It's your responsibility @@ -254,6 +256,7 @@ spec: tablespace map) both on object stores and volume snapshots. !!!warning + By default, backups are taken from replica nodes. A backup taken immediately after creating tablespaces in a cluster can result in an incomplete view of the tablespaces from the replica and thus an incomplete @@ -262,6 +265,7 @@ reconciliation. !!! !!!warning + When you add or remove a tablespace in an existing cluster, recovery from WAL will fail until you take a new base backup. !!! diff --git a/product_docs/docs/postgres_for_kubernetes/1/tde.mdx b/product_docs/docs/postgres_for_kubernetes/1/tde.mdx index 583840b1d0..fecfc9cd5f 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/tde.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/tde.mdx @@ -4,6 +4,7 @@ originalFilePath: 'src/tde.md' --- !!!info Important + TDE is available *only* for operands that support it: EPAS and PG Extended, versions 15 and newer. !!! @@ -17,6 +18,7 @@ Server from version 15, and is supported by the {{name.ln}} operator. !!!info Important + Before you proceed, please take some time to familiarize with the [TDE feature in the EPAS documentation](/tde/latest/). !!! @@ -27,6 +29,7 @@ managed by the database without requiring any application changes or updated client drivers. !!!note + In the code samples shown below, the `epas` sub-section of `postgresql` in the YAML manifests is used to activate TDE. The `epas` section can be used to enable TDE for PG Extended images as well as for EPAS images. @@ -44,6 +47,7 @@ The basic approach is to store the passphrase in a Kubernetes secret. Such a passphrase will be used to encrypt the EPAS binary key. !!!note EPAS documentation + Please refer to [the EPAS documentation](/tde/latest/secure_key/) for details on the EPAS encryption key. !!! @@ -68,6 +72,7 @@ For example: You can find an example in [`cluster-example-tde.yaml`](../samples/cluster-example-tde.yaml). !!!note + This file also contains the definition of the secret to hold the encryption key. Look at the following section for an example on how to create a secret for this purpose. diff --git a/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx b/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx index 836febe699..909ce8f7c7 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx @@ -6,9 +6,10 @@ originalFilePath: 'src/troubleshooting.md' In this page, you can find some basic information on how to troubleshoot -{{name.ln}} in your Kubernetes cluster deployment. +EDB Postgres for Kubernetes in your Kubernetes cluster deployment. !!!tip Hint + As a Kubernetes administrator, you should have the [`kubectl` Cheat Sheet](https://kubernetes.io/docs/reference/kubectl/cheatsheet/) page bookmarked! @@ -78,6 +79,7 @@ In some emergency situations, you might need to take an emergency logical backup of the main `app` database. !!!info Important + The instructions you find below must be executed only in emergency situations and the temporary backup files kept under the data protection policies that are effective in your organization. The dump file is indeed stored @@ -95,6 +97,7 @@ kubectl exec cluster-example-1 -c postgres \ ``` !!!note + You can easily adapt the above command to backup your cluster, by providing the names of the objects you have used in your environment. !!! @@ -116,6 +119,7 @@ kubectl exec -i new-cluster-example-1 -c postgres \ ``` !!!info Important + The example in this section assumes that you have no other global objects (databases and roles) to dump and restore, as per our recommendation. In case you have multiple roles, make sure you have taken a backup using `pg_dumpall -g` @@ -149,6 +153,7 @@ for doing so: and more. !!!note + The following sections provide examples of how to retrieve logs for various resources when troubleshooting {{name.ln}}. !!! @@ -167,6 +172,7 @@ kubectl get pods -n postgresql-operator-system ``` !!!note + Under normal circumstances, you should have one pod where the operator is running, identified by a name starting with `postgresql-operator-controller-manager-`. In case you have set up your operator for high availability, you should have more entries. @@ -197,6 +203,7 @@ kubectl logs -n postgresql-operator-system \ ``` !!!tip + You can add `-f` flag to above command to follow logs in real time. !!! @@ -221,7 +228,7 @@ Cluster in healthy state Name: cluster-example Namespace: default System ID: 7044925089871458324 -PostgreSQL Image: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 +PostgreSQL Image: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 Primary instance: cluster-example-1 Instances: 3 Ready instances: 3 @@ -278,6 +285,7 @@ kubectl cnp status -n ``` !!!tip + You can print more information by adding the `--verbose` option. !!! @@ -290,10 +298,11 @@ kubectl describe cluster -n | grep "Image Name" Output: ```shell - Image Name: docker.enterprisedb.com/k8s/postgresql:18.3-standard-ubi9 + Image Name: docker.enterprisedb.com/k8s/postgresql:18.4-standard-ubi9 ``` !!!note + Also you can use `kubectl-cnp status -n ` to get the same information. !!! @@ -592,6 +601,7 @@ to always run the latest minor version of PostgreSQL). the `k8s.enterprisedb.io/coredumpFilter` annotation. !!!info + Please refer to ["Labels and annotations"](labels_annotations.md) for more details on the standard annotations that {{name.ln}} provides. !!! @@ -601,12 +611,14 @@ exclude shared memory segments from the dump, as this is the safest approach in most cases. !!!info + Please refer to ["Core dump filtering settings" section of "The `/proc` Filesystem" page of the Linux Kernel documentation](https://docs.kernel.org/filesystems/proc.html#proc-pid-coredump-filter-core-dump-filtering-settings). for more details on how to set the bitmask that controls the core dump filter. !!! !!!info Important + Beware that this setting only takes effect during Pod startup and that changing the annotation doesn't trigger an automated rollout of the instances. !!! @@ -663,6 +675,7 @@ it to `"false"`. The operator will roll out changes automatically to remove the pprof port and flag. !!!info Important + The pprof server only serves plain HTTP on port `6060`. !!! @@ -686,6 +699,7 @@ Changing this annotation updates the instance pod spec (adds port `6060` and the corresponding flag) and triggers a rolling update. !!!warning + The example below uses `kubectl port-forward` for local testing only. This is **not** the intended way to expose the feature in production. Treat pprof as a sensitive debugging interface and never expose it publicly. diff --git a/product_docs/docs/postgres_for_kubernetes/1/wal_archiving.mdx b/product_docs/docs/postgres_for_kubernetes/1/wal_archiving.mdx index b152a133d7..3cb222362a 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/wal_archiving.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/wal_archiving.mdx @@ -5,13 +5,26 @@ originalFilePath: 'src/wal_archiving.md' +WAL archiving is the process that feeds a [WAL archive](backup.md#wal-archive) +in EDB Postgres for Kubernetes. + +!!!info Important + +{{name.ln}} currently only supports WAL archives on object stores. Such +WAL archives serve for both object store backups and volume snapshot backups. +!!! + Write-Ahead Log (WAL) archiving in {{name.ln}} is the process of continuously shipping WAL files to a designated object store from the PostgreSQL primary. These archives are essential for enabling Point-In-Time Recovery (PITR) and are a foundational component for both object store and volume snapshot-based backup strategies. -## Plugin-Based Architecture +!!!info + +Please refer to [`BarmanObjectStoreConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration) +in the barman-cloud API for a full list of options. +!!! {{name.ln}} supports WAL archiving through a **plugin-based mechanism**, defined via the [`spec.pluginConfiguration`](pg4k.v1.md#clusterspec) @@ -28,7 +41,16 @@ archiving plugin maintained by the {{name.ln}} Community. For full documentation, configuration options, and best practices, see the [Barman Cloud Plugin documentation](https://cloudnative-pg.io/plugin-barman-cloud/docs/intro/). -## Deprecation Notice: Native Barman Cloud +!!!info Important + +By default, {{name.ln}} sets `archive_timeout` to `5min`, ensuring +that WAL files, even in case of low workloads, are closed and archived +at least every 5 minutes, providing a deterministic time-based value for +your Recovery Point Objective ([RPO](before_you_start.md#postgresql-terminology)). Even though you change the value +of the [`archive_timeout` setting in the PostgreSQL configuration](https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT), +our experience suggests that the default value set by the operator is +suitable for most use cases. +!!! {{name.ln}} still supports WAL archiving natively through the `.spec.backup.barmanObjectStore` field. While still functional, **this