diff --git a/product_docs/docs/postgres_for_kubernetes/1/applications.mdx b/product_docs/docs/postgres_for_kubernetes/1/applications.mdx index 84cf029a86c..32661da0a96 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/applications.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/applications.mdx @@ -3,6 +3,8 @@ title: 'Connecting from an application' originalFilePath: 'src/applications.md' --- + + Applications are supposed to work with the services created by EDB Postgres for Kubernetes in the same Kubernetes cluster. diff --git a/product_docs/docs/postgres_for_kubernetes/1/architecture.mdx b/product_docs/docs/postgres_for_kubernetes/1/architecture.mdx index 55a96d5237b..a901e6962d9 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/architecture.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/architecture.mdx @@ -3,6 +3,8 @@ title: 'Architecture' originalFilePath: 'src/architecture.md' --- + + !!! 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/), @@ -414,9 +416,10 @@ This is typically triggered by: declarative configuration, enabling you to automate these procedures as part of your Infrastructure as Code (IaC) process, including GitOps. -The designated primary in the above example is fed via WAL streaming -(`primary_conninfo`), with fallback option for file-based WAL shipping through -the `restore_command` and `barman-cloud-wal-restore`. +In the example above, the designated primary receives WAL updates via streaming +replication (`primary_conninfo`). As a fallback, it can retrieve WAL segments +from an object store using file-based WAL shipping—for instance, with the +Barman Cloud plugin through `restore_command` and `barman-cloud-wal-restore`. EDB Postgres for Kubernetes allows you to define topologies with multiple replica clusters. You can also define replica clusters with a lower number of replicas, and then diff --git a/product_docs/docs/postgres_for_kubernetes/1/backup.mdx b/product_docs/docs/postgres_for_kubernetes/1/backup.mdx index 063a44186e9..27a68c95cec 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/backup.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/backup.mdx @@ -3,6 +3,14 @@ title: 'Backup' originalFilePath: 'src/backup.md' --- + + +!!! Warning + With the deprecation of native Barman Cloud support in EDB Postgres for Kubernetes in + favor of the Barman Cloud Plugin, this page—and the backup and recovery + documentation—may undergo changes before the official release of version + 1.26.0. + 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 @@ -30,7 +38,9 @@ The WAL archive can only be stored on object stores at the moment. 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 + compressed: + - Using the Barman Cloud plugin + - Natively via `.spec.backup.barmanObjectStore` (*deprecated, to be removed in EDB Postgres for Kubernetes 1.28*) - on [Kubernetes Volume Snapshots](backup_volumesnapshot.md), if supported by the underlying storage class @@ -44,11 +54,6 @@ On the other hand, EDB Postgres for Kubernetes supports two ways to store physic 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, EDB Postgres for Kubernetes 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 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 29420b58970..5a65921fe66 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/backup_barmanobjectstore.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/backup_barmanobjectstore.mdx @@ -3,6 +3,14 @@ title: 'Backup on object stores' originalFilePath: 'src/backup_barmanobjectstore.md' --- + + +!!! Warning + With the deprecation of native Barman Cloud support in EDB Postgres for Kubernetes in + favor of the Barman Cloud Plugin, this page—and the backup and recovery + documentation—may undergo changes before the official release of version + 1.26.0. + EDB Postgres for Kubernetes 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) @@ -96,7 +104,10 @@ algorithms via `barman-cloud-backup` (for backups) and - bzip2 - gzip +- lz4 - snappy +- xz +- zstd The compression settings for backups and WALs are independent. See the [DataBackupConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration) and diff --git a/product_docs/docs/postgres_for_kubernetes/1/backup_recovery.mdx b/product_docs/docs/postgres_for_kubernetes/1/backup_recovery.mdx index 1ee141ade78..b90f8c8a302 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/backup_recovery.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/backup_recovery.mdx @@ -3,4 +3,6 @@ title: 'Backup and Recovery' originalFilePath: 'src/backup_recovery.md' --- + + [Backup](backup.md) and [recovery](recovery.md) are in two separate sections. 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 3a085374575..e21ddf3909d 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/backup_volumesnapshot.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/backup_volumesnapshot.mdx @@ -3,6 +3,8 @@ title: 'Backup on volume snapshots' originalFilePath: 'src/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 @@ -60,6 +62,8 @@ volumes of a given storage class, and managed as `VolumeSnapshot` and ## How to configure Volume Snapshot backups + + EDB Postgres for Kubernetes allows you to configure a given Postgres cluster for Volume Snapshot backups through the `backup.volumeSnapshot` stanza. @@ -245,7 +249,97 @@ referenced in the `.spec.backup.volumeSnapshot.className` option. Please refer to the [Kubernetes documentation on Volume Snapshot Classes](https://kubernetes.io/docs/concepts/storage/volume-snapshot-classes/) for details on this standard behavior. -## Example +## Backup Volume Snapshot Deadlines + +EDB Postgres for Kubernetes supports backups using the volume snapshot method. In some +environments, volume snapshots may encounter temporary issues that can be +retried. + +The `backup.k8s.enterprisedb.io/volumeSnapshotDeadline` annotation defines how long +EDB Postgres for Kubernetes should continue retrying recoverable errors before marking the +backup as failed. + +You can add the `backup.k8s.enterprisedb.io/volumeSnapshotDeadline` annotation to both +`Backup` and `ScheduledBackup` resources. For `ScheduledBackup` resources, this +annotation is automatically inherited by any `Backup` resources created from +the schedule. + +If not specified, the default retry deadline is **10 minutes**. + +### Error Handling + +When a retryable error occurs during a volume snapshot operation: + +1. EDB Postgres for Kubernetes records the time of the first error. +2. The system retries the operation every **10 seconds**. +3. If the error persists beyond the specified deadline (or the default 10 + minutes), the backup is marked as **failed**. + +### Retryable Errors + +EDB Postgres for Kubernetes treats the following types of errors as retryable: + +- **Server timeout errors** (HTTP 408, 429, 500, 502, 503, 504) +- **Conflicts** (optimistic locking errors) +- **Internal errors** +- **Context deadline exceeded errors** +- **Timeout errors from the CSI snapshot controller** + +### Examples + +You can add the annotation to a `ScheduledBackup` resource as follows: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: ScheduledBackup +metadata: + name: daily-backup-schedule + annotations: + backup.k8s.enterprisedb.io/volumeSnapshotDeadline: "20" +spec: + schedule: "0 0 * * *" + backupOwnerReference: self + method: volumeSnapshot + # other configuration... +``` + +When you define a `ScheduledBackup` with the annotation, any `Backup` resources +created from this schedule automatically inherit the specified timeout value. + +In the following example, all backups created from the schedule will have a +30-minute timeout for retrying recoverable snapshot errors. + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: ScheduledBackup +metadata: + name: weekly-backup + annotations: + backup.k8s.enterprisedb.io/volumeSnapshotDeadline: "30" +spec: + schedule: "0 0 * * 0" # Weekly backup on Sunday + method: volumeSnapshot + cluster: + name: my-postgresql-cluster +``` + +Alternatively, you can add the annotation directly to a `Backup` Resource: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Backup +metadata: + name: my-backup + annotations: + backup.k8s.enterprisedb.io/volumeSnapshotDeadline: "15" +spec: + method: volumeSnapshot + # other backup configuration... +``` + +## Example of Volume Snapshot Backup + + The following example shows how to configure volume snapshot base backups on an EKS cluster on AWS using the `ebs-sc` storage class and the `csi-aws-vsc` diff --git a/product_docs/docs/postgres_for_kubernetes/1/before_you_start.mdx b/product_docs/docs/postgres_for_kubernetes/1/before_you_start.mdx index b24598570b2..c651d02845a 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/before_you_start.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/before_you_start.mdx @@ -3,6 +3,8 @@ title: 'Before You Start' originalFilePath: 'src/before_you_start.md' --- + + Before we get started, it is essential to go over some terminology that is specific to Kubernetes and PostgreSQL. diff --git a/product_docs/docs/postgres_for_kubernetes/1/benchmarking.mdx b/product_docs/docs/postgres_for_kubernetes/1/benchmarking.mdx index ceb73331d5e..ea29f56f8d1 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/benchmarking.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/benchmarking.mdx @@ -3,6 +3,8 @@ title: 'Benchmarking' originalFilePath: 'src/benchmarking.md' --- + + The CNP kubectl plugin provides an easy way for benchmarking a PostgreSQL deployment in Kubernetes using EDB Postgres for Kubernetes. Benchmarking is focused on two aspects: @@ -177,7 +179,7 @@ It will: 3. Create a fio deployment composed by a single Pod, which will run fio on the PVC, create graphs after completing the benchmark and start serving the generated files with a webserver. We use the - [`fio-tools`](https://github.com/wallnerryan/fio-tools`) image for that. + [`fio-tools`](https://github.com/wallnerryan/fio-tools) image for that. The Pod created by the deployment will be ready when it starts serving the results. You can forward the port of the pod created by the deployment diff --git a/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx b/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx index 3db31d60291..251184a57ed 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx @@ -3,6 +3,8 @@ title: 'Bootstrap' 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 diff --git a/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx b/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx index e19687881f4..bceff3185dd 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx @@ -3,6 +3,8 @@ title: 'Certificates' originalFilePath: 'src/certificates.md' --- + + EDB Postgres for Kubernetes was designed to natively support TLS certificates. To set up a cluster, the operator requires: @@ -53,6 +55,11 @@ expiration (within a 90-day validity period). certificates not controlled by EDB Postgres for Kubernetes must be re-issued following the renewal process. +When generating certificates, the operator assumes that the Kubernetes +cluster's DNS zone is set to `cluster.local` by default. This behavior can be +customized by setting the `KUBERNETES_CLUSTER_DOMAIN` environment variable. A +convenient alternative is to use the [operator's configuration capability](operator_conf.md). + ### Server certificates #### Server CA secret diff --git a/product_docs/docs/postgres_for_kubernetes/1/cluster_conf.mdx b/product_docs/docs/postgres_for_kubernetes/1/cluster_conf.mdx index 8b550eb893d..6c104e5ecbf 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/cluster_conf.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/cluster_conf.mdx @@ -3,6 +3,8 @@ title: 'Instance pod configuration' originalFilePath: 'src/cluster_conf.md' --- + + ## Projected volumes EDB Postgres for Kubernetes supports mounting custom files inside the Postgres pods through 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 c14f5b52717..dd91458902e 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/connection_pooling.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/connection_pooling.mdx @@ -3,6 +3,8 @@ title: 'Connection pooling' originalFilePath: 'src/connection_pooling.md' --- + + EDB Postgres for Kubernetes provides native support for connection pooling with [PgBouncer](https://www.pgbouncer.org/), one of the most popular open source connection poolers for PostgreSQL, through the `Pooler` custom resource definition (CRD). 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 43442a066c0..ec382a11627 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/container_images.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/container_images.mdx @@ -3,43 +3,42 @@ title: 'Container Image Requirements' originalFilePath: 'src/container_images.md' --- -The EDB Postgres for Kubernetes operator for Kubernetes is designed to -work with any compatible container image of PostgreSQL that complies -with the following requirements: -- PostgreSQL executables that must be in the path: + +The EDB Postgres for Kubernetes operator for Kubernetes is designed to work with any +compatible PostgreSQL container image that meets the following requirements: + +- PostgreSQL executables must be available in the system path: - `initdb` - `postgres` - `pg_ctl` - `pg_controldata` - `pg_basebackup` -- Barman Cloud executables that must be in the path: - - `barman-cloud-backup` - - `barman-cloud-backup-delete` - - `barman-cloud-backup-list` - - `barman-cloud-check-wal-archive` - - `barman-cloud-restore` - - `barman-cloud-wal-archive` - - `barman-cloud-wal-restore` -- PGAudit extension installed (optional - only if PGAudit is required - in the deployed clusters) -- Appropriate locale settings -- `du` (optional, for `kubectl cnp status`) +- 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`) !!! Important - Only [PostgreSQL versions supported by the PGDG](https://postgresql.org/) are allowed. + Only [PostgreSQL versions officially supported by PGDG](https://postgresql.org/) are allowed. + +!!! Info + Barman Cloud executables are no longer required in EDB Postgres for Kubernetes. The + recommended approach is to use the dedicated [Barman Cloud Plugin](https://github.com/cloudnative-pg/plugin-barman-cloud). -No entry point and/or command is required in the image definition, as -EDB Postgres for Kubernetes overrides it with its instance manager. +No entry point or command is required in the image definition. EDB Postgres for Kubernetes +automatically overrides it with its instance manager. !!! Warning - Application Container Images will be used by EDB Postgres for Kubernetes - in a **Primary with multiple/optional Hot Standby Servers Architecture** - only. + EDB Postgres for Kubernetes only supports **Primary with multiple/optional Hot Standby + Servers architecture** for PostgreSQL application container images. -EDB provides and supports +EDB provides and maintains [public PostgreSQL container images](https://github.com/enterprisedb/docker-postgres) -for EDB Postgres for Kubernetes, and publishes them on +that are fully compatible with EDB Postgres for Kubernetes. These images are published on [quay.io](https://quay.io/enterprisedb/postgresql). ## Image Tag Requirements diff --git a/product_docs/docs/postgres_for_kubernetes/1/controller.mdx b/product_docs/docs/postgres_for_kubernetes/1/controller.mdx index f8b7ae9016e..4a4b65d6a39 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/controller.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/controller.mdx @@ -3,6 +3,8 @@ title: 'Custom Pod Controller' originalFilePath: 'src/controller.md' --- + + Kubernetes uses the [Controller pattern](https://kubernetes.io/docs/concepts/architecture/controller/) to align the current cluster state with the desired one. 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 d203baffb82..ad102c3ec00 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/database_import.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/database_import.mdx @@ -3,6 +3,8 @@ title: 'Importing Postgres databases' originalFilePath: 'src/database_import.md' --- + + This section describes how to import one or more existing PostgreSQL databases inside a brand new EDB Postgres for Kubernetes cluster. 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 fc2ebe64bf8..afb3933a7d4 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 @@ -3,6 +3,8 @@ title: 'PostgreSQL Database Management' originalFilePath: 'src/declarative_database_management.md' --- + + EDB Postgres for Kubernetes simplifies PostgreSQL database provisioning by automatically creating an application database named `app` by default. This default behavior is explained in the ["Bootstrap an Empty Cluster"](bootstrap.md#bootstrap-an-empty-cluster-initdb) @@ -21,10 +23,10 @@ automated, and consistent approach to managing PostgreSQL databases. ### Scope of Management !!! Important - EDB Postgres for Kubernetes 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. + EDB Postgres for Kubernetes 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. ### Declarative `Database` Manifest @@ -41,6 +43,9 @@ spec: owner: app cluster: name: cluster-example + extensions: + - name: bloom + ensure: present ``` When applied, this manifest creates a `Database` object called @@ -160,6 +165,101 @@ spec: This manifest ensures that the `database-to-drop` database is removed from the `cluster-example` cluster. +## Managing Extensions in a Database + +!!! Info + While extensions are database-scoped rather than global objects, + EDB Postgres for Kubernetes provides a declarative interface for managing them. This approach + is necessary because installing certain extensions may require superuser + privileges, which EDB Postgres for Kubernetes recommends disabling by default. By leveraging + this API, users can efficiently manage extensions in a scalable and controlled + manner without requiring elevated privileges. + +EDB Postgres for Kubernetes simplifies and automates the management of PostgreSQL extensions within the +target database. + +To enable this feature, define the `spec.extensions` field +with a list of extension specifications, as shown in the following example: + +```yaml +# ... +spec: + extensions: + - name: bloom + ensure: present +# ... +``` + +Each extension entry supports the following properties: + +- `name` *(mandatory)*: The name of the extension. +- `ensure`: Specifies whether the extension should be present or absent in the + database: + - `present`: Ensures that the extension is installed (default). + - `absent`: Ensures that the extension is removed. +- `version`: The specific version of the extension to install or + upgrade to. +- `schema`: The schema in which the extension should be installed. + +!!! Info + EDB Postgres for Kubernetes manages extensions using the following PostgreSQL’s SQL commands: + [`CREATE EXTENSION`](https://www.postgresql.org/docs/current/sql-createextension.html), + [`DROP EXTENSION`](https://www.postgresql.org/docs/current/sql-dropextension.html), + [`ALTER EXTENSION`](https://www.postgresql.org/docs/current/sql-alterextension.html) + (limited to `UPDATE TO` and `SET SCHEMA`). + +The operator reconciles only the extensions explicitly listed in +`spec.extensions`. Any existing extensions not specified in this list remain +unchanged. + +!!! Warning + Before the introduction of declarative extension management, EDB Postgres for Kubernetes + did not offer a straightforward way to create extensions through configuration. + To address this, the ["managed extensions"](postgresql_conf.md#managed-extensions) + feature was introduced, enabling the automated and transparent management + of key extensions like `pg_stat_statements`. Currently, it is your + responsibility to ensure there are no conflicts between extension support in + the `Database` CRD and the managed extensions feature. + +## Managing Schemas in a Database + +!!! Info + Schema management in PostgreSQL is an exception to EDB Postgres for Kubernetes' primary + focus on managing global objects. Since schemas exist within a database, they + are typically managed as part of the application development process. However, + EDB Postgres for Kubernetes provides a declarative interface for schema management, primarily + to complete the support of extensions deployment within schemas. + +EDB Postgres for Kubernetes simplifies and automates the management of PostgreSQL schemas within the +target database. + +To enable this feature, define the `spec.schemas` field +with a list of schema specifications, as shown in the following example: + +```yaml +# ... +spec: + schemas: + - name: app + owner: app +# ... +``` + +Each schema entry supports the following properties: + +- `name` *(mandatory)*: The name of the schema. +- `owner`: The owner of the schema. +- `ensure`: Specifies whether the schema should be present or absent in the + database: + - `present`: Ensures that the schema is installed (default). + - `absent`: Ensures that the schema is removed. + +!!! Info + EDB Postgres for Kubernetes manages schemas using the following PostgreSQL’s SQL commands: + [`CREATE SCHEMA`](https://www.postgresql.org/docs/current/sql-createschema.html), + [`DROP SCHEMA`](https://www.postgresql.org/docs/current/sql-dropschema.html), + [`ALTER SCHEMA`](https://www.postgresql.org/docs/current/sql-alterschema.html). + ## Limitations and Caveats ### Renaming a database 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 e23788fb088..efed8816c10 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/declarative_hibernation.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/declarative_hibernation.mdx @@ -3,6 +3,8 @@ title: 'Declarative hibernation' originalFilePath: 'src/declarative_hibernation.md' --- + + EDB Postgres for Kubernetes is designed to keep PostgreSQL clusters up, running and available anytime. @@ -15,14 +17,6 @@ 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: 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 7144a67eefa..e8a35fa031e 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 @@ -3,6 +3,8 @@ title: 'PostgreSQL Role Management' originalFilePath: 'src/declarative_role_management.md' --- + + From its inception, EDB Postgres for Kubernetes has managed the creation of specific roles required in PostgreSQL instances: diff --git a/product_docs/docs/postgres_for_kubernetes/1/default-monitoring.yaml b/product_docs/docs/postgres_for_kubernetes/1/default-monitoring.yaml index 107072299f2..1a22775737c 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/default-monitoring.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/default-monitoring.yaml @@ -454,3 +454,35 @@ data: - setting: usage: "GAUGE" description: "Setting value" + + pg_extensions: + query: | + SELECT + current_database() as datname, + name as extname, + default_version, + installed_version, + CASE + WHEN default_version = installed_version THEN 0 + ELSE 1 + END AS update_available + FROM pg_catalog.pg_available_extensions + WHERE installed_version IS NOT NULL + metrics: + - datname: + usage: "LABEL" + description: "Name of the database" + - extname: + usage: "LABEL" + description: "Extension name" + - default_version: + usage: "LABEL" + description: "Default version" + - installed_version: + usage: "LABEL" + description: "Installed version" + - update_available: + usage: "GAUGE" + description: "An update is available" + target_databases: + - '*' diff --git a/product_docs/docs/postgres_for_kubernetes/1/failover.mdx b/product_docs/docs/postgres_for_kubernetes/1/failover.mdx index 73f92b0bffc..bb5fa67f5d6 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/failover.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/failover.mdx @@ -3,6 +3,8 @@ title: 'Automated failover' originalFilePath: 'src/failover.md' --- + + In the case of unexpected errors on the primary for longer than the `.spec.failoverDelay` (by default `0` seconds), the cluster will go into **failover mode**. This may happen, for example, when: 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 b8186905157..35010038306 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/failure_modes.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/failure_modes.mdx @@ -3,6 +3,8 @@ title: 'Failure Modes' originalFilePath: 'src/failure_modes.md' --- + + !!! Note In previous versions of EDB Postgres for Kubernetes, this page included specific failure scenarios. Since these largely follow standard Kubernetes behavior, we have diff --git a/product_docs/docs/postgres_for_kubernetes/1/faq.mdx b/product_docs/docs/postgres_for_kubernetes/1/faq.mdx index ee91c65d1c4..f79a2b373c5 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/faq.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/faq.mdx @@ -3,6 +3,8 @@ title: 'Frequently Asked Questions (FAQ)' originalFilePath: 'src/faq.md' --- + + ## Running PostgreSQL in Kubernetes **Everyone knows that stateful workloads like PostgreSQL cannot run in diff --git a/product_docs/docs/postgres_for_kubernetes/1/fencing.mdx b/product_docs/docs/postgres_for_kubernetes/1/fencing.mdx index c35e05abb82..0ba6a957961 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/fencing.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/fencing.mdx @@ -3,6 +3,8 @@ title: 'Fencing' originalFilePath: 'src/fencing.md' --- + + Fencing in EDB Postgres for Kubernetes is the ultimate process of protecting the data in one, more, or even all instances of a PostgreSQL cluster when they appear to be malfunctioning. When an instance is fenced, the PostgreSQL server 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 8b11d692b53..ddde69cdf84 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/image_catalog.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/image_catalog.mdx @@ -3,6 +3,8 @@ title: 'Image Catalog' originalFilePath: 'src/image_catalog.md' --- + + `ImageCatalog` and `ClusterImageCatalog` are essential resources that empower you to define images for creating a `Cluster`. 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 eafb229b16a..c7c6bafbef8 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' --- + + !!! Seealso "OpenShift" For instructions on how to install Cloud Native PostgreSQL on Red Hat OpenShift Container Platform, please refer to the ["OpenShift"](openshift.md) @@ -79,20 +81,21 @@ through a YAML manifest applied via `kubectl`. There are two different manifests available depending on your subscription plan: -- Standard: The [latest standard operator manifest](https://get.enterprisedb.io/pg4k/pg4k-standard-1.25.1.yaml). -- Enterprise: The [latest enterprise operator manifest](https://get.enterprisedb.io/pg4k/pg4k-enterprise-1.25.1.yaml). +- Standard: The [latest standard operator manifest](https://get.enterprisedb.io/pg4k/pg4k-standard-1.26.0-rc1.yaml). +- Enterprise: The [latest enterprise operator manifest](https://get.enterprisedb.io/pg4k/pg4k-enterprise-1.26.0-rc1.yaml). 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-$EDB_SUBSCRIPTION_PLAN-1.25.1.yaml + https://get.enterprisedb.io/pg4k/pg4k-$EDB_SUBSCRIPTION_PLAN-1.26.0-rc1.yaml ``` You can verify that with: ```sh -kubectl get deployment -n postgresql-operator-system postgresql-operator-controller-manager +kubectl rollout status deployment \ + -n postgresql-operator-system postgresql-operator-controller-manager ``` ### Using the `cnp` plugin for `kubectl` @@ -280,12 +283,9 @@ 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.25 from a previous minor version -!!! Important - We strongly recommend that all EDB Postgres for Kubernetes 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). + +### Upgrading to 1.25 from a previous minor version !!! Warning Every time you are upgrading to a higher minor release, make sure you 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 b529f086de6..6cb99ed7bd0 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/instance_manager.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/instance_manager.mdx @@ -3,6 +3,8 @@ title: 'Postgres instance manager' originalFilePath: 'src/instance_manager.md' --- + + EDB Postgres for Kubernetes does not rely on an external tool for failover management. It simply relies on the Kubernetes API server and a native key component called: the **Postgres instance manager**. @@ -18,23 +20,23 @@ main container, which in turn runs the PostgreSQL instance. During the lifetime of the Pod, the instance manager acts as a backend to handle the [startup, liveness and readiness probes](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes). -## Startup, Liveness, and Readiness Probes +## Startup Probe -EDB Postgres for Kubernetes leverages [PostgreSQL's `pg_isready`](https://www.postgresql.org/docs/current/app-pg-isready.html) -to implement Kubernetes startup, liveness, and readiness probes. +The startup probe ensures that a PostgreSQL instance, whether a primary or +standby, has fully started. -### Startup Probe +!!! Info + By default, the startup probe uses + [`pg_isready`](https://www.postgresql.org/docs/current/app-pg-isready.html). + However, the behavior can be customized by specifying a different startup + strategy. -The startup probe ensures that a PostgreSQL instance, whether a primary or -standby, has fully started according to `pg_isready`. While the startup probe is running, the liveness and readiness probes remain disabled. Following Kubernetes standards, if the startup probe fails, the kubelet will terminate the container, which will then be restarted. -The startup probe provided by EDB Postgres for Kubernetes is configurable via the -parameter `.spec.startDelay`, which specifies the maximum time, in seconds, -allowed for the startup probe to succeed. At a minimum, the probe requires -`pg_isready` to return `0` or `1`. +The `.spec.startDelay` parameter specifies the maximum time, in seconds, +allowed for the startup probe to succeed. By default, the `startDelay` is set to `3600` seconds. It is recommended to adjust this setting based on the time PostgreSQL needs to fully initialize in @@ -66,7 +68,7 @@ section of your configuration. !!! Info For more details on probe configuration, refer to the - [probe API documentation](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-Probe). + [probe API documentation](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-ProbeWithStrategy). If you manually specify `.spec.probes.startup.failureThreshold`, it will override the default behavior and disable the automatic use of `startDelay`. @@ -84,16 +86,63 @@ spec: failureThreshold: 10 ``` -### Liveness Probe +### Startup Probe Strategy + +In certain scenarios, you may need to customize the startup strategy for your +PostgreSQL cluster. For example, you might delay marking a replica as started +until it begins streaming from the primary or define a replication lag +threshold that must be met before considering the replica ready. + +To accommodate these requirements, EDB Postgres for Kubernetes extends the +`.spec.probes.startup` stanza with two optional parameters: + +- `type`: specifies the criteria for considering the probe successful. Accepted + values, in increasing order of complexity/depth, include: + + - `pg_isready`: marks the probe as successful when the `pg_isready` command + exits with `0`. This is the default for primary instances and replicas. + - `query`: marks the probe as successful when a basic query is executed on + the `postgres` database locally. + - `streaming`: marks the probe as successful when the replica begins + streaming from its source and meets the specified lag requirements (details + below). + +- `maximumLag`: defines the maximum acceptable replication lag, measured in bytes + (expressed as Kubernetes quantities). This parameter is only applicable when + `type` is set to `streaming`. If `maximumLag` is not specified, the replica is + considered successfully started as soon as it begins streaming. + +!!! Important + The `.spec.probes.startup.maximumLag` option is validated and enforced only + during the startup phase of the pod, meaning it applies exclusively when the + replica is starting. + +!!! Warning + Incorrect configuration of the `maximumLag` option can cause continuous + failures of the startup probe, leading to repeated replica restarts. Ensure + you understand how this option works and configure appropriate values for + `failureThreshold` and `periodSeconds` to give the replica enough time to + catch up with its source. + +The following example requires a replica to have a maximum lag of 16Mi from the +source to be considered started: + +```yaml +# +probes: + startup: + type: streaming + maximumLag: 16Mi +``` + +## Liveness Probe The liveness probe begins after the startup probe successfully completes. Its -primary role is to ensure the PostgreSQL instance—whether primary or standby—is -operating correctly. This is achieved using the `pg_isready` utility. Both exit -codes `0` (indicating the server is accepting connections) and `1` (indicating -the server is rejecting connections, such as during startup or a smart -shutdown) are treated as valid outcomes. -Following Kubernetes standards, if the liveness probe fails, the -kubelet will terminate the container, which will then be restarted. +primary role is to ensure the PostgreSQL instance manager is operating +correctly. + +Following Kubernetes standards, if the liveness probe fails, the kubelet will +terminate the container, which will then be restarted. The amount of time before a Pod is classified as not alive is configurable via the `.spec.livenessProbeTimeout` parameter. @@ -143,14 +192,21 @@ spec: failureThreshold: 10 ``` -### Readiness Probe +## Readiness Probe + +The readiness probe starts once the startup probe has successfully completed. +Its primary purpose is to check whether the PostgreSQL instance is ready to +accept traffic and serve requests at any point during the pod's lifecycle. + +!!! Info + By default, the readiness probe uses + [`pg_isready`](https://www.postgresql.org/docs/current/app-pg-isready.html). + However, the behavior can be customized by specifying a different readiness + strategy. -The readiness probe begins once the startup probe has successfully completed. -Its purpose is to check whether the PostgreSQL instance is ready to accept -traffic and serve requests. -For streaming replicas, it also requires that they have connected to the source -at least once. Following Kubernetes standards, if the readiness probe fails, -the pod will be marked unready and will not receive traffic from any services. +Following Kubernetes standards, if the readiness probe fails, the pod will be +marked unready and will not receive traffic from any services. An unready pod +is also ineligible for promotion during automated failover scenarios. EDB Postgres for Kubernetes uses the following default configuration for the readiness probe: @@ -181,7 +237,57 @@ spec: !!! Info For more information on configuring probes, see the - [probe API](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-Probe). + [probe API](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-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, EDB Postgres for Kubernetes 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. + +!!! 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. +``` +!!! + +``` +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. +``` + +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 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 63733dfd2fd..6ddb6efbc3a 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/kubernetes_upgrade.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/kubernetes_upgrade.mdx @@ -3,6 +3,8 @@ title: 'Kubernetes Upgrade and Maintenance' originalFilePath: 'src/kubernetes_upgrade.md' --- + + Maintaining an up-to-date Kubernetes cluster is crucial for ensuring optimal performance and security, particularly for self-managed clusters, especially those running on bare metal infrastructure. Regular updates help address 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 10155eb2d82..9e2e7e7796b 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx @@ -3,6 +3,8 @@ title: 'Labels and annotations' originalFilePath: 'src/labels_annotations.md' --- + + Resources in Kubernetes are organized in a flat structure, with no hierarchical information or relationship between them. However, such resources and objects can be linked together and put in relationship through *labels* and @@ -31,40 +33,45 @@ they're inherited by all resources created by it (including pods). ## Predefined labels -These predefined labels are managed by EDB Postgres for Kubernetes. +EDB Postgres for Kubernetes manages the following predefined labels: `k8s.enterprisedb.io/backupDate` -: The date of the backup in ISO 8601 format (`YYYYMMDD`) +: The date of the backup in ISO 8601 format (`YYYYMMDD`). + This label is available only on `VolumeSnapshot` resources. `k8s.enterprisedb.io/backupName` -: Backup identifier, available only on `Backup` and `VolumeSnapshot` - resources +: Backup identifier. + This label is available only on `VolumeSnapshot` resources. `k8s.enterprisedb.io/backupMonth` -: The year/month when a backup was taken +: The year/month when a backup was taken. + This label is available only on `VolumeSnapshot` resources. `k8s.enterprisedb.io/backupTimeline` -: The timeline of the instance when a backup was taken +: The timeline of the instance when a backup was taken. + This label is available only on `VolumeSnapshot` resources. `k8s.enterprisedb.io/backupYear` -: The year a backup was taken +: The year a backup was taken. + This label is available only on `VolumeSnapshot` resources. `k8s.enterprisedb.io/cluster` -: Name of the cluster +: Name of the cluster. `k8s.enterprisedb.io/immediateBackup` : Applied to a `Backup` resource if the backup is the first one created from - a `ScheduledBackup` object having `immediate` set to `true` + a `ScheduledBackup` object having `immediate` set to `true`. `k8s.enterprisedb.io/instanceName` : Name of the PostgreSQL instance (replaces the old and - deprecated `postgresql` label) + deprecated `postgresql` label). `k8s.enterprisedb.io/jobRole` : Role of the job (that is, `import`, `initdb`, `join`, ...) `k8s.enterprisedb.io/onlineBackup` -: Whether the backup is online (hot) or taken when Postgres is down (cold) +: Whether the backup is online (hot) or taken when Postgres is down (cold). + This label is available only on `VolumeSnapshot` resources. `postgresql` : deprecated, Name of the PostgreSQL instance. Use `k8s.enterprisedb.io/instanceName` @@ -72,13 +79,13 @@ instead `k8s.enterprisedb.io/podRole` : Distinguishes pods dedicated to pooler deployment from those used for - database instances + database instances. `k8s.enterprisedb.io/poolerName` -: Name of the PgBouncer pooler +: Name of the PgBouncer pooler. `k8s.enterprisedb.io/pvcRole` -: Purpose of the PVC, such as `PG_DATA` or `PG_WAL` +: Purpose of the PVC, such as `PG_DATA` or `PG_WAL`. `k8s.enterprisedb.io/reload` : Available on `ConfigMap` and `Secret` resources. When set to `true`, @@ -96,14 +103,14 @@ instead `k8s.enterprisedb.io/scheduled-backup` : When available, name of the `ScheduledBackup` resource that created a given - `Backup` object + `Backup` object. `k8s.enterprisedb.io/instanceRole` : Whether the instance running in a pod is a `primary` or a `replica`. ## Predefined annotations -These predefined annotations are managed by EDB Postgres for Kubernetes. +EDB Postgres for Kubernetes manages the following predefined annotations: `container.apparmor.security.beta.kubernetes.io/*` : Name of the AppArmor profile to apply to the named container. @@ -112,15 +119,18 @@ These predefined annotations are managed by EDB Postgres for Kubernetes. `k8s.enterprisedb.io/backupEndTime` : The time a backup ended. + This annotation is available only on `VolumeSnapshot` resources. `k8s.enterprisedb.io/backupEndWAL` : The WAL at the conclusion of a backup. + This annotation is available only on `VolumeSnapshot` resources. `k8s.enterprisedb.io/backupStartTime` : The time a backup started. `k8s.enterprisedb.io/backupStartWAL` : The WAL at the start of a backup. + This annotation is available only on `VolumeSnapshot` resources. `k8s.enterprisedb.io/coredumpFilter` : Filter to control the coredump of Postgres processes, expressed with a @@ -166,6 +176,21 @@ These predefined annotations are managed by EDB Postgres for Kubernetes. `k8s.enterprisedb.io/podEnvHash` : Deprecated, as the `k8s.enterprisedb.io/podSpec` annotation now also contains the pod environment. +`k8s.enterprisedb.io/podPatch` +: Annotation can be applied on a `Cluster` resource. + +``` +When set to JSON-patch formatted patch, the patch will be applied on the instance Pods. + +**⚠️ WARNING:** This feature may introduce discrepancies between the +operator’s expectations and Kubernetes behavior. Use with caution and only as a +last resort. + +**IMPORTANT**: adding or changing this annotation won't trigger a rolling deployment +of the generated Pods. The latter can be triggered manually by the user with +`kubectl cnp restart`. +``` + `k8s.enterprisedb.io/podSpec` : Snapshot of the `spec` of the pod generated by the operator. This annotation replaces the old, deprecated `k8s.enterprisedb.io/podEnvHash` annotation. @@ -214,6 +239,20 @@ to the deployment specification, except for changes to `spec.instances`. `k8s.enterprisedb.io/snapshotEndTime` : The time a snapshot was marked as ready to use. +`k8s.enterprisedb.io/validation` +: When set to `disabled` on a EDB Postgres for Kubernetes-managed custom resource, the + validation webhook allows all changes without restriction. + +``` +**⚠️ WARNING:** Disabling validation may permit unsafe or destructive +operations. Use this setting with caution and at your own risk. +``` + +`k8s.enterprisedb.io/volumeSnapshotDeadline` +: Applied to `Backup` and `ScheduledBackup` resources, allows you to control + how long the operator should retry recoverable errors before considering the + volume snapshot backup failed. In minutes, defaulting to 10. + `kubectl.kubernetes.io/restartedAt` : When available, the time of last requested restart of a Postgres cluster. diff --git a/product_docs/docs/postgres_for_kubernetes/1/logging.mdx b/product_docs/docs/postgres_for_kubernetes/1/logging.mdx index 6a2cdd3a3f1..3e53504c920 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/logging.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/logging.mdx @@ -3,6 +3,8 @@ title: 'Logging' originalFilePath: 'src/logging.md' --- + + EDB Postgres for Kubernetes outputs logs in JSON format directly to standard output, including PostgreSQL logs, without persisting them to storage for security reasons. This design facilitates seamless integration with most Kubernetes-compatible log 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 14ce50caae0..da6678647e8 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx @@ -3,6 +3,8 @@ title: 'Logical Replication' originalFilePath: 'src/logical_replication.md' --- + + PostgreSQL extends its replication capabilities beyond physical replication, which operates at the level of exact block addresses and byte-by-byte copying, by offering [logical replication](https://www.postgresql.org/docs/current/logical-replication.html). diff --git a/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx b/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx index 429e33f743d..2bb89d673ae 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx @@ -3,6 +3,8 @@ title: 'Monitoring' originalFilePath: 'src/monitoring.md' --- + + !!! Important Installing Prometheus and Grafana is beyond the scope of this project. We assume they are correctly installed in your system. However, for diff --git a/product_docs/docs/postgres_for_kubernetes/1/networking.mdx b/product_docs/docs/postgres_for_kubernetes/1/networking.mdx index 0df3fb93072..cd3d58cdb79 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/networking.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/networking.mdx @@ -3,6 +3,8 @@ title: 'Networking' originalFilePath: 'src/networking.md' --- + + EDB Postgres for Kubernetes assumes the underlying Kubernetes cluster has the required connectivity already set up. Networking on Kubernetes is an important and extended topic; please refer to 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 d74b8942080..f868d37652b 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/object_stores.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/object_stores.mdx @@ -3,6 +3,14 @@ title: 'Appendix A - Common object stores for backups' originalFilePath: 'src/appendixes/object_stores.md' --- + + +!!! Warning + With the deprecation of native Barman Cloud support in EDB Postgres for Kubernetes in + favor of the Barman Cloud Plugin, this page—and the backup and recovery + documentation—may undergo changes before the official release of version + 1.26.0. + You can store the [backup](backup.md) files in any service that is supported by the Barman Cloud infrastructure. That is: diff --git a/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx b/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx index f06963d9dea..62a8fe806d9 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx @@ -198,20 +198,39 @@ in OpenShift documentation. ## Channels -Since the release of version 1.16.0, EDB Postgres for Kubernetes is available in the following -[OLM channels](https://olm.operatorframework.io/docs/best-practices/channel-naming/): - -- `fast`: the head version in the channel is always the latest available patch - release in the latest available minor release of EDB Postgres for Kubernetes -- `stable-vX.Y`: the head version in the channel is always the latest available - patch release in the X.Y minor release of EDB Postgres for Kubernetes - -While `fast` might contain versions spanning over multiple minor versions, the -`stable-vX.Y` branches include only patch versions of the same minor release. - -Considering the both CloudNativePG and EDB Postgres for Kubernetes are -developed using the *trunk development* and *continuous delivery* DevOps -principles, our recommendation is to use the `fast` channel. +EDB Postgres for Kubernetes is distributed through the following +[OLM channels](https://olm.operatorframework.io/docs/best-practices/channel-naming/), +each serving a distinct purpose: + +- `candidate`: this channel provides early access to the next potential `fast` + release. It includes the latest pre-release versions with new features and + fixes, but is considered experimental and not supported. Use this channel only + for testing and validation purposes—**not in production environments**. Versions in + `candidate` may not appear in other channels if no further updates are + recommended. + +- `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. + +- `stable`: similar to `fast`, but restricted to the latest **minor release** + currently under EDB’s Long Term Support (LTS) policy. Designed for users who + require predictable updates and official support while benefiting from ongoing + stability and maintenance. + +- `stable-vX.Y`: tracks the latest patch release within a specific minor + version (e.g., `stable-v1.26`). These channels are ideal for environments + that require version pinning and predictable updates within a stable minor + release. + +The `fast` and `stable` channels may span multiple minor versions, whereas +each `stable-vX.Y` channel is limited to patch updates within a specific minor +release. + +**EDB Postgres for Kubernetes** follow *trunk-based development* and +*continuous delivery* principles. As a result, we generally recommend using the +`fast` channel to stay current with the latest stable improvements and fixes. ## Installation via web console 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 a003957462a..29bba09d99b 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 @@ -3,6 +3,8 @@ title: 'Operator capability levels' originalFilePath: 'src/operator_capability_levels.md' --- + + These capabilities were implemented by EDB Postgres for Kubernetes, classified using the [Operator SDK definition of Capability Levels](https://operatorframework.io/operator-capabilities/) @@ -150,7 +152,7 @@ required, as part of the bootstrap. Additional databases can be created or managed via [declarative database management](declarative_database_management.md) using -the `Database` CRD. +the `Database` CRD, also supporting extensions and schemas. Although no configuration is required to run the cluster, you can customize both PostgreSQL runtime configuration and PostgreSQL host-based @@ -162,7 +164,7 @@ EDB Postgres for Kubernetes supports [management of PostgreSQL roles, users, and groups through declarative configuration](declarative_role_management.md) using the `.spec.managed.roles` stanza. -### Pod security policies +### Pod security standards For InfoSec requirements, the operator doesn't require privileged mode for any container. It enforces a read-only root filesystem to guarantee containers @@ -331,11 +333,8 @@ or a subsequent switchover of the cluster. ### Upgrade of the managed workload The operand can be upgraded using a declarative configuration approach as -part of changing the CR and, in particular, the `imageName` parameter. The -operator prevents major upgrades of PostgreSQL while making it possible to go -in both directions in terms of minor PostgreSQL releases within a major -version, enabling updates and rollbacks. - +part of changing the CR and, in particular, the `imageName` parameter. +This is normally initiated by security updates or Postgres minor version updates. In the presence of standby servers, the operator performs rolling updates starting from the replicas. It does this by dropping the existing pod and creating a new one with the new requested operand image that reuses the underlying storage. @@ -347,11 +346,24 @@ The setting to use depends on the business requirements, as the operation might generate some downtime for the applications. This downtime can range from a few seconds to minutes, based on the actual database workload. +### Offline In-Place Major Upgrades of PostgreSQL + +EDB Postgres for Kubernetes supports declarative offline in-place major upgrades when a new +operand container image with a higher PostgreSQL major version is applied to a +cluster. The upgrade can be triggered by updating the image tag via the +`.spec.imageName` option or by using an image catalog to manage version +changes. During the upgrade, all cluster pods are shut down to ensure data +consistency. A new job is then created to validate the upgrade conditions, +execute `pg_upgrade`, and create new directories for `PGDATA`, WAL files, and +tablespaces if needed. Once the upgrade is complete, replicas are re-created. +Failed upgrades can be rolled back. + ### Display cluster availability status during upgrade At any time, convey the cluster's high availability status, for example, `Setting up primary`, `Creating a new replica`, `Cluster in healthy state`, -`Switchover in progress`, `Failing over`, and `Upgrading cluster`. +`Switchover in progress`, `Failing over`, `Upgrading cluster`, and `Upgrading +Postgres major version`. ## Level 3: Full lifecycle 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 49373e83b2b..2d70e6f5862 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/operator_conf.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/operator_conf.mdx @@ -3,6 +3,8 @@ title: 'Operator configuration' originalFilePath: 'src/operator_conf.md' --- + + The operator for EDB Postgres for Kubernetes is installed from a standard deployment manifest and follows the convention over configuration paradigm. While this is fine in most cases, there are some scenarios where you want @@ -38,24 +40,28 @@ is located in the same namespace of the operator deployment and with 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` | -| `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. | -| `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 | -| `PULL_SECRET_NAME` | Name of an additional pull secret to be defined in the operator's namespace and to be used to download images | +| 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_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. | +| `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) for replication connections from standby instances to the primary. Default is 0 (system's default). | +| `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`. | 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`. diff --git a/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/index.mdx b/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/index.mdx index 99154ae3443..ae824cbb8ea 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/index.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/index.mdx @@ -1,11 +1,10 @@ --- -title: API Reference - v1.25.1 +title: API Reference - v1.26.0-rc1 originalFilePath: src/pg4k.v1.md navTitle: API Reference navigation: - - v1.25.1 + - v1.26.0-rc1 - v1.25.0 - - v1.24.3 - v1.24.2 - v1.24.1 - v1.24.0 @@ -123,7 +122,7 @@ navigation: ## Backup -

Backup is the Schema for the backups API

+

A Backup resource is a request for a PostgreSQL backup by the user.

@@ -2361,18 +2360,19 @@ This field is reported when .spec.failoverDelay is populated or dur

OnlineUpdateEnabled shows if the online upgrade is enabled inside the cluster

- -
FieldDescription
azurePVCUpdateEnabled
-bool +
image
+string 		-

AzurePVCUpdateEnabled shows if the PVC online upgrade is enabled for this cluster

+

Image contains the image name used by the pods
image
+
majorVersionUpgradeFromImage
string 		-

Image contains the image name used by the pods

+

MajorVersionUpgradeFromImage contains the image that was +running before the major version upgrade started.
pluginStatus
@@ -2478,6 +2478,80 @@ PostgreSQL cluster from an existing storage
+
+ +## DatabaseObjectSpec + +**Appears in:** + +- [ExtensionSpec](#postgresql-k8s-enterprisedb-io-v1-ExtensionSpec) + +- [SchemaSpec](#postgresql-k8s-enterprisedb-io-v1-SchemaSpec) + +

DatabaseObjectSpec contains the fields which are common to every +database object

+ + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

Name of the extension/schema

+
ensure
+EnsureOption +		 +

Specifies whether an extension/schema should be present or absent in +the database. If set to present, the extension/schema will be +created if it does not exist. If set to absent, the +extension/schema will be removed if it exists.

+
+ +
+ +## DatabaseObjectStatus + +**Appears in:** + +- [DatabaseStatus](#postgresql-k8s-enterprisedb-io-v1-DatabaseStatus) + +

DatabaseObjectStatus is the status of the managed database objects

+ + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

The name of the object

+
applied [Required]
+bool +		 +

True of the object has been installed successfully in +the database

+
message
+string +		 +

Message is the object reconciliation message

+
+
## DatabaseReclaimPolicy @@ -2689,6 +2763,20 @@ tablespace used for objects created in this database.

The policy for end-of-life maintenance of this database.

+schemas
+[]SchemaSpec + + +

The list of schemas to be managed in the database

+ + +extensions
+[]ExtensionSpec + + +

The list of extensions to be managed in the database

+ + @@ -2727,6 +2815,20 @@ desired state that was synchronized

Message is the reconciliation output message

+schemas
+[]DatabaseObjectStatus + + +

Schemas is the status of the managed schemas

+ + +extensions
+[]DatabaseObjectStatus + + +

Extensions is the status of the managed extensions

+ + @@ -2796,6 +2898,8 @@ desired state that was synchronized

**Appears in:** +- [DatabaseObjectSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseObjectSpec) + - [DatabaseSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseSpec) - [RoleConfiguration](#postgresql-k8s-enterprisedb-io-v1-RoleConfiguration) @@ -2834,6 +2938,49 @@ storage

+
+ +## ExtensionSpec + +**Appears in:** + +- [DatabaseSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseSpec) + +

ExtensionSpec configures an extension in a database

+ + + + + + + + + + + + + + +
FieldDescription
DatabaseObjectSpec
+DatabaseObjectSpec +		(Members of DatabaseObjectSpec are embedded into this type.) +

Common fields

+
version [Required]
+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)

+
schema [Required]
+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.

+
+
## ExternalCluster @@ -4309,6 +4456,8 @@ the primary server of the cluster as part of rolling updates

**Appears in:** +- [ProbeWithStrategy](#postgresql-k8s-enterprisedb-io-v1-ProbeWithStrategy) + - [ProbesConfiguration](#postgresql-k8s-enterprisedb-io-v1-ProbesConfiguration)

Probe describes a health check to be performed against a container to determine whether it is @@ -4377,6 +4526,56 @@ Minimum value is 1. spec.terminationGracePeriodSeconds is used if unset.

+
+ +## ProbeStrategyType + +(Alias of `string`) + +**Appears in:** + +- [ProbeWithStrategy](#postgresql-k8s-enterprisedb-io-v1-ProbeWithStrategy) + +

ProbeStrategyType is the type of the strategy used to declare a PostgreSQL instance +ready

+ +
+ +## ProbeWithStrategy + +**Appears in:** + +- [ProbesConfiguration](#postgresql-k8s-enterprisedb-io-v1-ProbesConfiguration) + +

ProbeWithStrategy is the configuration of the startup probe

+ + + + + + + + + + + + + + +
FieldDescription
Probe
+Probe +		(Members of Probe are embedded into this type.) +

Probe is the standard probe configuration

+
type
+ProbeStrategyType +		 +

The probe strategy

+
maximumLag
+k8s.io/apimachinery/pkg/api/resource.Quantity +		 +

Lag limit. Used only for streaming strategy

+
+
## ProbesConfiguration @@ -4392,7 +4591,7 @@ to be injected in the PostgreSQL Pods

FieldDescription startup [Required]
-Probe +ProbeWithStrategy

The startup probe configuration

@@ -4406,7 +4605,7 @@ to be injected in the PostgreSQL Pods

readiness [Required]
-Probe +ProbeWithStrategy

The readiness probe configuration

@@ -5185,6 +5384,38 @@ Overrides the default settings specified in the cluster '.backup.volumeSnapshot. +
+ +## SchemaSpec + +**Appears in:** + +- [DatabaseSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseSpec) + +

SchemaSpec configures a schema in a database

+ + + + + + + + + + + +
FieldDescription
DatabaseObjectSpec
+DatabaseObjectSpec +		(Members of DatabaseObjectSpec are embedded into this type.) +

Common fields

+
owner [Required]
+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.

+
+
## SecretVersion diff --git a/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.26.0-rc1.mdx b/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.26.0-rc1.mdx new file mode 100644 index 00000000000..e60827fb1c5 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.26.0-rc1.mdx @@ -0,0 +1,6184 @@ +--- +title: API Reference - v1.26.0-rc1 +navTitle: v1.26.0-rc1 +pdfExclude: 'true' + +--- + +

Package v1 contains API Schema definitions for the postgresql v1 API group

+ +## Resource Types + +- [Backup](#postgresql-k8s-enterprisedb-io-v1-Backup) +- [Cluster](#postgresql-k8s-enterprisedb-io-v1-Cluster) +- [ClusterImageCatalog](#postgresql-k8s-enterprisedb-io-v1-ClusterImageCatalog) +- [Database](#postgresql-k8s-enterprisedb-io-v1-Database) +- [ImageCatalog](#postgresql-k8s-enterprisedb-io-v1-ImageCatalog) +- [Pooler](#postgresql-k8s-enterprisedb-io-v1-Pooler) +- [Publication](#postgresql-k8s-enterprisedb-io-v1-Publication) +- [ScheduledBackup](#postgresql-k8s-enterprisedb-io-v1-ScheduledBackup) +- [Subscription](#postgresql-k8s-enterprisedb-io-v1-Subscription) + +
+ +## Backup + +

A Backup resource is a request for a PostgreSQL backup by the user.

+ + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		Backup
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+BackupSpec +		 +

Specification of the desired behavior of the backup. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
status
+BackupStatus +		 +

Most recently observed status of the backup. This data may not be up to +date. Populated by the system. Read-only. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## Cluster + +

Cluster is the Schema for the PostgreSQL API

+ + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		Cluster
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+ClusterSpec +		 +

Specification of the desired behavior of the cluster. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
status
+ClusterStatus +		 +

Most recently observed status of the cluster. This data may not be up +to date. Populated by the system. Read-only. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## ClusterImageCatalog + +

ClusterImageCatalog is the Schema for the clusterimagecatalogs API

+ + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		ClusterImageCatalog
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+ImageCatalogSpec +		 +

Specification of the desired behavior of the ClusterImageCatalog. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## Database + +

Database is the Schema for the databases API

+ + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		Database
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+DatabaseSpec +		 +

Specification of the desired Database. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
status
+DatabaseStatus +		 +

Most recently observed status of the Database. This data may not be up to +date. Populated by the system. Read-only. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## ImageCatalog + +

ImageCatalog is the Schema for the imagecatalogs API

+ + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		ImageCatalog
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+ImageCatalogSpec +		 +

Specification of the desired behavior of the ImageCatalog. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## Pooler + +

Pooler is the Schema for the poolers API

+ + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		Pooler
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+PoolerSpec +		 +

Specification of the desired behavior of the Pooler. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
status
+PoolerStatus +		 +

Most recently observed status of the Pooler. This data may not be up to +date. Populated by the system. Read-only. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## Publication + +

Publication is the Schema for the publications API

+ + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		Publication
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+PublicationSpec +		 + No description provided.
status [Required]
+PublicationStatus +		 + No description provided.
+ +
+ +## ScheduledBackup + +

ScheduledBackup is the Schema for the scheduledbackups API

+ + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		ScheduledBackup
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+ScheduledBackupSpec +		 +

Specification of the desired behavior of the ScheduledBackup. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
status
+ScheduledBackupStatus +		 +

Most recently observed status of the ScheduledBackup. This data may not be up +to date. Populated by the system. Read-only. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## Subscription + +

Subscription is the Schema for the subscriptions API

+ + + + + + + + + + + + + + + + +
FieldDescription
apiVersion [Required]
string		postgresql.k8s.enterprisedb.io/v1
kind [Required]
string		Subscription
metadata [Required]
+meta/v1.ObjectMeta +		 + No description provided.Refer to the Kubernetes API documentation for the fields of the metadata field.
spec [Required]
+SubscriptionSpec +		 + No description provided.
status [Required]
+SubscriptionStatus +		 + No description provided.
+ +
+ +## AffinityConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

AffinityConfiguration contains the info we need to create the +affinity rules for Pods

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
enablePodAntiAffinity
+bool +		 +

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
+map[string]string +		 +

NodeSelector is map of key-value pairs used to define the nodes on which +the pods can run. +More info: https://kubernetes.io/docs/concepts/configuration/assign-pod-node/

+
nodeAffinity
+core/v1.NodeAffinity +		 +

NodeAffinity describes node affinity scheduling rules for the pod. +More info: https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#node-affinity

+
tolerations
+[]core/v1.Toleration +		 +

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: https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/

+
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: +https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#inter-pod-affinity-and-anti-affinity

+
additionalPodAntiAffinity
+core/v1.PodAntiAffinity +		 +

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
+core/v1.PodAffinity +		 +

AdditionalPodAffinity allows to specify pod affinity terms to be passed to all the cluster's pods.

+
+ +
+ +## AvailableArchitecture + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

AvailableArchitecture represents the state of a cluster's architecture

+ + + + + + + + + + + +
FieldDescription
goArch [Required]
+string +		 +

GoArch is the name of the executable architecture

+
hash [Required]
+string +		 +

Hash is the hash of the executable

+
+ +
+ +## BackupConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

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

+ + + + + + + + + + + + + + + + + +
FieldDescription
volumeSnapshot
+VolumeSnapshotConfiguration +		 +

VolumeSnapshot provides the configuration for the execution of volume snapshot backups.

+
barmanObjectStore
+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.

+
target
+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.

+
+ +
+ +## BackupMethod + +(Alias of `string`) + +**Appears in:** + +- [BackupSpec](#postgresql-k8s-enterprisedb-io-v1-BackupSpec) + +- [BackupStatus](#postgresql-k8s-enterprisedb-io-v1-BackupStatus) + +- [ScheduledBackupSpec](#postgresql-k8s-enterprisedb-io-v1-ScheduledBackupSpec) + +

BackupMethod defines the way of executing the physical base backups of +the selected PostgreSQL instance

+ +
+ +## BackupPhase + +(Alias of `string`) + +**Appears in:** + +- [BackupStatus](#postgresql-k8s-enterprisedb-io-v1-BackupStatus) + +

BackupPhase is the phase of the backup

+ +
+ +## BackupPluginConfiguration + +**Appears in:** + +- [BackupSpec](#postgresql-k8s-enterprisedb-io-v1-BackupSpec) + +- [ScheduledBackupSpec](#postgresql-k8s-enterprisedb-io-v1-ScheduledBackupSpec) + +

BackupPluginConfiguration contains the backup configuration used by +the backup plugin

+ + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

Name is the name of the plugin managing this backup

+
parameters
+map[string]string +		 +

Parameters are the configuration parameters passed to the backup +plugin for this backup

+
+ +
+ +## BackupSnapshotElementStatus + +**Appears in:** + +- [BackupSnapshotStatus](#postgresql-k8s-enterprisedb-io-v1-BackupSnapshotStatus) + +

BackupSnapshotElementStatus is a volume snapshot that is part of a volume snapshot method backup

+ + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

Name is the snapshot resource name

+
type [Required]
+string +		 +

Type is tho role of the snapshot in the cluster, such as PG_DATA, PG_WAL and PG_TABLESPACE

+
tablespaceName
+string +		 +

TablespaceName is the name of the snapshotted tablespace. Only set +when type is PG_TABLESPACE

+
+ +
+ +## BackupSnapshotStatus + +**Appears in:** + +- [BackupStatus](#postgresql-k8s-enterprisedb-io-v1-BackupStatus) + +

BackupSnapshotStatus the fields exclusive to the volumeSnapshot method backup

+ + + + + + + + +
FieldDescription
elements
+[]BackupSnapshotElementStatus +		 +

The elements list, populated with the gathered volume snapshots

+
+ +
+ +## BackupSource + +**Appears in:** + +- [BootstrapRecovery](#postgresql-k8s-enterprisedb-io-v1-BootstrapRecovery) + +

BackupSource contains the backup we need to restore from, plus some +information that could be needed to correctly restore it.

+ + + + + + + + + + + +
FieldDescription
LocalObjectReference
+github.com/cloudnative-pg/machinery/pkg/api.LocalObjectReference +		(Members of LocalObjectReference are embedded into this type.) + No description provided.
endpointCA
+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 + +**Appears in:** + +- [Backup](#postgresql-k8s-enterprisedb-io-v1-Backup) + +

BackupSpec defines the desired state of Backup

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
cluster [Required]
+github.com/cloudnative-pg/machinery/pkg/api.LocalObjectReference +		 +

The cluster to backup

+
target
+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.

+
method
+BackupMethod +		 +

The backup method to be used, possible options are barmanObjectStore, +volumeSnapshot or plugin. Defaults to: barmanObjectStore.

+
pluginConfiguration
+BackupPluginConfiguration +		 +

Configuration parameters passed to the plugin managing this backup

+
online
+bool +		 +

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 +		 +

Configuration parameters to control the online/hot backup with volume snapshots +Overrides the default settings specified in the cluster '.backup.volumeSnapshot.onlineConfiguration' stanza

+
+ +
+ +## BackupStatus + +**Appears in:** + +- [Backup](#postgresql-k8s-enterprisedb-io-v1-Backup) + +

BackupStatus defines the observed state of Backup

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
BarmanCredentials
+github.com/cloudnative-pg/barman-cloud/pkg/api.BarmanCredentials +		(Members of BarmanCredentials are embedded into this type.) +

The potential credentials for each cloud provider

+
endpointCA
+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 +		 +

The last backup status

+
startedAt
+meta/v1.Time +		 +

When the backup was started

+
stoppedAt
+meta/v1.Time +		 +

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
+[]byte +		 +

Backup label file content as returned by Postgres in case of online (hot) backups

+
tablespaceMapFile
+[]byte +		 +

Tablespace map file content as returned by Postgres in case of online (hot) backups

+
instanceID
+InstanceID +		 +

Information to identify the instance where the backup has been taken from

+
snapshotBackupStatus
+BackupSnapshotStatus +		 +

Status of the volumeSnapshot backup

+
method
+BackupMethod +		 +

The backup method being used

+
online
+bool +		 +

Whether the backup was online/hot (true) or offline/cold (false)

+
pluginMetadata
+map[string]string +		 +

A map containing the plugin metadata

+
+ +
+ +## BackupTarget + +(Alias of `string`) + +**Appears in:** + +- [BackupConfiguration](#postgresql-k8s-enterprisedb-io-v1-BackupConfiguration) + +- [BackupSpec](#postgresql-k8s-enterprisedb-io-v1-BackupSpec) + +- [ScheduledBackupSpec](#postgresql-k8s-enterprisedb-io-v1-ScheduledBackupSpec) + +

BackupTarget describes the preferred targets for a backup

+ +
+ +## BootstrapConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

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.

+ + + + + + + + + + + + + + +
FieldDescription
initdb
+BootstrapInitDB +		 +

Bootstrap the cluster via initdb

+
recovery
+BootstrapRecovery +		 +

Bootstrap the cluster from a backup

+
pg_basebackup
+BootstrapPgBaseBackup +		 +

Bootstrap the cluster taking a physical backup of another compatible +PostgreSQL instance

+
+ +
+ +## BootstrapInitDB + +**Appears in:** + +- [BootstrapConfiguration](#postgresql-k8s-enterprisedb-io-v1-BootstrapConfiguration) + +

BootstrapInitDB is the configuration of the bootstrap process when +initdb is used +Refer to the Bootstrap page of the documentation for more information.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
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
+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
+bool +		 +

If we need to enable/disable Redwood compatibility. Requires +EPAS and for EPAS defaults to true

+
options
+[]string +		 +

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
+bool +		 +

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
+int +		 +

The value in megabytes (1 to 1024) to be passed to the --wal-segsize +option for initdb (default: empty, resulting in PostgreSQL default: 16MB)

+
postInitSQL
+[]string +		 +

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 +		 +

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 +		 +

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 +		 +

Bootstraps the new cluster by importing data from an existing PostgreSQL +instance using logical backup (pg_dump and pg_restore)

+
postInitApplicationSQLRefs
+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 +		 +

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 +		 +

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 + +**Appears in:** + +- [BootstrapConfiguration](#postgresql-k8s-enterprisedb-io-v1-BootstrapConfiguration) + +

BootstrapPgBaseBackup contains the configuration required to take +a physical backup of an existing PostgreSQL cluster

+ + + + + + + + + + + + + + + + + +
FieldDescription
source [Required]
+string +		 +

The name of the server of which we need to take a physical backup

+
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
+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 + +**Appears in:** + +- [BootstrapConfiguration](#postgresql-k8s-enterprisedb-io-v1-BootstrapConfiguration) + +

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.
    2. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
backup
+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 +		 +

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 EDB Postgres for Kubernetes, 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 +		 +

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: https://www.postgresql.org/docs/current/runtime-config-wal.html#RUNTIME-CONFIG-WAL-RECOVERY-TARGET

+
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
+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

+
+ +
+ +## CatalogImage + +**Appears in:** + +- [ImageCatalogSpec](#postgresql-k8s-enterprisedb-io-v1-ImageCatalogSpec) + +

CatalogImage defines the image and major version

+ + + + + + + + + + + +
FieldDescription
image [Required]
+string +		 +

The image reference

+
major [Required]
+int +		 +

The PostgreSQL major version of the image. Must be unique within the catalog.

+
+ +
+ +## CertificatesConfiguration + +**Appears in:** + +- [CertificatesStatus](#postgresql-k8s-enterprisedb-io-v1-CertificatesStatus) + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

CertificatesConfiguration contains the needed configurations to handle server certificates.

+ + + + + + + + + + + + + + + + + + + + +
FieldDescription
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 +		 +

The list of the server alternative DNS names to be added to the generated server TLS certificates, when required.

+
+ +
+ +## CertificatesStatus + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

CertificatesStatus contains configuration certificates and related expiration dates.

+ + + + + + + + + + + +
FieldDescription
CertificatesConfiguration
+CertificatesConfiguration +		(Members of CertificatesConfiguration are embedded into this type.) +

Needed configurations to handle server certificates, initialized with default values, if needed.

+
expirations
+map[string]string +		 +

Expiration dates for all certificates.

+
+ +
+ +## ClusterMonitoringTLSConfiguration + +**Appears in:** + +- [MonitoringConfiguration](#postgresql-k8s-enterprisedb-io-v1-MonitoringConfiguration) + +

ClusterMonitoringTLSConfiguration is the type containing the TLS configuration +for the cluster's monitoring

+ + + + + + + + +
FieldDescription
enabled
+bool +		 +

Enable TLS for the monitoring endpoint. +Changing this option will force a rollout of all instances.

+
+ +
+ +## ClusterSpec + +**Appears in:** + +- [Cluster](#postgresql-k8s-enterprisedb-io-v1-Cluster) + +

ClusterSpec defines the desired state of Cluster

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
description
+string +		 +

Description of this PostgreSQL cluster

+
inheritedMetadata
+EmbeddedObjectMetadata +		 +

Metadata that will be inherited by all objects related to the Cluster

+
imageName
+string +		 +

Name of the container image, supporting both tags (<image>:<tag>) +and digests for deterministic and repeatable deployments +(<image>:<tag>@sha256:<digestValue>)

+
imageCatalogRef
+ImageCatalogRef +		 +

Defines the major PostgreSQL version we want to use within an ImageCatalog

+
imagePullPolicy
+core/v1.PullPolicy +		 +

Image pull policy. +One of Always, Never or IfNotPresent. +If not defined, it defaults to IfNotPresent. +Cannot be updated. +More info: https://kubernetes.io/docs/concepts/containers/images#updating-images

+
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: +https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/

+
postgresUID
+int64 +		 +

The UID of the postgres user inside the image, defaults to 26

+
postgresGID
+int64 +		 +

The GID of the postgres user inside the image, defaults to 26

+
instances [Required]
+int +		 +

Number of instances required in the cluster

+
minSyncReplicas
+int +		 +

Minimum number of instances required in synchronous replication with the +primary. Undefined or 0 allow writes to complete when no standby is +available.

+
maxSyncReplicas
+int +		 +

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.

+
postgresql
+PostgresConfiguration +		 +

Configuration of the PostgreSQL server

+
replicationSlots
+ReplicationSlotsConfiguration +		 +

Replication slots management configuration

+
bootstrap
+BootstrapConfiguration +		 +

Instructions to bootstrap this cluster

+
replica
+ReplicaClusterConfiguration +		 +

Replica cluster configuration

+
superuserSecret
+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
+bool +		 +

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 +		 +

The configuration for the CA and related certificates

+
imagePullSecrets
+[]github.com/cloudnative-pg/machinery/pkg/api.LocalObjectReference +		 +

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 +		 +

Configuration of the storage of the instances

+
serviceAccountTemplate
+ServiceAccountTemplate +		 +

Configure the generation of the service account

+
walStorage
+StorageConfiguration +		 +

Configuration of the storage for PostgreSQL WAL (Write-Ahead Log)

+
ephemeralVolumeSource
+core/v1.EphemeralVolumeSource +		 +

EphemeralVolumeSource allows the user to configure the source of ephemeral volumes.

+
startDelay
+int32 +		 +

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).

+
stopDelay
+int32 +		 +

The time in seconds that is allowed for a PostgreSQL instance to +gracefully shutdown (default 1800)

+
smartStopDelay
+int32 +		 +

Deprecated: please use SmartShutdownTimeout instead

+
smartShutdownTimeout
+int32 +		 +

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).

+
switchoverDelay
+int32 +		 +

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).

+
failoverDelay
+int32 +		 +

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

+
livenessProbeTimeout
+int32 +		 +

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 +		 +

Affinity/Anti-affinity rules for Pods

+
topologySpreadConstraints
+[]core/v1.TopologySpreadConstraint +		 +

TopologySpreadConstraints specifies how to spread matching pods among the given topology. +More info: +https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/

+
resources
+core/v1.ResourceRequirements +		 +

Resources requirements of every generated Pod. Please refer to +https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ +for more information.

+
ephemeralVolumesSizeLimit
+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 +https://kubernetes.io/docs/concepts/scheduling-eviction/pod-priority-preemption/#priorityclass +for more information

+
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)

+
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)

+
backup
+BackupConfiguration +		 +

The configuration to be used for backups

+
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
+core/v1.SecretKeySelector +		 +

The reference to the license key. When this is set it take precedence over LicenseKey.

+
monitoring
+MonitoringConfiguration +		 +

The configuration of the monitoring infrastructure of this cluster

+
externalClusters
+[]ExternalCluster +		 +

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

+
projectedVolumeTemplate
+core/v1.ProjectedVolumeSource +		 +

Template to be used to define projected volumes, projected volumes will be mounted +under /projected base folder

+
env
+[]core/v1.EnvVar +		 +

Env follows the Env format to pass environment variables +to the pods created in the cluster

+
envFrom
+[]core/v1.EnvFromSource +		 +

EnvFrom follows the EnvFrom format to pass environment variables +sources to the pods to be used by Env

+
managed
+ManagedConfiguration +		 +

The configuration that is used by the portions of PostgreSQL that are managed by the instance manager

+
seccompProfile
+core/v1.SeccompProfile +		 +

The SeccompProfile applied to every Pod and Container. +Defaults to: RuntimeDefault

+
tablespaces
+[]TablespaceConfiguration +		 +

The tablespaces configuration

+
enablePDB
+bool +		 +

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.

+
plugins
+[]PluginConfiguration +		 +

The plugins configuration, containing +any plugin to be loaded with the corresponding configuration

+
probes
+ProbesConfiguration +		 +

The configuration of the probes to be injected +in the PostgreSQL Pods.

+
+ +
+ +## ClusterStatus + +**Appears in:** + +- [Cluster](#postgresql-k8s-enterprisedb-io-v1-Cluster) + +

ClusterStatus defines the observed state of Cluster

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
instances
+int +		 +

The total number of PVC Groups detected in the cluster. It may differ from the number of existing instance pods.

+
readyInstances
+int +		 +

The total number of ready instances in the cluster. It is equal to the number of ready instance pods.

+
instancesStatus
+map[PodStatus][]string +		 +

InstancesStatus indicates in which status the instances are

+
instancesReportedState
+map[PodName]InstanceReportedState +		 +

The reported state of the instances during the last reconciliation loop

+
managedRolesStatus
+ManagedRoles +		 +

ManagedRolesStatus reports the state of the managed roles in the cluster

+
tablespacesStatus
+[]TablespaceState +		 +

TablespacesStatus reports the state of the declarative tablespaces in the cluster

+
timelineID
+int +		 +

The timeline of the Postgres cluster

+
topology
+Topology +		 +

Instances topology.

+
latestGeneratedNode
+int +		 +

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
+int32 +		 +

How many PVCs have been created by this cluster

+
jobCount
+int32 +		 +

How many Jobs have been created by this cluster

+
danglingPVC
+[]string +		 +

List of all the PVCs created by this cluster and still available +which are not attached to a Pod

+
resizingPVC
+[]string +		 +

List of all the PVCs that have ResizingPVC condition.

+
initializingPVC
+[]string +		 +

List of all the PVCs that are being initialized by this cluster

+
healthyPVC
+[]string +		 +

List of all the PVCs not dangling nor initializing

+
unusablePVC
+[]string +		 +

List of all the PVCs that are unusable because another PVC is missing

+
licenseStatus
+github.com/EnterpriseDB/cloud-native-postgres/pkg/licensekey.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 +		 +

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 +		 +

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 +		 +

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

+
firstRecoverabilityPointByMethod
+map[BackupMethod]meta/v1.Time +		 +

The first recoverability point, stored as a date in RFC3339 format, per backup method type

+
lastSuccessfulBackup
+string +		 +

Last successful backup, stored as a date in RFC3339 format +This field is calculated from the content of LastSuccessfulBackupByMethod

+
lastSuccessfulBackupByMethod
+map[BackupMethod]meta/v1.Time +		 +

Last successful backup, stored as a date in RFC3339 format, per backup method type

+
lastFailedBackup
+string +		 +

Stored as a date in RFC3339 format

+
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 +		 +

The integration needed by poolers referencing the cluster

+
cloudNativePostgresqlOperatorHash
+string +		 +

The hash of the binary of the operator

+
availableArchitectures
+[]AvailableArchitecture +		 +

AvailableArchitectures reports the available architectures of a cluster

+
conditions
+[]meta/v1.Condition +		 +

Conditions for cluster object

+
instanceNames
+[]string +		 +

List of instance names in the cluster

+
onlineUpdateEnabled
+bool +		 +

OnlineUpdateEnabled shows if the online upgrade is enabled inside the cluster

+
image
+string +		 +

Image contains the image name used by the pods

+
majorVersionUpgradeFromImage
+string +		 +

MajorVersionUpgradeFromImage contains the image that was +running before the major version upgrade started.

+
pluginStatus
+[]PluginStatus +		 +

PluginStatus is the status of the loaded plugins

+
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

+
+ +
+ +## ConfigMapResourceVersion + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

ConfigMapResourceVersion is the resource versions of the secrets +managed by the operator

+ + + + + + + + +
FieldDescription
metrics
+map[string]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 + +(Alias of `string`) + +**Appears in:** + +- [SynchronousReplicaConfiguration](#postgresql-k8s-enterprisedb-io-v1-SynchronousReplicaConfiguration) + +

DataDurabilityLevel specifies how strictly to enforce synchronous replication +when cluster instances are unavailable. Options are required or preferred.

+ +
+ +## DataSource + +**Appears in:** + +- [BootstrapRecovery](#postgresql-k8s-enterprisedb-io-v1-BootstrapRecovery) + +

DataSource contains the configuration required to bootstrap a +PostgreSQL cluster from an existing storage

+ + + + + + + + + + + + + + +
FieldDescription
storage [Required]
+core/v1.TypedLocalObjectReference +		 +

Configuration of the storage of the instances

+
walStorage
+core/v1.TypedLocalObjectReference +		 +

Configuration of the storage for PostgreSQL WAL (Write-Ahead Log)

+
tablespaceStorage
+map[string]core/v1.TypedLocalObjectReference +		 +

Configuration of the storage for PostgreSQL tablespaces

+
+ +
+ +## DatabaseObjectSpec + +**Appears in:** + +- [ExtensionSpec](#postgresql-k8s-enterprisedb-io-v1-ExtensionSpec) + +- [SchemaSpec](#postgresql-k8s-enterprisedb-io-v1-SchemaSpec) + +

DatabaseObjectSpec contains the fields which are common to every +database object

+ + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

Name of the extension/schema

+
ensure
+EnsureOption +		 +

Specifies whether an extension/schema should be present or absent in +the database. If set to present, the extension/schema will be +created if it does not exist. If set to absent, the +extension/schema will be removed if it exists.

+
+ +
+ +## DatabaseObjectStatus + +**Appears in:** + +- [DatabaseStatus](#postgresql-k8s-enterprisedb-io-v1-DatabaseStatus) + +

DatabaseObjectStatus is the status of the managed database objects

+ + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

The name of the object

+
applied [Required]
+bool +		 +

True of the object has been installed successfully in +the database

+
message
+string +		 +

Message is the object reconciliation message

+
+ +
+ +## DatabaseReclaimPolicy + +(Alias of `string`) + +**Appears in:** + +- [DatabaseSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseSpec) + +

DatabaseReclaimPolicy describes a policy for end-of-life maintenance of databases.

+ +
+ +## DatabaseRoleRef + +**Appears in:** + +- [TablespaceConfiguration](#postgresql-k8s-enterprisedb-io-v1-TablespaceConfiguration) + +

DatabaseRoleRef is a reference an a role available inside PostgreSQL

+ + + + + + + + +
FieldDescription
name
+string +		 + No description provided.
+ +
+ +## DatabaseSpec + +**Appears in:** + +- [Database](#postgresql-k8s-enterprisedb-io-v1-Database) + +

DatabaseSpec is the specification of a Postgresql Database, built around the +CREATE DATABASE, ALTER DATABASE, and DROP DATABASE SQL commands of +PostgreSQL.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
cluster [Required]
+core/v1.LocalObjectReference +		 +

The name of the PostgreSQL cluster hosting the database.

+
ensure
+EnsureOption +		 +

Ensure the PostgreSQL database is present or absent - defaults to "present".

+
name [Required]
+string +		 +

The name of the database to create inside PostgreSQL. This setting cannot be changed.

+
owner [Required]
+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.

+
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
+bool +		 +

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
+bool +		 +

Maps to the ALLOW_CONNECTIONS parameter of CREATE DATABASE and +ALTER DATABASE. If false then no one can connect to this database.

+
connectionLimit
+int +		 +

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 +		 +

The policy for end-of-life maintenance of this database.

+
schemas
+[]SchemaSpec +		 +

The list of schemas to be managed in the database

+
extensions
+[]ExtensionSpec +		 +

The list of extensions to be managed in the database

+
+ +
+ +## DatabaseStatus + +**Appears in:** + +- [Database](#postgresql-k8s-enterprisedb-io-v1-Database) + +

DatabaseStatus defines the observed state of Database

+ + + + + + + + + + + + + + + + + + + + +
FieldDescription
observedGeneration
+int64 +		 +

A sequence number representing the latest +desired state that was synchronized

+
applied
+bool +		 +

Applied is true if the database was reconciled correctly

+
message
+string +		 +

Message is the reconciliation output message

+
schemas
+[]DatabaseObjectStatus +		 +

Schemas is the status of the managed schemas

+
extensions
+[]DatabaseObjectStatus +		 +

Extensions is the status of the managed extensions

+
+ +
+ +## EPASConfiguration + +**Appears in:** + +- [PostgresConfiguration](#postgresql-k8s-enterprisedb-io-v1-PostgresConfiguration) + +

EPASConfiguration contains EDB Postgres Advanced Server specific configurations

+ + + + + + + + + + + +
FieldDescription
audit
+bool +		 +

If true enables edb_audit logging

+
tde
+TDEConfiguration +		 +

TDE configuration

+
+ +
+ +## EmbeddedObjectMetadata + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

EmbeddedObjectMetadata contains metadata to be inherited by all resources related to a Cluster

+ + + + + + + + + + + +
FieldDescription
labels
+map[string]string +		 + No description provided.
annotations
+map[string]string +		 + No description provided.
+ +
+ +## EnsureOption + +(Alias of `string`) + +**Appears in:** + +- [DatabaseObjectSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseObjectSpec) + +- [DatabaseSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseSpec) + +- [RoleConfiguration](#postgresql-k8s-enterprisedb-io-v1-RoleConfiguration) + +

EnsureOption represents whether we should enforce the presence or absence of +a Role in a PostgreSQL instance

+ +
+ +## EphemeralVolumesSizeLimitConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

EphemeralVolumesSizeLimitConfiguration contains the configuration of the ephemeral +storage

+ + + + + + + + + + + +
FieldDescription
shm
+k8s.io/apimachinery/pkg/api/resource.Quantity +		 +

Shm is the size limit of the shared memory volume

+
temporaryData
+k8s.io/apimachinery/pkg/api/resource.Quantity +		 +

TemporaryData is the size limit of the temporary data volume

+
+ +
+ +## ExtensionSpec + +**Appears in:** + +- [DatabaseSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseSpec) + +

ExtensionSpec configures an extension in a database

+ + + + + + + + + + + + + + +
FieldDescription
DatabaseObjectSpec
+DatabaseObjectSpec +		(Members of DatabaseObjectSpec are embedded into this type.) +

Common fields

+
version [Required]
+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)

+
schema [Required]
+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.

+
+ +
+ +## ExternalCluster + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

ExternalCluster represents the connection parameters to an +external cluster which is used in the other sections of the configuration

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

The server name, required

+
connectionParameters
+map[string]string +		 +

The list of connection parameters, such as dbname, host, username, etc

+
sslCert
+core/v1.SecretKeySelector +		 +

The reference to an SSL certificate to be used to connect to this +instance

+
sslKey
+core/v1.SecretKeySelector +		 +

The reference to an SSL private key to be used to connect to this +instance

+
sslRootCert
+core/v1.SecretKeySelector +		 +

The reference to an SSL CA public key to be used to connect to this +instance

+
password
+core/v1.SecretKeySelector +		 +

The reference to the password to be used to connect to the server. +If a password is provided, EDB Postgres for Kubernetes 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
+github.com/cloudnative-pg/barman-cloud/pkg/api.BarmanObjectStoreConfiguration +		 +

The configuration for the barman-cloud tool suite

+
plugin [Required]
+PluginConfiguration +		 +

The configuration of the plugin that is taking care +of WAL archiving and backups for this external cluster

+
+ +
+ +## ImageCatalogRef + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

ImageCatalogRef defines the reference to a major version in an ImageCatalog

+ + + + + + + + + + + +
FieldDescription
TypedLocalObjectReference
+core/v1.TypedLocalObjectReference +		(Members of TypedLocalObjectReference are embedded into this type.) + No description provided.
major [Required]
+int +		 +

The major version of PostgreSQL we want to use from the ImageCatalog

+
+ +
+ +## ImageCatalogSpec + +**Appears in:** + +- [ClusterImageCatalog](#postgresql-k8s-enterprisedb-io-v1-ClusterImageCatalog) + +- [ImageCatalog](#postgresql-k8s-enterprisedb-io-v1-ImageCatalog) + +

ImageCatalogSpec defines the desired ImageCatalog

+ + + + + + + + +
FieldDescription
images [Required]
+[]CatalogImage +		 +

List of CatalogImages available in the catalog

+
+ +
+ +## Import + +**Appears in:** + +- [BootstrapInitDB](#postgresql-k8s-enterprisedb-io-v1-BootstrapInitDB) + +

Import contains the configuration to init a database from a logic snapshot of an externalCluster

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
source [Required]
+ImportSource +		 +

The source of the import

+
type [Required]
+SnapshotType +		 +

The import type. Can be microservice or monolith.

+
databases [Required]
+[]string +		 +

The databases to import

+
roles
+[]string +		 +

The roles to import

+
postImportApplicationSQL
+[]string +		 +

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
+bool +		 +

When set to true, only the pre-data and post-data sections of +pg_restore are invoked, avoiding data import. Default: false.

+
pgDumpExtraOptions
+[]string +		 +

List of custom options to pass to the pg_dump command. IMPORTANT: +Use these options with caution and at your own risk, as the operator +does not validate their content. Be aware that certain options may +conflict with the operator's intended functionality or design.

+
pgRestoreExtraOptions
+[]string +		 +

List of custom options to pass to the pg_restore command. IMPORTANT: +Use these options with caution and at your own risk, as the operator +does not validate their content. Be aware that certain options may +conflict with the operator's intended functionality or design.

+
+ +
+ +## ImportSource + +**Appears in:** + +- [Import](#postgresql-k8s-enterprisedb-io-v1-Import) + +

ImportSource describes the source for the logical snapshot

+ + + + + + + + +
FieldDescription
externalCluster [Required]
+string +		 +

The name of the externalCluster used for import

+
+ +
+ +## InstanceID + +**Appears in:** + +- [BackupStatus](#postgresql-k8s-enterprisedb-io-v1-BackupStatus) + +

InstanceID contains the information to identify an instance

+ + + + + + + + + + + +
FieldDescription
podName
+string +		 +

The pod name

+
ContainerID
+string +		 +

The container ID

+
+ +
+ +## InstanceReportedState + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

InstanceReportedState describes the last reported state of an instance during a reconciliation loop

+ + + + + + + + + + + +
FieldDescription
isPrimary [Required]
+bool +		 +

indicates if an instance is the primary one

+
timeLineID
+int +		 +

indicates on which TimelineId the instance is

+
+ +
+ +## LDAPBindAsAuth + +**Appears in:** + +- [LDAPConfig](#postgresql-k8s-enterprisedb-io-v1-LDAPConfig) + +

LDAPBindAsAuth provides the required fields to use the +bind authentication for LDAP

+ + + + + + + + + + + +
FieldDescription
prefix
+string +		 +

Prefix for the bind authentication option

+
suffix
+string +		 +

Suffix for the bind authentication option

+
+ +
+ +## LDAPBindSearchAuth + +**Appears in:** + +- [LDAPConfig](#postgresql-k8s-enterprisedb-io-v1-LDAPConfig) + +

LDAPBindSearchAuth provides the required fields to use +the bind+search LDAP authentication process

+ + + + + + + + + + + + + + + + + + + + +
FieldDescription
baseDN
+string +		 +

Root DN to begin the user search

+
bindDN
+string +		 +

DN of the user to bind to the directory

+
bindPassword
+core/v1.SecretKeySelector +		 +

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 + +**Appears in:** + +- [PostgresConfiguration](#postgresql-k8s-enterprisedb-io-v1-PostgresConfiguration) + +

LDAPConfig contains the parameters needed for LDAP authentication

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
server
+string +		 +

LDAP hostname or IP address

+
port
+int +		 +

LDAP server port

+
scheme
+LDAPScheme +		 +

LDAP schema to be used, possible options are ldap and ldaps

+
bindAsAuth
+LDAPBindAsAuth +		 +

Bind as authentication configuration

+
bindSearchAuth
+LDAPBindSearchAuth +		 +

Bind+Search authentication configuration

+
tls
+bool +		 +

Set to 'true' to enable LDAP over TLS. 'false' is default

+
+ +
+ +## LDAPScheme + +(Alias of `string`) + +**Appears in:** + +- [LDAPConfig](#postgresql-k8s-enterprisedb-io-v1-LDAPConfig) + +

LDAPScheme defines the possible schemes for LDAP

+ +
+ +## ManagedConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

ManagedConfiguration represents the portions of PostgreSQL that are managed +by the instance manager

+ + + + + + + + + + + +
FieldDescription
roles
+[]RoleConfiguration +		 +

Database roles managed by the Cluster

+
services
+ManagedServices +		 +

Services roles managed by the Cluster

+
+ +
+ +## ManagedRoles + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

ManagedRoles tracks the status of a cluster's managed roles

+ + + + + + + + + + + + + + +
FieldDescription
byStatus
+map[RoleStatus][]string +		 +

ByStatus gives the list of roles in each state

+
cannotReconcile
+map[string][]string +		 +

CannotReconcile lists roles that cannot be reconciled in PostgreSQL, +with an explanation of the cause

+
passwordStatus
+map[string]PasswordState +		 +

PasswordStatus gives the last transaction id and password secret version for each managed role

+
+ +
+ +## ManagedService + +**Appears in:** + +- [ManagedServices](#postgresql-k8s-enterprisedb-io-v1-ManagedServices) + +

ManagedService represents a specific service managed by the cluster. +It includes the type of service and its associated template specification.

+ + + + + + + + + + + + + + +
FieldDescription
selectorType [Required]
+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.

+
updateStrategy
+ServiceUpdateStrategy +		 +

UpdateStrategy describes how the service differences should be reconciled

+
serviceTemplate [Required]
+ServiceTemplateSpec +		 +

ServiceTemplate is the template specification for the service.

+
+ +
+ +## ManagedServices + +**Appears in:** + +- [ManagedConfiguration](#postgresql-k8s-enterprisedb-io-v1-ManagedConfiguration) + +

ManagedServices represents the services managed by the cluster.

+ + + + + + + + + + + +
FieldDescription
disabledDefaultServices
+[]ServiceSelectorType +		 +

DisabledDefaultServices is a list of service types that are disabled by default. +Valid values are "r", and "ro", representing read, and read-only services.

+
additional
+[]ManagedService +		 +

Additional is a list of additional managed services specified by the user.

+
+ +
+ +## Metadata + +**Appears in:** + +- [PodTemplateSpec](#postgresql-k8s-enterprisedb-io-v1-PodTemplateSpec) + +- [ServiceAccountTemplate](#postgresql-k8s-enterprisedb-io-v1-ServiceAccountTemplate) + +- [ServiceTemplateSpec](#postgresql-k8s-enterprisedb-io-v1-ServiceTemplateSpec) + +

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.

+ + + + + + + + + + + + + + +
FieldDescription
name
+string +		 +

The name of the resource. Only supported for certain types

+
labels
+map[string]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: http://kubernetes.io/docs/user-guide/labels

+
annotations
+map[string]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: http://kubernetes.io/docs/user-guide/annotations

+
+ +
+ +## MonitoringConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

MonitoringConfiguration is the type containing all the monitoring +configuration for a certain cluster

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
disableDefaultQueries
+bool +		 +

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.

+
customQueriesConfigMap
+[]github.com/cloudnative-pg/machinery/pkg/api.ConfigMapKeySelector +		 +

The list of config maps containing the custom queries

+
customQueriesSecret
+[]github.com/cloudnative-pg/machinery/pkg/api.SecretKeySelector +		 +

The list of secrets containing the custom queries

+
enablePodMonitor
+bool +		 +

Enable or disable the PodMonitor

+
tls
+ClusterMonitoringTLSConfiguration +		 +

Configure TLS communication for the metrics endpoint. +Changing tls.enabled option will force a rollout of all instances.

+
podMonitorMetricRelabelings
+[]github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1.RelabelConfig +		 +

The list of metric relabelings for the PodMonitor. Applied to samples before ingestion.

+
podMonitorRelabelings
+[]github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1.RelabelConfig +		 +

The list of relabelings for the PodMonitor. Applied to samples before scraping.

+
+ +
+ +## NodeMaintenanceWindow + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

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.

+ + + + + + + + + + + +
FieldDescription
reusePVC
+bool +		 +

Reuse the existing PVC (wait for the node to come +up again) or not (recreate it elsewhere - when instances >1)

+
inProgress
+bool +		 +

Is there a node maintenance activity in progress?

+
+ +
+ +## OnlineConfiguration + +**Appears in:** + +- [BackupSpec](#postgresql-k8s-enterprisedb-io-v1-BackupSpec) + +- [ScheduledBackupSpec](#postgresql-k8s-enterprisedb-io-v1-ScheduledBackupSpec) + +- [VolumeSnapshotConfiguration](#postgresql-k8s-enterprisedb-io-v1-VolumeSnapshotConfiguration) + +

OnlineConfiguration contains the configuration parameters for the online volume snapshot

+ + + + + + + + + + + +
FieldDescription
waitForArchive
+bool +		 +

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.

+
immediateCheckpoint
+bool +		 +

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.

+
+ +
+ +## PasswordState + +**Appears in:** + +- [ManagedRoles](#postgresql-k8s-enterprisedb-io-v1-ManagedRoles) + +

PasswordState represents the state of the password of a managed RoleConfiguration

+ + + + + + + + + + + +
FieldDescription
transactionID
+int64 +		 +

the last transaction ID to affect the role definition in PostgreSQL

+
resourceVersion
+string +		 +

the resource version of the password secret

+
+ +
+ +## PgBouncerIntegrationStatus + +**Appears in:** + +- [PoolerIntegrations](#postgresql-k8s-enterprisedb-io-v1-PoolerIntegrations) + +

PgBouncerIntegrationStatus encapsulates the needed integration for the pgbouncer poolers referencing the cluster

+ + + + + + + + +
FieldDescription
secrets
+[]string +		 + No description provided.
+ +
+ +## PgBouncerPoolMode + +(Alias of `string`) + +**Appears in:** + +- [PgBouncerSpec](#postgresql-k8s-enterprisedb-io-v1-PgBouncerSpec) + +

PgBouncerPoolMode is the mode of PgBouncer

+ +
+ +## PgBouncerSecrets + +**Appears in:** + +- [PoolerSecrets](#postgresql-k8s-enterprisedb-io-v1-PoolerSecrets) + +

PgBouncerSecrets contains the versions of the secrets used +by pgbouncer

+ + + + + + + + +
FieldDescription
authQuery
+SecretVersion +		 +

The auth query secret version

+
+ +
+ +## PgBouncerSpec + +**Appears in:** + +- [PoolerSpec](#postgresql-k8s-enterprisedb-io-v1-PoolerSpec) + +

PgBouncerSpec defines how to configure PgBouncer

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
poolMode
+PgBouncerPoolMode +		 +

The pool mode. Default: session.

+
authQuerySecret
+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.

+
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
+map[string]string +		 +

Additional parameters to be passed to PgBouncer - please check +the CNP documentation for a list of options you can configure

+
pg_hba
+[]string +		 +

PostgreSQL Host Based Authentication rules (lines to be appended +to the pg_hba.conf file)

+
paused
+bool +		 +

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.

+
+ +
+ +## PluginConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +- [ExternalCluster](#postgresql-k8s-enterprisedb-io-v1-ExternalCluster) + +

PluginConfiguration specifies a plugin that need to be loaded for this +cluster to be reconciled

+ + + + + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

Name is the plugin name

+
enabled
+bool +		 +

Enabled is true if this plugin will be used

+
isWALArchiver
+bool +		 +

Only one plugin can be declared as WALArchiver. +Cannot be active if ".spec.backup.barmanObjectStore" configuration is present.

+
parameters
+map[string]string +		 +

Parameters is the configuration of the plugin

+
+ +
+ +## PluginStatus + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

PluginStatus is the status of a loaded plugin

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

Name is the name of the plugin

+
version [Required]
+string +		 +

Version is the version of the plugin loaded by the +latest reconciliation loop

+
capabilities
+[]string +		 +

Capabilities are the list of capabilities of the +plugin

+
operatorCapabilities
+[]string +		 +

OperatorCapabilities are the list of capabilities of the +plugin regarding the reconciler

+
walCapabilities
+[]string +		 +

WALCapabilities are the list of capabilities of the +plugin regarding the WAL management

+
backupCapabilities
+[]string +		 +

BackupCapabilities are the list of capabilities of the +plugin regarding the Backup management

+
restoreJobHookCapabilities
+[]string +		 +

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

+
+ +
+ +## PodTemplateSpec + +**Appears in:** + +- [PoolerSpec](#postgresql-k8s-enterprisedb-io-v1-PoolerSpec) + +

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: +https://github.com/kubernetes-sigs/controller-tools/issues/385 +https://github.com/kubernetes-sigs/controller-tools/issues/448 +https://github.com/prometheus-operator/prometheus-operator/issues/3041

+ + + + + + + + + + + +
FieldDescription
metadata
+Metadata +		 +

Standard object's metadata. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

+
spec
+core/v1.PodSpec +		 +

Specification of the desired behavior of the pod. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## PodTopologyLabels + +(Alias of `map[string]string`) + +**Appears in:** + +- [Topology](#postgresql-k8s-enterprisedb-io-v1-Topology) + +

PodTopologyLabels represent the topology of a Pod. map[labelName]labelValue

+ +
+ +## PoolerIntegrations + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

PoolerIntegrations encapsulates the needed integration for the poolers referencing the cluster

+ + + + + + + + +
FieldDescription
pgBouncerIntegration
+PgBouncerIntegrationStatus +		 + No description provided.
+ +
+ +## PoolerMonitoringConfiguration + +**Appears in:** + +- [PoolerSpec](#postgresql-k8s-enterprisedb-io-v1-PoolerSpec) + +

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.

+ + + + + + + + + + + + + + +
FieldDescription
enablePodMonitor
+bool +		 +

Enable or disable the PodMonitor

+
podMonitorMetricRelabelings
+[]github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1.RelabelConfig +		 +

The list of metric relabelings for the PodMonitor. Applied to samples before ingestion.

+
podMonitorRelabelings
+[]github.com/prometheus-operator/prometheus-operator/pkg/apis/monitoring/v1.RelabelConfig +		 +

The list of relabelings for the PodMonitor. Applied to samples before scraping.

+
+ +
+ +## PoolerSecrets + +**Appears in:** + +- [PoolerStatus](#postgresql-k8s-enterprisedb-io-v1-PoolerStatus) + +

PoolerSecrets contains the versions of all the secrets used

+ + + + + + + + + + + + + + + + + +
FieldDescription
serverTLS
+SecretVersion +		 +

The server TLS secret version

+
serverCA
+SecretVersion +		 +

The server CA secret version

+
clientCA
+SecretVersion +		 +

The client CA secret version

+
pgBouncerSecrets
+PgBouncerSecrets +		 +

The version of the secrets used by PgBouncer

+
+ +
+ +## PoolerSpec + +**Appears in:** + +- [Pooler](#postgresql-k8s-enterprisedb-io-v1-Pooler) + +

PoolerSpec defines the desired state of Pooler

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
cluster [Required]
+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.

+
type
+PoolerType +		 +

Type of service to forward traffic to. Default: rw.

+
instances
+int32 +		 +

The number of replicas we want. Default: 1.

+
template
+PodTemplateSpec +		 +

The template of the Pod to be created

+
pgbouncer [Required]
+PgBouncerSpec +		 +

The PgBouncer configuration

+
deploymentStrategy
+apps/v1.DeploymentStrategy +		 +

The deployment strategy to use for pgbouncer to replace existing pods with new ones

+
monitoring
+PoolerMonitoringConfiguration +		 +

The configuration of the monitoring infrastructure of this pooler.

+
serviceTemplate
+ServiceTemplateSpec +		 +

Template for the Service to be created

+
+ +
+ +## PoolerStatus + +**Appears in:** + +- [Pooler](#postgresql-k8s-enterprisedb-io-v1-Pooler) + +

PoolerStatus defines the observed state of Pooler

+ + + + + + + + + + + +
FieldDescription
secrets
+PoolerSecrets +		 +

The resource version of the config object

+
instances
+int32 +		 +

The number of pods trying to be scheduled

+
+ +
+ +## PoolerType + +(Alias of `string`) + +**Appears in:** + +- [PoolerSpec](#postgresql-k8s-enterprisedb-io-v1-PoolerSpec) + +

PoolerType is the type of the connection pool, meaning the service +we are targeting. Allowed values are rw and ro.

+ +
+ +## PostgresConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

PostgresConfiguration defines the PostgreSQL configuration

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
parameters
+map[string]string +		 +

PostgreSQL configuration options (postgresql.conf)

+
synchronous
+SynchronousReplicaConfiguration +		 +

Configuration of the PostgreSQL synchronous replication feature

+
pg_hba
+[]string +		 +

PostgreSQL Host Based Authentication rules (lines to be appended +to the pg_hba.conf file)

+
pg_ident
+[]string +		 +

PostgreSQL User Name Maps rules (lines to be appended +to the pg_ident.conf file)

+
epas
+EPASConfiguration +		 +

EDB Postgres Advanced Server specific configurations

+
syncReplicaElectionConstraint
+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 +		 +

Lists of shared preload libraries to add to the default ones

+
ldap
+LDAPConfig +		 +

Options to specify LDAP configuration

+
promotionTimeout
+int32 +		 +

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
+bool +		 +

If this parameter is true, the user will be able to invoke ALTER SYSTEM +on this EDB Postgres for Kubernetes Cluster. +This should only be used for debugging and troubleshooting. +Defaults to false.

+
+ +
+ +## PrimaryUpdateMethod + +(Alias of `string`) + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

PrimaryUpdateMethod contains the method to use when upgrading +the primary server of the cluster as part of rolling updates

+ +
+ +## PrimaryUpdateStrategy + +(Alias of `string`) + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

PrimaryUpdateStrategy contains the strategy to follow when upgrading +the primary server of the cluster as part of rolling updates

+ +
+ +## Probe + +**Appears in:** + +- [ProbeWithStrategy](#postgresql-k8s-enterprisedb-io-v1-ProbeWithStrategy) + +- [ProbesConfiguration](#postgresql-k8s-enterprisedb-io-v1-ProbesConfiguration) + +

Probe describes a health check to be performed against a container to determine whether it is +alive or ready to receive traffic.

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
initialDelaySeconds
+int32 +		 +

Number of seconds after the container has started before liveness probes are initiated. +More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes

+
timeoutSeconds
+int32 +		 +

Number of seconds after which the probe times out. +Defaults to 1 second. Minimum value is 1. +More info: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle#container-probes

+
periodSeconds
+int32 +		 +

How often (in seconds) to perform the probe. +Default to 10 seconds. Minimum value is 1.

+
successThreshold
+int32 +		 +

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
+int32 +		 +

Minimum consecutive failures for the probe to be considered failed after having succeeded. +Defaults to 3. Minimum value is 1.

+
terminationGracePeriodSeconds
+int64 +		 +

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 + +(Alias of `string`) + +**Appears in:** + +- [ProbeWithStrategy](#postgresql-k8s-enterprisedb-io-v1-ProbeWithStrategy) + +

ProbeStrategyType is the type of the strategy used to declare a PostgreSQL instance +ready

+ +
+ +## ProbeWithStrategy + +**Appears in:** + +- [ProbesConfiguration](#postgresql-k8s-enterprisedb-io-v1-ProbesConfiguration) + +

ProbeWithStrategy is the configuration of the startup probe

+ + + + + + + + + + + + + + +
FieldDescription
Probe
+Probe +		(Members of Probe are embedded into this type.) +

Probe is the standard probe configuration

+
type
+ProbeStrategyType +		 +

The probe strategy

+
maximumLag
+k8s.io/apimachinery/pkg/api/resource.Quantity +		 +

Lag limit. Used only for streaming strategy

+
+ +
+ +## ProbesConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

ProbesConfiguration represent the configuration for the probes +to be injected in the PostgreSQL Pods

+ + + + + + + + + + + + + + +
FieldDescription
startup [Required]
+ProbeWithStrategy +		 +

The startup probe configuration

+
liveness [Required]
+Probe +		 +

The liveness probe configuration

+
readiness [Required]
+ProbeWithStrategy +		 +

The readiness probe configuration

+
+ +
+ +## PublicationReclaimPolicy + +(Alias of `string`) + +**Appears in:** + +- [PublicationSpec](#postgresql-k8s-enterprisedb-io-v1-PublicationSpec) + +

PublicationReclaimPolicy defines a policy for end-of-life maintenance of Publications.

+ +
+ +## PublicationSpec + +**Appears in:** + +- [Publication](#postgresql-k8s-enterprisedb-io-v1-Publication) + +

PublicationSpec defines the desired state of Publication

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
cluster [Required]
+core/v1.LocalObjectReference +		 +

The name of the PostgreSQL cluster that identifies the "publisher"

+
name [Required]
+string +		 +

The name of the publication inside PostgreSQL

+
dbname [Required]
+string +		 +

The name of the database where the publication will be installed in +the "publisher" cluster

+
parameters
+map[string]string +		 +

Publication parameters part of the WITH clause as expected by +PostgreSQL CREATE PUBLICATION command

+
target [Required]
+PublicationTarget +		 +

Target of the publication as expected by PostgreSQL CREATE PUBLICATION command

+
publicationReclaimPolicy
+PublicationReclaimPolicy +		 +

The policy for end-of-life maintenance of this publication

+
+ +
+ +## PublicationStatus + +**Appears in:** + +- [Publication](#postgresql-k8s-enterprisedb-io-v1-Publication) + +

PublicationStatus defines the observed state of Publication

+ + + + + + + + + + + + + + +
FieldDescription
observedGeneration
+int64 +		 +

A sequence number representing the latest +desired state that was synchronized

+
applied
+bool +		 +

Applied is true if the publication was reconciled correctly

+
message
+string +		 +

Message is the reconciliation output message

+
+ +
+ +## PublicationTarget + +**Appears in:** + +- [PublicationSpec](#postgresql-k8s-enterprisedb-io-v1-PublicationSpec) + +

PublicationTarget is what this publication should publish

+ + + + + + + + + + + +
FieldDescription
allTables
+bool +		 +

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 +		 +

Just the following schema objects

+
+ +
+ +## PublicationTargetObject + +**Appears in:** + +- [PublicationTarget](#postgresql-k8s-enterprisedb-io-v1-PublicationTarget) + +

PublicationTargetObject is an object to publish

+ + + + + + + + + + + +
FieldDescription
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 +		 +

Specifies a list of tables to add to the publication. Corresponding +to FOR TABLE in PostgreSQL.

+
+ +
+ +## PublicationTargetTable + +**Appears in:** + +- [PublicationTargetObject](#postgresql-k8s-enterprisedb-io-v1-PublicationTargetObject) + +

PublicationTargetTable is a table to publish

+ + + + + + + + + + + + + + + + + +
FieldDescription
only
+bool +		 +

Whether to limit to the table only or include all its descendants

+
name [Required]
+string +		 +

The table name

+
schema
+string +		 +

The schema name

+
columns
+[]string +		 +

The columns to publish

+
+ +
+ +## RecoveryTarget + +**Appears in:** + +- [BootstrapRecovery](#postgresql-k8s-enterprisedb-io-v1-BootstrapRecovery) + +

RecoveryTarget allows to configure the moment where the recovery process +will stop. All the target options except TargetTLI are mutually exclusive.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
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 the RFC3339 standard

+
targetImmediate
+bool +		 +

End recovery as soon as a consistent state is reached

+
exclusive
+bool +		 +

Set the target to be exclusive. If omitted, defaults to false, so that +in Postgres, recovery_target_inclusive will be true

+
+ +
+ +## ReplicaClusterConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

ReplicaClusterConfiguration encapsulates the configuration of a replica +cluster

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
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 [Required]
+string +		 +

The name of the external cluster which is the replication origin

+
enabled
+bool +		 +

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
+meta/v1.Duration +		 +

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 + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

ReplicationSlotsConfiguration encapsulates the configuration +of replication slots

+ + + + + + + + + + + + + + +
FieldDescription
highAvailability
+ReplicationSlotsHAConfiguration +		 +

Replication slots for high availability configuration

+
updateInterval
+int +		 +

Standby will update the status of the local replication slots +every updateInterval seconds (default 30).

+
synchronizeReplicas
+SynchronizeReplicasConfiguration +		 +

Configures the synchronization of the user defined physical replication slots

+
+ +
+ +## ReplicationSlotsHAConfiguration + +**Appears in:** + +- [ReplicationSlotsConfiguration](#postgresql-k8s-enterprisedb-io-v1-ReplicationSlotsConfiguration) + +

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.

+ + + + + + + + + + + +
FieldDescription
enabled
+bool +		 +

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_.

+
+ +
+ +## RoleConfiguration + +**Appears in:** + +- [ManagedConfiguration](#postgresql-k8s-enterprisedb-io-v1-ManagedConfiguration) + +

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: https://www.postgresql.org/docs/current/sql-createrole.html

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

Name of the role

+
comment
+string +		 +

Description of the role

+
ensure
+EnsureOption +		 +

Ensure the role is present or absent - defaults to "present"

+
passwordSecret
+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

+
connectionLimit
+int64 +		 +

If the role can log in, this specifies how many concurrent +connections the role can make. -1 (the default) means no limit.

+
validUntil
+meta/v1.Time +		 +

Date and time after which the role's password is no longer valid. +When omitted, the password will never expire (default).

+
inRoles
+[]string +		 +

List of one or more existing roles to which this role will be +immediately added as a new member. Default empty.

+
inherit
+bool +		 +

Whether a role "inherits" the privileges of roles it is a member of. +Defaults is true.

+
disablePassword
+bool +		 +

DisablePassword indicates that a role's password should be set to NULL in Postgres

+
superuser
+bool +		 +

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
+bool +		 +

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
+bool +		 +

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
+bool +		 +

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
+bool +		 +

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
+bool +		 +

Whether a role bypasses every row-level security (RLS) policy. +Default is false.

+
+ +
+ +## SQLRefs + +**Appears in:** + +- [BootstrapInitDB](#postgresql-k8s-enterprisedb-io-v1-BootstrapInitDB) + +

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.

+ + + + + + + + + + + +
FieldDescription
secretRefs
+[]github.com/cloudnative-pg/machinery/pkg/api.SecretKeySelector +		 +

SecretRefs holds a list of references to Secrets

+
configMapRefs
+[]github.com/cloudnative-pg/machinery/pkg/api.ConfigMapKeySelector +		 +

ConfigMapRefs holds a list of references to ConfigMaps

+
+ +
+ +## ScheduledBackupSpec + +**Appears in:** + +- [ScheduledBackup](#postgresql-k8s-enterprisedb-io-v1-ScheduledBackup) + +

ScheduledBackupSpec defines the desired state of ScheduledBackup

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
suspend
+bool +		 +

If this backup is suspended or not

+
immediate
+bool +		 +

If the first backup has to be immediately start after creation or not

+
schedule [Required]
+string +		 +

The schedule does not follow the same format used in Kubernetes CronJobs +as it includes an additional seconds specifier, +see https://pkg.go.dev/github.com/robfig/cron#hdr-CRON_Expression_Format

+
cluster [Required]
+github.com/cloudnative-pg/machinery/pkg/api.LocalObjectReference +		 +

The cluster to backup

+
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
    • +
+
target
+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.

+
method
+BackupMethod +		 +

The backup method to be used, possible options are barmanObjectStore, +volumeSnapshot or plugin. Defaults to: barmanObjectStore.

+
pluginConfiguration
+BackupPluginConfiguration +		 +

Configuration parameters passed to the plugin managing this backup

+
online
+bool +		 +

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 +		 +

Configuration parameters to control the online/hot backup with volume snapshots +Overrides the default settings specified in the cluster '.backup.volumeSnapshot.onlineConfiguration' stanza

+
+ +
+ +## ScheduledBackupStatus + +**Appears in:** + +- [ScheduledBackup](#postgresql-k8s-enterprisedb-io-v1-ScheduledBackup) + +

ScheduledBackupStatus defines the observed state of ScheduledBackup

+ + + + + + + + + + + + + + +
FieldDescription
lastCheckTime
+meta/v1.Time +		 +

The latest time the schedule

+
lastScheduleTime
+meta/v1.Time +		 +

Information when was the last time that backup was successfully scheduled.

+
nextScheduleTime
+meta/v1.Time +		 +

Next time we will run a backup

+
+ +
+ +## SchemaSpec + +**Appears in:** + +- [DatabaseSpec](#postgresql-k8s-enterprisedb-io-v1-DatabaseSpec) + +

SchemaSpec configures a schema in a database

+ + + + + + + + + + + +
FieldDescription
DatabaseObjectSpec
+DatabaseObjectSpec +		(Members of DatabaseObjectSpec are embedded into this type.) +

Common fields

+
owner [Required]
+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.

+
+ +
+ +## SecretVersion + +**Appears in:** + +- [PgBouncerSecrets](#postgresql-k8s-enterprisedb-io-v1-PgBouncerSecrets) + +- [PoolerSecrets](#postgresql-k8s-enterprisedb-io-v1-PoolerSecrets) + +

SecretVersion contains a secret name and its ResourceVersion

+ + + + + + + + + + + +
FieldDescription
name
+string +		 +

The name of the secret

+
version
+string +		 +

The ResourceVersion of the secret

+
+ +
+ +## SecretsResourceVersion + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

SecretsResourceVersion is the resource versions of the secrets +managed by the operator

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
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
+map[string]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
+map[string]string +		 +

The resource versions of the external cluster secrets

+
metrics
+map[string]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

+
+ +
+ +## ServiceAccountTemplate + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

ServiceAccountTemplate contains the template needed to generate the service accounts

+ + + + + + + + +
FieldDescription
metadata [Required]
+Metadata +		 +

Metadata are the metadata to be used for the generated +service account

+
+ +
+ +## ServiceSelectorType + +(Alias of `string`) + +**Appears in:** + +- [ManagedService](#postgresql-k8s-enterprisedb-io-v1-ManagedService) + +- [ManagedServices](#postgresql-k8s-enterprisedb-io-v1-ManagedServices) + +

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

+ +
+ +## ServiceTemplateSpec + +**Appears in:** + +- [ManagedService](#postgresql-k8s-enterprisedb-io-v1-ManagedService) + +- [PoolerSpec](#postgresql-k8s-enterprisedb-io-v1-PoolerSpec) + +

ServiceTemplateSpec is a structure allowing the user to set +a template for Service generation.

+ + + + + + + + + + + +
FieldDescription
metadata
+Metadata +		 +

Standard object's metadata. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

+
spec
+core/v1.ServiceSpec +		 +

Specification of the desired behavior of the service. +More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

+
+ +
+ +## ServiceUpdateStrategy + +(Alias of `string`) + +**Appears in:** + +- [ManagedService](#postgresql-k8s-enterprisedb-io-v1-ManagedService) + +

ServiceUpdateStrategy describes how the changes to the managed service should be handled

+ +
+ +## SnapshotOwnerReference + +(Alias of `string`) + +**Appears in:** + +- [VolumeSnapshotConfiguration](#postgresql-k8s-enterprisedb-io-v1-VolumeSnapshotConfiguration) + +

SnapshotOwnerReference defines the reference type for the owner of the snapshot. +This specifies which owner the processed resources should relate to.

+ +
+ +## SnapshotType + +(Alias of `string`) + +**Appears in:** + +- [Import](#postgresql-k8s-enterprisedb-io-v1-Import) + +

SnapshotType is a type of allowed import

+ +
+ +## StorageConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +- [TablespaceConfiguration](#postgresql-k8s-enterprisedb-io-v1-TablespaceConfiguration) + +

StorageConfiguration is the configuration used to create and reconcile PVCs, +usable for WAL volumes, PGDATA volumes, or tablespaces

+ + + + + + + + + + + + + + + + + +
FieldDescription
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
+bool +		 +

Resize existent PVCs, defaults to true

+
pvcTemplate
+core/v1.PersistentVolumeClaimSpec +		 +

Template to be used to generate the Persistent Volume Claim

+
+ +
+ +## SubscriptionReclaimPolicy + +(Alias of `string`) + +**Appears in:** + +- [SubscriptionSpec](#postgresql-k8s-enterprisedb-io-v1-SubscriptionSpec) + +

SubscriptionReclaimPolicy describes a policy for end-of-life maintenance of Subscriptions.

+ +
+ +## SubscriptionSpec + +**Appears in:** + +- [Subscription](#postgresql-k8s-enterprisedb-io-v1-Subscription) + +

SubscriptionSpec defines the desired state of Subscription

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
cluster [Required]
+core/v1.LocalObjectReference +		 +

The name of the PostgreSQL cluster that identifies the "subscriber"

+
name [Required]
+string +		 +

The name of the subscription inside PostgreSQL

+
dbname [Required]
+string +		 +

The name of the database where the publication will be installed in +the "subscriber" cluster

+
parameters
+map[string]string +		 +

Subscription parameters part of the WITH clause as expected by +PostgreSQL CREATE SUBSCRIPTION command

+
publicationName [Required]
+string +		 +

The name of the publication inside the PostgreSQL database in the +"publisher"

+
publicationDBName
+string +		 +

The name of the database containing the publication on the external +cluster. Defaults to the one in the external cluster definition.

+
externalClusterName [Required]
+string +		 +

The name of the external cluster with the publication ("publisher")

+
subscriptionReclaimPolicy
+SubscriptionReclaimPolicy +		 +

The policy for end-of-life maintenance of this subscription

+
+ +
+ +## SubscriptionStatus + +**Appears in:** + +- [Subscription](#postgresql-k8s-enterprisedb-io-v1-Subscription) + +

SubscriptionStatus defines the observed state of Subscription

+ + + + + + + + + + + + + + +
FieldDescription
observedGeneration
+int64 +		 +

A sequence number representing the latest +desired state that was synchronized

+
applied
+bool +		 +

Applied is true if the subscription was reconciled correctly

+
message
+string +		 +

Message is the reconciliation output message

+
+ +
+ +## SwitchReplicaClusterStatus + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

SwitchReplicaClusterStatus contains all the statuses regarding the switch of a cluster to a replica cluster

+ + + + + + + + +
FieldDescription
inProgress
+bool +		 +

InProgress indicates if there is an ongoing procedure of switching a cluster to a replica cluster.

+
+ +
+ +## SyncReplicaElectionConstraints + +**Appears in:** + +- [PostgresConfiguration](#postgresql-k8s-enterprisedb-io-v1-PostgresConfiguration) + +

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.

+ + + + + + + + + + + +
FieldDescription
nodeLabelsAntiAffinity
+[]string +		 +

A list of node labels values to extract and compare to evaluate if the pods reside in the same topology or not

+
enabled [Required]
+bool +		 +

This flag enables the constraints for sync replicas

+
+ +
+ +## SynchronizeReplicasConfiguration + +**Appears in:** + +- [ReplicationSlotsConfiguration](#postgresql-k8s-enterprisedb-io-v1-ReplicationSlotsConfiguration) + +

SynchronizeReplicasConfiguration contains the configuration for the synchronization of user defined +physical replication slots

+ + + + + + + + + + + +
FieldDescription
enabled [Required]
+bool +		 +

When set to true, every replication slot that is on the primary is synchronized on each standby

+
excludePatterns
+[]string +		 +

List of regular expression patterns to match the names of replication slots to be excluded (by default empty)

+
+ +
+ +## SynchronousReplicaConfiguration + +**Appears in:** + +- [PostgresConfiguration](#postgresql-k8s-enterprisedb-io-v1-PostgresConfiguration) + +

SynchronousReplicaConfiguration contains the configuration of the +PostgreSQL synchronous replication feature. +Important: at this moment, also .spec.minSyncReplicas and .spec.maxSyncReplicas +need to be considered.

+ + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
method [Required]
+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.

+
number [Required]
+int +		 +

Specifies the number of synchronous standby servers that +transactions must wait for responses from.

+
maxStandbyNamesFromCluster
+int +		 +

Specifies the maximum number of local cluster pods that can be +automatically included in the synchronous_standby_names option in +PostgreSQL.

+
standbyNamesPre
+[]string +		 +

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 +		 +

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 +		 +

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).

+
+ +
+ +## SynchronousReplicaConfigurationMethod + +(Alias of `string`) + +**Appears in:** + +- [SynchronousReplicaConfiguration](#postgresql-k8s-enterprisedb-io-v1-SynchronousReplicaConfiguration) + +

SynchronousReplicaConfigurationMethod configures whether to use +quorum based replication or a priority list

+ +
+ +## TDEConfiguration + +**Appears in:** + +- [EPASConfiguration](#postgresql-k8s-enterprisedb-io-v1-EPASConfiguration) + +

TDEConfiguration contains the Transparent Data Encryption configuration

+ + + + + + + + + + + + + + + + + + + + +
FieldDescription
enabled
+bool +		 +

True if we want to have TDE enabled

+
secretKeyRef
+core/v1.SecretKeySelector +		 +

Reference to the secret that contains the encryption key

+
wrapCommand
+core/v1.SecretKeySelector +		 +

WrapCommand is the encrypt command provided by the user

+
unwrapCommand
+core/v1.SecretKeySelector +		 +

UnwrapCommand is the decryption command provided by the user

+
passphraseCommand
+core/v1.SecretKeySelector +		 +

PassphraseCommand is the command executed to get the passphrase that will be +passed to the OpenSSL command to encrypt and decrypt

+
+ +
+ +## TablespaceConfiguration + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

TablespaceConfiguration is the configuration of a tablespace, and includes +the storage specification for the tablespace

+ + + + + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

The name of the tablespace

+
storage [Required]
+StorageConfiguration +		 +

The storage configuration for the tablespace

+
owner
+DatabaseRoleRef +		 +

Owner is the PostgreSQL user owning the tablespace

+
temporary
+bool +		 +

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.

+
+ +
+ +## TablespaceState + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

TablespaceState represents the state of a tablespace in a cluster

+ + + + + + + + + + + + + + + + + +
FieldDescription
name [Required]
+string +		 +

Name is the name of the tablespace

+
owner
+string +		 +

Owner is the PostgreSQL user owning the tablespace

+
state [Required]
+TablespaceStatus +		 +

State is the latest reconciliation state

+
error
+string +		 +

Error is the reconciliation error, if any

+
+ +
+ +## TablespaceStatus + +(Alias of `string`) + +**Appears in:** + +- [TablespaceState](#postgresql-k8s-enterprisedb-io-v1-TablespaceState) + +

TablespaceStatus represents the status of a tablespace in the cluster

+ +
+ +## Topology + +**Appears in:** + +- [ClusterStatus](#postgresql-k8s-enterprisedb-io-v1-ClusterStatus) + +

Topology contains the cluster topology

+ + + + + + + + + + + + + + +
FieldDescription
instances
+map[PodName]PodTopologyLabels +		 +

Instances contains the pod topology of the instances

+
nodesUsed
+int32 +		 +

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
+bool +		 +

SuccessfullyExtracted indicates if the topology data was extract. It is useful to enact fallback behaviors +in synchronous replica election in case of failures

+
+ +
+ +## VolumeSnapshotConfiguration + +**Appears in:** + +- [BackupConfiguration](#postgresql-k8s-enterprisedb-io-v1-BackupConfiguration) + +

VolumeSnapshotConfiguration represents the configuration for the execution of snapshot backups.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
labels
+map[string]string +		 +

Labels are key-value pairs that will be added to .metadata.labels snapshot resources.

+
annotations
+map[string]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
+map[string]string +		 +

TablespaceClassName specifies the Snapshot Class to be used for the tablespaces. +defaults to the PGDATA Snapshot Class, if set

+
snapshotOwnerReference
+SnapshotOwnerReference +		 +

SnapshotOwnerReference indicates the type of owner reference the snapshot should have

+
online
+bool +		 +

Whether the default type of backup with volume snapshots is +online/hot (true, default) or offline/cold (false)

+
onlineConfiguration
+OnlineConfiguration +		 +

Configuration parameters to control the online/hot backup with volume snapshots

+
diff --git a/product_docs/docs/postgres_for_kubernetes/1/postgres_upgrades.mdx b/product_docs/docs/postgres_for_kubernetes/1/postgres_upgrades.mdx new file mode 100644 index 00000000000..5b245ee8d43 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/postgres_upgrades.mdx @@ -0,0 +1,208 @@ +--- +title: 'PostgreSQL Upgrades' +originalFilePath: 'src/postgres_upgrades.md' +--- + + + +PostgreSQL upgrades fall into two categories: + +- [Minor version upgrades](#minor-version-upgrades) (e.g., from 17.0 to 17.1) +- [Major version upgrades](#major-version-upgrades) (e.g., from 16.x to 17.0) + +## Minor Version Upgrades + +PostgreSQL version numbers follow a `major.minor` format. For instance, in +version 17.1: + +- `17` is the major version +- `1` is the minor version + +Minor releases are fully compatible with earlier and later minor releases of +the same major version. They include bug fixes and security updates but do not +introduce changes to the internal storage format. +For example, PostgreSQL 17.1 is compatible with 17.0 and 17.4. + +### Upgrading a Minor Version in EDB Postgres for Kubernetes + +To upgrade to a newer minor version, simply update the PostgreSQL container +image reference in your cluster definition, either directly or via image catalogs. +EDB Postgres for Kubernetes will trigger a [rolling update of the cluster](rolling_update.md), +replacing each instance one by one, starting with the replicas. Once all +replicas have been updated, it will perform either a switchover or a restart of +the primary to complete the process. + +## Major Version Upgrades + +Major PostgreSQL releases introduce changes to the internal data storage +format, requiring a more structured upgrade process. + +EDB Postgres for Kubernetes supports three methods for performing major upgrades: + +1. [Logical dump/restore](database_import.md) – Blue/green deployment, offline. +2. [Native logical replication](logical_replication.md#example-of-live-migration-and-major-postgres-upgrade-with-logical-replication) – Blue/green deployment, online. +3. Physical with `pg_upgrade` – In-place upgrade, offline (covered in the + ["Offline In-Place Major Upgrades" section](#offline-in-place-major-upgrades) below). + +Each method has trade-offs in terms of downtime, complexity, and data volume +handling. The best approach depends on your upgrade strategy and operational +constraints. + +!!! Important + We strongly recommend testing all methods in a controlled environment + before proceeding with a production upgrade. + +## Offline In-Place Major Upgrades + +EDB Postgres for Kubernetes performs an **offline in-place major upgrade** when a new operand +container image with a higher PostgreSQL major version is declaratively +requested for a cluster. + +You can trigger the upgrade in one of two ways: + +- By updating the major version in the image tag via the `.spec.imageName` + option. +- Using an [image catalog](image_catalog.md) to manage version changes. + +For details on supported image tags, see +["Image Tag Requirements"](container_images.md#image-tag-requirements). + +!!! Warning + EDB Postgres for Kubernetes is not responsible for PostgreSQL extensions. You must ensure + that extensions in the source PostgreSQL image are compatible with those in the + target image and that upgrade paths are supported. Thoroughly test the upgrade + process in advance to avoid unexpected issues. + The [extensions management feature](declarative_database_management.md#managing-extensions-in-a-database) + can help manage extension upgrades declaratively. + +### Upgrade Process + +1. Shuts down all cluster pods to ensure data consistency. +2. Records the previous PostgreSQL version in the cluster’s status under + `.status.majorVersionUpgradeFromImage`. +3. Initiates a new upgrade job, which: + - Verifies that the binaries in the image and the data files align with a + major upgrade request. + - Creates new directories for `PGDATA`, and where applicable, WAL files and + tablespaces. + - Performs the upgrade using `pg_upgrade` with the `--link` option. + - Upon successful completion, replaces the original directories with their + upgraded counterparts. + +!!! Warning + During the upgrade process, the entire PostgreSQL cluster, including + replicas, is unavailable to applications. Ensure that your system can + tolerate this downtime before proceeding. + +!!! Warning + Performing an in-place upgrade is an exceptional operation that carries inherent + risks. It is strongly recommended to take a full backup of the cluster before + initiating the upgrade process. + +!!! Info + For detailed guidance on `pg_upgrade`, refer to the official + [PostgreSQL documentation](https://www.postgresql.org/docs/current/pgupgrade.html). + +### Post-Upgrade Actions + +If the upgrade is successful, EDB Postgres for Kubernetes: + +- Destroys the PVCs of replicas (if available). +- Scales up replicas as required. + +!!! Warning + Re-cloning replicas can be time-consuming, especially for very large + databases. Plan accordingly to accommodate potential delays. After completing + the upgrade, it is strongly recommended to take a full backup. Existing backup + data (namely base backups and WAL files) is only available for the previous + minor PostgreSQL release. + +!!! Warning + `pg_upgrade` doesn't transfer optimizer statistics. After the upgrade, you + may want to run `ANALYZE` on your databases to update them. + +If the upgrade fails, you must manually revert the major version change in the +cluster's configuration and delete the upgrade job, as EDB Postgres for Kubernetes cannot +automatically decide the rollback. + +!!! Important + This process **protects your existing database from data loss**, as no data + is modified during the upgrade. If the upgrade fails, a rollback is + usually possible, without having to perform a full recovery from a backup. + Ensure you monitor the process closely and take corrective action if needed. + +### Example: Performing a Major Upgrade + +Consider the following PostgreSQL cluster running version 16: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: cluster-example +spec: + imageName: quay.io/enterprisedb/postgresql:16-minimal-bookworm + instances: 3 + storage: + size: 1Gi +``` + +You can check the current PostgreSQL version using the following command: + +```sh +kubectl cnp psql cluster-example -- -qAt -c 'SELECT version()' +``` + +This will return output similar to: + +```console +PostgreSQL 16.x ... +``` + +To upgrade the cluster to version 17, update the `imageName` field by changing +the major version tag from `16` to `17`: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: cluster-example +spec: + imageName: quay.io/enterprisedb/postgresql:17-minimal-bookworm + instances: 3 + storage: + size: 1Gi +``` + +### Upgrade Process + +1. Cluster shutdown – All cluster pods are terminated to ensure a consistent + upgrade. +2. Upgrade job execution – A new job is created with the name of the primary + pod, appended with the suffix `-major-upgrade`. This job runs `pg_upgrade` + on the primary’s persistent volume group. +3. Post-upgrade steps: + - The PVC groups of the replicas (`cluster-example-2` and + `cluster-example-3`) are removed. + - The primary pod is restarted. + - Two new replicas (`cluster-example-4` and `cluster-example-5`) are + re-cloned from the upgraded primary. + +Once the upgrade is complete, you can verify the new major version by running +the same command: + +```sh +kubectl cnp psql cluster-example -- -qAt -c 'SELECT version()' +``` + +This should now return output similar to: + +```console +PostgreSQL 17.x ... +``` + +You can now update the statistics by running `ANALYZE` on the `app` database: + +```sh +kubectl cnp psql cluster-example -- app -c 'ANALYZE' +``` 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 db307c2dd53..3a8615ae698 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx @@ -3,6 +3,8 @@ title: 'PostgreSQL Configuration' originalFilePath: 'src/postgresql_conf.md' --- + + Users that are familiar with PostgreSQL are aware of the existence of the following three files to configure an instance: @@ -134,17 +136,28 @@ Since the fixed parameters are added at the end, they can't be overridden by the user via the YAML configuration. Those parameters are required for correct WAL archiving and replication. -### Replication settings +### Replication Settings -The `primary_conninfo`, `restore_command`, and `recovery_target_timeline` -parameters are managed automatically by the operator according to the state of -the instance in the cluster. +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 +instance is operating as a replica. ```text -primary_conninfo = 'host=cluster-example-rw user=postgres dbname=postgres' +primary_conninfo = 'host= user=postgres dbname=postgres' recovery_target_timeline = 'latest' ``` +The [`STANDBY_TCP_USER_TIMEOUT` operator configuration setting](operator_conf.md#available-options), +if specified, sets the `tcp_user_timeout` parameter on all standby instances +managed by the operator. + +The `tcp_user_timeout` parameter determines how long transmitted data can +remain unacknowledged before the TCP connection is forcibly closed. Adjusting +this value allows you to fine-tune the responsiveness of standby instances to +network disruptions. For more details, refer to the +[PostgreSQL documentation](https://www.postgresql.org/docs/current/runtime-config-connection.html#GUC-TCP-USER-TIMEOUT). + ### Log control settings The operator requires PostgreSQL to output its log in CSV format, and the @@ -219,6 +232,12 @@ SELECT datname FROM pg_database WHERE datallowconn !!! Note The above query also includes template databases like `template1`. +!!! 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 EDB Postgres for Kubernetes, and some functionalities might be deprecated. + #### Enabling `auto_explain` The [`auto_explain`](https://www.postgresql.org/docs/current/auto-explain.html) 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 6ebbec0d22b..80b803de0ef 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/preview_version.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/preview_version.mdx @@ -3,6 +3,8 @@ title: 'Preview Versions' originalFilePath: 'src/preview_version.md' --- + + EDB Postgres for Kubernetes candidate releases are pre-release versions made available for testing before the community issues a new generally available (GA) release. These versions are feature-frozen, meaning no new features are added, and are @@ -38,3 +40,9 @@ are not backwards compatible and could be removed entirely. There are currently no preview versions available. +The current preview version is **1.26.0-rc1**. + +For more information on the current preview version and how to test, please view the links below: + +- [Announcement](https://cloudnative-pg.io/releases/cloudnative-pg-1-26.0-rc1-released/) +- [Documentation](https://cloudnative-pg.io/documentation/preview/) diff --git a/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx b/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx index 52c77281de1..29429422164 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 EDB Postgres for Kubernetes on a local Kubernetes cluster using either [Kind](https://kind.sigs.k8s.io/) or diff --git a/product_docs/docs/postgres_for_kubernetes/1/recovery.mdx b/product_docs/docs/postgres_for_kubernetes/1/recovery.mdx index 090f8f1dfaf..de81013c318 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/recovery.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/recovery.mdx @@ -3,6 +3,14 @@ title: 'Recovery' originalFilePath: 'src/recovery.md' --- + + +!!! Warning + With the deprecation of native Barman Cloud support in EDB Postgres for Kubernetes in + favor of the Barman Cloud Plugin, this page—and the backup and recovery + documentation—may undergo changes before the official release of version + 1.26.0. + 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 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 51dd6a5e3b7..a4c24368098 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/replica_cluster.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/replica_cluster.mdx @@ -3,6 +3,14 @@ title: 'Replica clusters' originalFilePath: 'src/replica_cluster.md' --- + + +!!! Warning + With the deprecation of native Barman Cloud support in EDB Postgres for Kubernetes in + favor of the Barman Cloud Plugin, this page—and the backup and recovery + documentation—may undergo changes before the official release of version + 1.26.0. + A replica cluster is a EDB Postgres for Kubernetes `Cluster` resource designed to replicate data from another PostgreSQL instance, ideally also managed by EDB Postgres for Kubernetes. @@ -100,6 +108,8 @@ recovery. There are three main options: When configuring the external cluster, you have the following options: + + - **`barmanObjectStore` section**: - Enables use of the WAL archive, with EDB Postgres for Kubernetes automatically setting the `restore_command` in the designated primary instance. diff --git a/product_docs/docs/postgres_for_kubernetes/1/replication.mdx b/product_docs/docs/postgres_for_kubernetes/1/replication.mdx index 4618aa50d7c..7304c067bbb 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/replication.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/replication.mdx @@ -3,6 +3,8 @@ title: 'Replication' originalFilePath: 'src/replication.md' --- + + Physical replication is one of the strengths of PostgreSQL and one of the reasons why some of the largest organizations in the world have chosen it for the management of their data in business continuity contexts. Primarily used to @@ -397,7 +399,9 @@ number of standbys are available. 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. + once. However, EDB Postgres for Kubernetes 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). This setting balances data safety with availability, enabling applications to continue writing during temporary standby unavailability—hence, it’s also known 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 a516d7459ae..e91e1808e93 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/resource_management.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/resource_management.mdx @@ -3,6 +3,8 @@ title: 'Resource management' originalFilePath: 'src/resource_management.md' --- + + In a typical Kubernetes cluster, pods run with unlimited resources. By default, they might be allowed to use as much CPU and RAM as needed. 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 7268cc5eb0f..6c9c41ca1c9 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/rolling_update.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/rolling_update.mdx @@ -3,6 +3,8 @@ title: 'Rolling Updates' originalFilePath: 'src/rolling_update.md' --- + + The operator allows changing the PostgreSQL version used in a cluster while applications are 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 6015c1764ca..2a03ee73bef 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/samples.mdx @@ -3,6 +3,8 @@ title: 'Examples' originalFilePath: 'src/samples.md' --- + + The examples show configuration files for setting up your PostgreSQL cluster. diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-with-probes.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-with-probes.yaml new file mode 100644 index 00000000000..450fab88a4c --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-with-probes.yaml @@ -0,0 +1,16 @@ +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: cluster-example +spec: + instances: 3 + + probes: + startup: + type: streaming + maximumLag: 16Mi + failureThreshold: 30 + periodSeconds: 10 + + storage: + size: 1Gi diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example.yaml index 230b7b5fcc5..1e01b6ed3ef 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example.yaml @@ -4,6 +4,8 @@ metadata: name: cluster-example spec: instances: 3 - + imageName: quay.io/enterprisedb/postgresql:13 + storage: size: 1Gi + diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/k9s/plugins.yml b/product_docs/docs/postgres_for_kubernetes/1/samples/k9s/plugins.yml index 76974204e1b..2ab7984926a 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/k9s/plugins.yml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/k9s/plugins.yml @@ -26,7 +26,7 @@ plugins: background: false args: - -c - - "kubectl cnp backup $NAME -n $NAMESPACE --context \"$CONTEXT\" |& less -R" + - "kubectl cnp backup $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R" postgresql-operator-hibernate-status: shortCut: h description: Hibernate status @@ -36,7 +36,7 @@ plugins: background: false args: - -c - - "kubectl cnp hibernate status $NAME -n $NAMESPACE --context \"$CONTEXT\" |& less -R" + - "kubectl cnp hibernate status $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R" postgresql-operator-hibernate: shortCut: Shift-H description: Hibernate @@ -47,7 +47,7 @@ plugins: background: false args: - -c - - "kubectl cnp hibernate on $NAME -n $NAMESPACE --context \"$CONTEXT\" |& less -R" + - "kubectl cnp hibernate on $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R" postgresql-operator-hibernate-off: shortCut: Shift-H description: Wake up hibernated cluster in this namespace @@ -58,7 +58,7 @@ plugins: background: false args: - -c - - "kubectl cnp hibernate off $NAME -n $NAME --context \"$CONTEXT\" |& less -R" + - "kubectl cnp hibernate off $NAME -n $NAME --context \"$CONTEXT\" 2>&1 | less -R" postgresql-operator-logs: shortCut: l description: Logs @@ -89,7 +89,7 @@ plugins: background: false args: - -c - - "kubectl cnp reload $NAME -n $NAMESPACE --context \"$CONTEXT\" |& less -R" + - "kubectl cnp reload $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R" postgresql-operator-restart: shortCut: Shift-R description: Restart @@ -100,7 +100,7 @@ plugins: background: false args: - -c - - "kubectl cnp restart $NAME -n $NAMESPACE --context \"$CONTEXT\" |& less -R" + - "kubectl cnp restart $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R" postgresql-operator-status: shortCut: s description: Status @@ -110,7 +110,7 @@ plugins: background: false args: - -c - - "kubectl cnp status $NAME -n $NAMESPACE --context \"$CONTEXT\" |& less -R" + - "kubectl cnp status $NAME -n $NAMESPACE --context \"$CONTEXT\" 2>&1 | less -R" postgresql-operator-status-verbose: shortCut: Shift-S description: Status (verbose) @@ -120,4 +120,4 @@ plugins: background: false args: - -c - - "kubectl cnp status $NAME -n $NAMESPACE --context \"$CONTEXT\" --verbose |& less -R" + - "kubectl cnp status $NAME -n $NAMESPACE --context \"$CONTEXT\" --verbose 2>&1 | less -R" diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/monitoring/kube-stack-config.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/monitoring/kube-stack-config.yaml index 68c0885fbb3..58df3e420ae 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/monitoring/kube-stack-config.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/monitoring/kube-stack-config.yaml @@ -1,9 +1,6 @@ -# Default values for cnp-sandbox. -# This is a YAML-formatted file. -# Declare variables to be passed into your templates. # -# -# Copyright The CloudNativePG Contributors +# Copyright © contributors to EDB Postgres for Kubernetes, established as +# EDB Postgres for Kubernetes a Series of LF Projects, LLC. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -17,6 +14,8 @@ # See the License for the specific language governing permissions and # limitations under the License. # +# SPDX-License-Identifier: Apache-2.0 +# # -- here you can pass the whole values directly to the kube-prometheus-stack chart enabled: true 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 2982710ae19..f342616977b 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,15 +3,25 @@ kind: Cluster metadata: name: postgis-example spec: - instances: 3 - imageName: ghcr.io/cloudnative-pg/postgis:14 - bootstrap: - initdb: - postInitTemplateSQL: - - CREATE EXTENSION postgis; - - CREATE EXTENSION postgis_topology; - - CREATE EXTENSION fuzzystrmatch; - - CREATE EXTENSION postgis_tiger_geocoder; - + instances: 1 + imageName: ghcr.io/cloudnative-pg/postgis:17 storage: size: 1Gi + postgresql: + parameters: + log_statement: ddl +--- +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Database +metadata: + name: postgis-example-app +spec: + name: app + owner: app + cluster: + name: postgis-example + extensions: + - name: postgis + - name: postgis_topology + - name: fuzzystrmatch + - name: postgis_tiger_geocoder diff --git a/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx b/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx index c64bc7cc0af..564e973dabd 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx @@ -3,6 +3,8 @@ title: 'Scheduling' originalFilePath: 'src/scheduling.md' --- + + Scheduling, in Kubernetes, is the process responsible for placing a new pod on the best node possible, based on several criteria. 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 5edd068fbb2..237690af789 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/service_management.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/service_management.mdx @@ -3,6 +3,8 @@ title: 'Service Management' originalFilePath: 'src/service_management.md' --- + + A PostgreSQL cluster should only be accessed via standard Kubernetes network services directly managed by EDB Postgres for Kubernetes. For more details, refer to the ["Service" page of the Kubernetes Documentation](https://kubernetes.io/docs/concepts/services-networking/service/#virtual-ips-and-service-proxies). 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 e0b3e05ce74..dce298814fc 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/ssl_connections.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/ssl_connections.mdx @@ -3,6 +3,8 @@ title: 'Client TLS/SSL connections' originalFilePath: 'src/ssl_connections.md' --- + + !!! Seealso "Certificates" See [Certificates](certificates.md) for more details on how EDB Postgres for Kubernetes supports TLS certificates. @@ -93,7 +95,7 @@ spec: app: webtest spec: containers: - - image: ghcr.io/cloudnative-pg/webtest:1.6.0 + - image: ghcr.io/cloudnative-pg/webtest:1.7.0 name: cert-test volumeMounts: - name: secret-volume-root-ca diff --git a/product_docs/docs/postgres_for_kubernetes/1/storage.mdx b/product_docs/docs/postgres_for_kubernetes/1/storage.mdx index f526be3575d..69d28b89195 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/storage.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/storage.mdx @@ -3,6 +3,8 @@ title: 'Storage' originalFilePath: 'src/storage.md' --- + + Storage is the most critical component in a database workload. Storage must always be available, scale, perform well, and guarantee consistency and durability. The same expectations and @@ -261,110 +263,6 @@ 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. - -!!! 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 diff --git a/product_docs/docs/postgres_for_kubernetes/1/tablespaces.mdx b/product_docs/docs/postgres_for_kubernetes/1/tablespaces.mdx index e54ce48a2b9..0efcf6edf4e 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/tablespaces.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/tablespaces.mdx @@ -3,6 +3,8 @@ title: 'Tablespaces' originalFilePath: 'src/tablespaces.md' --- + + A tablespace is a robust and widely embraced feature in database management systems. It offers a powerful means to enhance the vertical scalability of a database by decoupling the physical and logical modeling of diff --git a/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx b/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx index a98d2ccf8d3..87dcd73ab3e 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx @@ -3,6 +3,8 @@ title: 'Troubleshooting' originalFilePath: 'src/troubleshooting.md' --- + + In this page, you can find some basic information on how to troubleshoot EDB Postgres for Kubernetes in your Kubernetes cluster deployment. @@ -822,3 +824,9 @@ establish the connection for approximately 127 seconds before giving up. This prolonged retry period can significantly delay the reconnection process. For more details, consult the [tcp_syn_retries documentation](https://www.kernel.org/doc/Documentation/networking/ip-sysctl.txt). + +You can work around this issue by setting `STANDBY_TCP_USER_TIMEOUT` in the +[operator configuration](operator_conf.md#available-options). This will cause +the standby instances to close the TCP connection if the initial `SYN` packet +is not acknowledged within the specified timeout, allowing them to retry the +connection more quickly. diff --git a/product_docs/docs/postgres_for_kubernetes/1/use_cases.mdx b/product_docs/docs/postgres_for_kubernetes/1/use_cases.mdx index 813300a5cec..1a854aa30b1 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/use_cases.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/use_cases.mdx @@ -3,6 +3,8 @@ title: 'Use cases' originalFilePath: 'src/use_cases.md' --- + + EDB Postgres for Kubernetes has been designed to work with applications that reside in the same Kubernetes cluster, for a full cloud native experience. 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 7de3864c39d..136a24fa10b 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/wal_archiving.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/wal_archiving.mdx @@ -3,6 +3,14 @@ title: 'WAL archiving' originalFilePath: 'src/wal_archiving.md' --- + + +!!! Warning + With the deprecation of native Barman Cloud support in EDB Postgres for Kubernetes in + favor of the Barman Cloud Plugin, this page—and the backup and recovery + documentation—may undergo changes before the official release of version + 1.26.0. + WAL archiving is the process that feeds a [WAL archive](backup.md#wal-archive) in EDB Postgres for Kubernetes.