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 deb0cecaec6..29420b58970 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/backup_barmanobjectstore.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/backup_barmanobjectstore.mdx @@ -99,9 +99,9 @@ algorithms via `barman-cloud-backup` (for backups) and - snappy The compression settings for backups and WALs are independent. See the -[DataBackupConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration) and +[DataBackupConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration) and [WALBackupConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration) sections in -the API reference. +the barman-cloud API reference. It is important to note that archival time, restore time, and size change between the algorithms, so the compression algorithm should be chosen according diff --git a/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx b/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx index 650b6c544b3..10b4c70cc0e 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/bootstrap.mdx @@ -32,7 +32,7 @@ For more detailed information about this feature, please refer to the EDB Postgres for Kubernetes requires both the `postgres` user and database to always exists. Using the local Unix Domain Socket, it needs to connect as `postgres` user to the `postgres` database via `peer` authentication in - order to perform administrative tasks on the cluster. + order to perform administrative tasks on the cluster. **DO NOT DELETE** the `postgres` user or the `postgres` database!!! !!! Info @@ -212,36 +212,87 @@ The user that owns the database defaults to the database name instead. The application user is not used internally by the operator, which instead relies on the superuser to reconcile the cluster with the desired status. -### Passing options to `initdb` +### Passing Options to `initdb` -The actual PostgreSQL data directory is created via an invocation of the -`initdb` PostgreSQL command. If you need to add custom options to that command -(i.e., to change the `locale` used for the template databases or to add data -checksums), you can use the following parameters: +The PostgreSQL data directory is initialized using the +[`initdb` PostgreSQL command](https://www.postgresql.org/docs/current/app-initdb.html). + +EDB Postgres for Kubernetes enables you to customize the behavior of `initdb` to modify +settings such as default locale configurations and data checksums. + +!!! Warning + EDB Postgres for Kubernetes acts only as a direct proxy to `initdb` for locale-related + options, due to the ongoing and significant enhancements in PostgreSQL's locale + support. It is your responsibility to ensure that the correct options are + provided, following the PostgreSQL documentation, and to verify that the + bootstrap process completes successfully. + +To include custom options in the `initdb` command, you can use the following +parameters: + +builtinLocale +: When `builtinLocale` is set to a value, EDB Postgres for Kubernetes passes it to the + `--builtin-locale` option in `initdb`. This option controls the builtin locale, as + defined in ["Locale Support"](https://www.postgresql.org/docs/current/locale.html) + from the PostgreSQL documentation (default: empty). Note that this option requires + `localeProvider` to be set to `builtin`. Available from PostgreSQL 17. dataChecksums -: When `dataChecksums` is set to `true`, CNP invokes the `-k` option in +: When `dataChecksums` is set to `true`, EDB Postgres for Kubernetes invokes the `-k` option in `initdb` to enable checksums on data pages and help detect corruption by the I/O system - that would otherwise be silent (default: `false`). encoding -: When `encoding` set to a value, CNP passes it to the `--encoding` option in `initdb`, - which selects the encoding of the template database (default: `UTF8`). +: When `encoding` set to a value, EDB Postgres for Kubernetes passes it to the `--encoding` + option in `initdb`, which selects the encoding of the template database + (default: `UTF8`). + +icuLocale +: When `icuLocale` is set to a value, EDB Postgres for Kubernetes passes it to the + `--icu-locale` option in `initdb`. This option controls the ICU locale, as + defined in ["Locale Support"](https://www.postgresql.org/docs/current/locale.html) + from the PostgreSQL documentation (default: empty). + Note that this option requires `localeProvider` to be set to `icu`. + Available from PostgreSQL 15. + +icuRules +: When `icuRules` is set to a value, EDB Postgres for Kubernetes passes it to the + `--icu-rules` option in `initdb`. This option controls the ICU locale, as + defined in ["Locale + Support"](https://www.postgresql.org/docs/current/locale.html) from the + PostgreSQL documentation (default: empty). Note that this option requires + `localeProvider` to be set to `icu`. Available from PostgreSQL 16. + +locale +: When `locale` is set to a value, EDB Postgres for Kubernetes passes it to the `--locale` + option in `initdb`. This option controls the locale, as defined in + ["Locale Support"](https://www.postgresql.org/docs/current/locale.html) from + the PostgreSQL documentation. By default, the locale parameter is empty. In + this case, environment variables such as `LANG` are used to determine the + locale. Be aware that these variables can vary between container images, + potentially leading to inconsistent behavior. localeCollate -: When `localeCollate` is set to a value, CNP passes it to the `--lc-collate` +: When `localeCollate` is set to a value, EDB Postgres for Kubernetes passes it to the `--lc-collate` option in `initdb`. This option controls the collation order (`LC_COLLATE` subcategory), as defined in ["Locale Support"](https://www.postgresql.org/docs/current/locale.html) from the PostgreSQL documentation (default: `C`). localeCType -: When `localeCType` is set to a value, CNP passes it to the `--lc-ctype` option in +: When `localeCType` is set to a value, EDB Postgres for Kubernetes passes it to the `--lc-ctype` option in `initdb`. This option controls the collation order (`LC_CTYPE` subcategory), as defined in ["Locale Support"](https://www.postgresql.org/docs/current/locale.html) from the PostgreSQL documentation (default: `C`). +localeProvider +: When `localeProvider` is set to a value, EDB Postgres for Kubernetes passes it to the `--locale-provider` +option in `initdb`. This option controls the locale provider, as defined in +["Locale Support"](https://www.postgresql.org/docs/current/locale.html) from the +PostgreSQL documentation (default: empty, which means `libc` for PostgreSQL). +Available from PostgreSQL 15. + walSegmentSize -: When `walSegmentSize` is set to a value, CNP passes it to the `--wal-segsize` +: When `walSegmentSize` is set to a value, EDB Postgres for Kubernetes passes it to the `--wal-segsize` option in `initdb` (default: not set - defined by PostgreSQL as 16 megabytes). !!! Note @@ -430,44 +481,59 @@ to the ["Recovery" section](recovery.md). ### Bootstrap from a live cluster (`pg_basebackup`) -The `pg_basebackup` bootstrap mode lets you create a new cluster (*target*) as -an exact physical copy of an existing and **binary compatible** PostgreSQL -instance (*source*), through a valid *streaming replication* connection. -The source instance can be either a primary or a standby PostgreSQL server. +The `pg_basebackup` bootstrap mode allows you to create a new cluster +(*target*) as an exact physical copy of an existing and **binary-compatible** +PostgreSQL instance (*source*) managed by EDB Postgres for Kubernetes, using a valid +*streaming replication* connection. The source instance can either be a primary +or a standby PostgreSQL server. It’s crucial to thoroughly review the +requirements section below, as the pros and cons of PostgreSQL physical +replication fully apply. -The primary use case for this method is represented by **migrations** to EDB Postgres for Kubernetes, -either from outside Kubernetes or within Kubernetes (e.g., from another operator). +The primary use cases for this method include: -!!! Warning - The current implementation creates a *snapshot* of the origin PostgreSQL - instance when the cloning process terminates and immediately starts - the created cluster. See ["Current limitations"](#current-limitations) below for details. +- Reporting and business intelligence clusters that need to be regenerated + periodically (daily, weekly) +- Test databases containing live data that require periodic regeneration + (daily, weekly, monthly) and anonymization +- Rapid spin-up of a standalone replica cluster +- Physical migrations of EDB Postgres for Kubernetes clusters to different namespaces or + Kubernetes clusters -Similar to the case of the `recovery` bootstrap method, once the clone operation -completes, the operator will take ownership of the target cluster, starting from -the first instance. This includes overriding some configuration parameters, as -required by EDB Postgres for Kubernetes, resetting the superuser password, creating -the `streaming_replica` user, managing the replicas, and so on. The resulting -cluster will be completely independent of the source instance. +!!! Important + Avoid using this method, based on physical replication, to migrate an + existing PostgreSQL cluster outside of Kubernetes into EDB Postgres for Kubernetes unless you + are completely certain that all requirements are met and the operation has been + thoroughly tested. The EDB Postgres for Kubernetes community does not endorse this approach + for such use cases and recommends using logical import instead. It is + exceedingly rare that all requirements for physical replication are met in a + way that seamlessly works with EDB Postgres for Kubernetes. + +!!! Warning + In its current implementation, this method clones the source PostgreSQL + instance, thereby creating a *snapshot*. Once the cloning process has finished, + the new cluster is immediately started. + Refer to ["Current limitations"](#current-limitations) for more details. + +Similar to the `recovery` bootstrap method, once the cloning operation is +complete, the operator takes full ownership of the target cluster, starting +from the first instance. This includes overriding certain configuration +parameters as required by EDB Postgres for Kubernetes, resetting the superuser password, +creating the `streaming_replica` user, managing replicas, and more. The +resulting cluster operates independently from the source instance. !!! Important - Configuring the network between the target instance and the source instance - goes beyond the scope of EDB Postgres for Kubernetes documentation, as it depends - on the actual context and environment. + Configuring the network connection between the target and source instances + lies outside the scope of EDB Postgres for Kubernetes documentation, as it depends heavily on + the specific context and environment. -The streaming replication client on the target instance, which will be -transparently managed by `pg_basebackup`, can authenticate itself on the source -instance in any of the following ways: +The streaming replication client on the target instance, managed transparently +by `pg_basebackup`, can authenticate on the source instance using one of the +following methods: -1. via [username/password](#usernamepassword-authentication) -2. via [TLS client certificate](#tls-certificate-authentication) +1. [Username/password](#usernamepassword-authentication) +2. [TLS client certificate](#tls-certificate-authentication) -The latter is the recommended one if you connect to a source managed -by EDB Postgres for Kubernetes or configured for TLS authentication. -The first option is, however, the most common form of authentication to a -PostgreSQL server in general, and might be the easiest way if the source -instance is on a traditional environment outside Kubernetes. -Both cases are explained below. +Both authentication methods are detailed below. #### Requirements @@ -545,7 +611,7 @@ file on the source PostgreSQL instance: host replication streaming_replica all md5 ``` -The following manifest creates a new PostgreSQL 17.0 cluster, +The following manifest creates a new PostgreSQL 17.2 cluster, called `target-db`, using the `pg_basebackup` bootstrap method to clone an external PostgreSQL cluster defined as `source-db` (in the `externalClusters` array). As you can see, the `source-db` @@ -560,7 +626,7 @@ metadata: name: target-db spec: instances: 3 - imageName: quay.io/enterprisedb/postgresql:17.0 + imageName: quay.io/enterprisedb/postgresql:17.2 bootstrap: pg_basebackup: @@ -580,7 +646,7 @@ spec: ``` All the requirements must be met for the clone operation to work, including -the same PostgreSQL version (in our case 17.0). +the same PostgreSQL version (in our case 17.2). #### TLS certificate authentication @@ -595,7 +661,7 @@ in the same Kubernetes cluster. This example can be easily adapted to cover an instance that resides outside the Kubernetes cluster. -The manifest defines a new PostgreSQL 17.0 cluster called `cluster-clone-tls`, +The manifest defines a new PostgreSQL 17.2 cluster called `cluster-clone-tls`, which is bootstrapped using the `pg_basebackup` method from the `cluster-example` external cluster. The host is identified by the read/write service in the same cluster, while the `streaming_replica` user is authenticated @@ -610,7 +676,7 @@ metadata: name: cluster-clone-tls spec: instances: 3 - imageName: quay.io/enterprisedb/postgresql:17.0 + imageName: quay.io/enterprisedb/postgresql:17.2 bootstrap: pg_basebackup: @@ -691,7 +757,7 @@ instance using a second connection (see the `--wal-method=stream` option for Once the backup is completed, the new instance will be started on a new timeline and diverge from the source. For this reason, it is advised to stop all write operations to the source database -before migrating to the target database in Kubernetes. +before migrating to the target database. !!! Important Before you attempt a migration, you must test both the procedure diff --git a/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx b/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx index 829e682b172..e19687881f4 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/certificates.mdx @@ -132,14 +132,14 @@ Given the following files: Create a secret containing the CA certificate: -``` +```sh kubectl create secret generic my-postgresql-server-ca \ --from-file=ca.crt=./server-ca.crt ``` Create a secret with the TLS certificate: -``` +```sh kubectl create secret tls my-postgresql-server \ --cert=./server.crt --key=./server.key ``` 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 3943ef00288..2e52773f714 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/connection_pooling.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/connection_pooling.mdx @@ -335,13 +335,17 @@ are the ones directly set by PgBouncer. - [`application_name_add_host`](https://www.pgbouncer.org/config.html#application_name_add_host) - [`autodb_idle_timeout`](https://www.pgbouncer.org/config.html#autodb_idle_timeout) +- [`cancel_wait_timeout`](https://www.pgbouncer.org/config.html#cancel_wait_timeout) - [`client_idle_timeout`](https://www.pgbouncer.org/config.html#client_idle_timeout) - [`client_login_timeout`](https://www.pgbouncer.org/config.html#client_login_timeout) - [`default_pool_size`](https://www.pgbouncer.org/config.html#default_pool_size) - [`disable_pqexec`](https://www.pgbouncer.org/config.html#disable_pqexec) +- [`dns_max_ttl`](https://www.pgbouncer.org/config.html#dns_max_ttl) +- [`dns_nxdomain_ttl`](https://www.pgbouncer.org/config.html#dns_nxdomain_ttl) - [`idle_transaction_timeout`](https://www.pgbouncer.org/config.html#idle_transaction_timeout) - [`ignore_startup_parameters`](https://www.pgbouncer.org/config.html#ignore_startup_parameters): - to be appended to `extra_float_digits,options` - required by CNP + to be appended to `extra_float_digits,options` - required by EDB Postgres for Kubernetes +- [`listen_backlog`](https://www.pgbouncer.org/config.html#listen_backlog) - [`log_connections`](https://www.pgbouncer.org/config.html#log_connections) - [`log_disconnections`](https://www.pgbouncer.org/config.html#log_disconnections) - [`log_pooler_errors`](https://www.pgbouncer.org/config.html#log_pooler_errors) @@ -350,13 +354,16 @@ are the ones directly set by PgBouncer. export as described in the ["Monitoring"](#monitoring) section below - [`max_client_conn`](https://www.pgbouncer.org/config.html#max_client_conn) - [`max_db_connections`](https://www.pgbouncer.org/config.html#max_db_connections) +- [`max_packet_size`](https://www.pgbouncer.org/config.html#max_packet_size) - [`max_prepared_statements`](https://www.pgbouncer.org/config.html#max_prepared_statements) - [`max_user_connections`](https://www.pgbouncer.org/config.html#max_user_connections) - [`min_pool_size`](https://www.pgbouncer.org/config.html#min_pool_size) +- [`pkt_buf`](https://www.pgbouncer.org/config.html#pkt_buf) - [`query_timeout`](https://www.pgbouncer.org/config.html#query_timeout) - [`query_wait_timeout`](https://www.pgbouncer.org/config.html#query_wait_timeout) - [`reserve_pool_size`](https://www.pgbouncer.org/config.html#reserve_pool_size) - [`reserve_pool_timeout`](https://www.pgbouncer.org/config.html#reserve_pool_timeout) +- [`sbuf_loopcnt`](https://www.pgbouncer.org/config.html#sbuf_loopcnt) - [`server_check_delay`](https://www.pgbouncer.org/config.html#server_check_delay) - [`server_check_query`](https://www.pgbouncer.org/config.html#server_check_query) - [`server_connect_timeout`](https://www.pgbouncer.org/config.html#server_connect_timeout) @@ -367,12 +374,18 @@ are the ones directly set by PgBouncer. - [`server_reset_query`](https://www.pgbouncer.org/config.html#server_reset_query) - [`server_reset_query_always`](https://www.pgbouncer.org/config.html#server_reset_query_always) - [`server_round_robin`](https://www.pgbouncer.org/config.html#server_round_robin) +- [`server_tls_ciphers`](https://www.pgbouncer.org/config.html#server_tls_ciphers) +- [`server_tls_server_tls_protocols`](https://www.pgbouncer.org/config.html#server_tls_protocols) - [`stats_period`](https://www.pgbouncer.org/config.html#stats_period) +- [`suspend_timeout`](https://www.pgbouncer.org/config.html#suspend_timeout) +- [`tcp_defer_accept`](https://www.pgbouncer.org/config.html#tcp_defer_accept) - [`tcp_keepalive`](https://www.pgbouncer.org/config.html#tcp_keepalive) - [`tcp_keepcnt`](https://www.pgbouncer.org/config.html#tcp_keepcnt) - [`tcp_keepidle`](https://www.pgbouncer.org/config.html#tcp_keepidle) - [`tcp_keepintvl`](https://www.pgbouncer.org/config.html#tcp_keepintvl) - [`tcp_user_timeout`](https://www.pgbouncer.org/config.html#tcp_user_timeout) +- [`tcp_socket_buffer`](https://www.pgbouncer.org/config.html#tcp_socket_buffer) +- [`track_extra_parameters`](https://www.pgbouncer.org/config.html#track_extra_parameters) - [`verbose`](https://www.pgbouncer.org/config.html#verbose) Customizations of the PgBouncer configuration are written declaratively in the 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 2dc53155226..d203baffb82 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/database_import.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/database_import.mdx @@ -76,7 +76,7 @@ performed in 4 steps: - `initdb` bootstrap of the new cluster - export of the selected database (in `initdb.import.databases`) using - `pg_dump -Fc` + `pg_dump -Fd` - import of the database using `pg_restore --no-acl --no-owner` into the `initdb.database` (application database) owned by the `initdb.owner` user - cleanup of the database dump file @@ -148,7 +148,7 @@ There are a few things you need to be aware of when using the `microservice` typ `externalCluster` during the operation - Connection to the source database must be granted with the specified user that needs to run `pg_dump` and read roles information (*superuser* is OK) -- Currently, the `pg_dump -Fc` result is stored temporarily inside the `dumps` +- Currently, the `pg_dump -Fd` result is stored temporarily inside the `dumps` folder in the `PGDATA` volume, so there should be enough available space to temporarily contain the dump result on the assigned node, as well as the restored data and indexes. Once the import operation is completed, this @@ -165,7 +165,7 @@ The operation is performed in the following steps: - `initdb` bootstrap of the new cluster - export and import of the selected roles - export of the selected databases (in `initdb.import.databases`), one at a time, - using `pg_dump -Fc` + using `pg_dump -Fd` - create each of the selected databases and import data using `pg_restore` - run `ANALYZE` on each imported database - cleanup of the database dump files @@ -225,7 +225,7 @@ There are a few things you need to be aware of when using the `monolith` type: - Connection to the source database must be granted with the specified user that needs to run `pg_dump` and retrieve roles information (*superuser* is OK) -- Currently, the `pg_dump -Fc` result is stored temporarily inside the `dumps` +- Currently, the `pg_dump -Fd` result is stored temporarily inside the `dumps` folder in the `PGDATA` volume, so there should be enough available space to temporarily contain the dump result on the assigned node, as well as the restored data and indexes. Once the import operation is completed, this @@ -270,3 +270,51 @@ topic is beyond the scope of EDB Postgres for Kubernetes, we recommend that you unnecessary writes in the checkpoint area by tuning Postgres GUCs like `shared_buffers`, `max_wal_size`, `checkpoint_timeout` directly in the `Cluster` configuration. + +## Customizing `pg_dump` and `pg_restore` Behavior + +You can customize the behavior of `pg_dump` and `pg_restore` by specifying +additional options using the `pgDumpExtraOptions` and `pgRestoreExtraOptions` +parameters. For instance, you can enable parallel jobs to speed up data +import/export processes, as shown in the following example: + +```yaml + # + bootstrap: + initdb: + import: + type: microservice + databases: + - app + source: + externalCluster: cluster-example + pgDumpExtraOptions: + - '--jobs=2' + pgRestoreExtraOptions: + - '--jobs=2' + # +``` + +!!! Warning + Use the `pgDumpExtraOptions` and `pgRestoreExtraOptions` fields with + caution and at your own risk. These options are not validated or verified by + the operator, and some configurations may conflict with its intended + functionality or behavior. Always test thoroughly in a safe and controlled + environment before applying them in production. + +## Online Import and Upgrades + +Logical replication offers a powerful way to import any PostgreSQL database +accessible over the network using the following approach: + +- **Import Bootstrap with Schema-Only Option**: Initialize the schema in the + target database before replication begins. +- **`Subscription` Resource**: Set up continuous replication to synchronize + data changes. + +This technique can also be leveraged for performing major PostgreSQL upgrades +with minimal downtime, making it ideal for seamless migrations and system +upgrades. + +For more details, including limitations and best practices, refer to the +[Logical Replication](logical_replication.md) section in the documentation. 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 new file mode 100644 index 00000000000..fc2ebe64bf8 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/declarative_database_management.mdx @@ -0,0 +1,218 @@ +--- +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) +section. + +For more advanced use cases, EDB Postgres for Kubernetes introduces **declarative database +management**, which empowers users to define and control the lifecycle of +PostgreSQL databases using the `Database` Custom Resource Definition (CRD). +This method seamlessly integrates with Kubernetes, providing a scalable, +automated, and consistent approach to managing PostgreSQL databases. + +* * * + +## Key Concepts + +### 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. + +### Declarative `Database` Manifest + +The following example demonstrates how a `Database` resource interacts with a +`Cluster`: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Database +metadata: + name: cluster-example-one +spec: + name: one + owner: app + cluster: + name: cluster-example +``` + +When applied, this manifest creates a `Database` object called +`cluster-example-one` requesting a database named `one`, owned by the `app` +role, in the `cluster-example` PostgreSQL cluster. + +!!! Info + Please refer to the [API reference](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-DatabaseSpec) + the full list of attributes you can define for each `Database` object. + +### Required Fields in the `Database` Manifest + +- `metadata.name`: Unique name of the Kubernetes object within its namespace. +- `spec.name`: Name of the database as it will appear in PostgreSQL. +- `spec.owner`: PostgreSQL role that owns the database. +- `spec.cluster.name`: Name of the target PostgreSQL cluster. + +The `Database` object must reference a specific `Cluster`, determining where +the database will be created. It is managed by the cluster's primary instance, +ensuring the database is created or updated as needed. + +!!! Info + The distinction between `metadata.name` and `spec.name` allows multiple + `Database` resources to reference databases with the same name across different + EDB Postgres for Kubernetes clusters in the same Kubernetes namespace. + +## Reserved Database Names + +PostgreSQL automatically creates databases such as `postgres`, `template0`, and +`template1`. These names are reserved and cannot be used for new `Database` +objects in EDB Postgres for Kubernetes. + +!!! Important + Creating a `Database` with `spec.name` set to `postgres`, `template0`, or + `template1` is not allowed. + +## Reconciliation and Status + +Once a `Database` object is reconciled successfully: + +- `status.applied` will be set to `true`. +- `status.observedGeneration` will match the `metadata.generation` of the last + applied configuration. + +Example of a reconciled `Database` object: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Database +metadata: + generation: 1 + name: cluster-example-one +spec: + cluster: + name: cluster-example + name: one + owner: app +status: + observedGeneration: 1 + applied: true +``` + +If an error occurs during reconciliation, `status.applied` will be `false`, and +an error message will be included in the `status.message` field. + +## Deleting a Database + +EDB Postgres for Kubernetes supports two methods for database deletion: + +1. Using the `delete` reclaim policy +2. Declaratively setting the database's `ensure` field to `absent` + +### Deleting via `delete` Reclaim Policy + +The `databaseReclaimPolicy` field determines the behavior when a `Database` +object is deleted: + +- `retain` (default): The database remains in PostgreSQL for manual management. +- `delete`: The database is automatically removed from PostgreSQL. + +Example: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Database +metadata: + name: cluster-example-two +spec: + databaseReclaimPolicy: delete + name: two + owner: app + cluster: + name: cluster-example +``` + +Deleting this `Database` object will automatically remove the `two` database +from the `cluster-example` cluster. + +### Declaratively Setting `ensure: absent` + +To remove a database, set the `ensure` field to `absent` like in the following +example:. + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Database +metadata: + name: cluster-example-database-to-drop +spec: + cluster: + name: cluster-example + name: database-to-drop + owner: app + ensure: absent +``` + +This manifest ensures that the `database-to-drop` database is removed from the +`cluster-example` cluster. + +## Limitations and Caveats + +### Renaming a database + +While EDB Postgres for Kubernetes adheres to PostgreSQL’s +[CREATE DATABASE](https://www.postgresql.org/docs/current/sql-createdatabase.html) and +[ALTER DATABASE](https://www.postgresql.org/docs/current/sql-alterdatabase.html) +commands, **renaming databases is not supported**. +Attempting to modify `spec.name` in an existing `Database` object will result +in rejection by Kubernetes. + +### Creating vs. Altering a Database + +- For new databases, EDB Postgres for Kubernetes uses the `CREATE DATABASE` statement. +- For existing databases, `ALTER DATABASE` is used to apply changes. + +It is important to note that there are some differences between these two +Postgres commands: in particular, the options accepted by `ALTER` are a subset +of those accepted by `CREATE`. + +!!! Warning + Some fields, such as encoding and collation settings, are immutable in + PostgreSQL. Attempts to modify these fields on existing databases will be + ignored. + +### Replica Clusters + +Database objects declared on replica clusters cannot be enforced, as replicas +lack write privileges. These objects will remain in a pending state until the +replica is promoted. + +### Conflict Resolution + +If two `Database` objects in the same namespace manage the same PostgreSQL +database (i.e., identical `spec.name` and `spec.cluster.name`), the second +object will be rejected. + +Example status message: + +```yaml +status: + applied: false + message: 'reconciliation error: database "one" is already managed by Database object "cluster-example-one"' +``` + +### Postgres Version Differences + +EDB Postgres for Kubernetes adheres to PostgreSQL's capabilities. For example, features like +`ICU_RULES` introduced in PostgreSQL 16 are unavailable in earlier versions. +Errors from PostgreSQL will be reflected in the `Database` object's `status`. + +### Manual Changes + +EDB Postgres for Kubernetes does not overwrite manual changes to databases. Once reconciled, +a `Database` object will not be reapplied unless its `metadata.generation` +changes, giving flexibility for direct PostgreSQL modifications. 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 e1b3c541101..b939cf837c4 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/declarative_hibernation.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/declarative_hibernation.mdx @@ -61,7 +61,7 @@ $ kubectl cnp status Cluster Summary Name: cluster-example Namespace: default -PostgreSQL Image: quay.io/enterprisedb/postgresql:17.0 +PostgreSQL Image: quay.io/enterprisedb/postgresql:17.2 Primary instance: cluster-example-2 Status: Cluster in healthy state Instances: 3 diff --git a/product_docs/docs/postgres_for_kubernetes/1/declarative_role_management.mdx b/product_docs/docs/postgres_for_kubernetes/1/declarative_role_management.mdx index f6d4ede40a4..7144a67eefa 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 @@ -1,5 +1,5 @@ --- -title: 'Database Role Management' +title: 'PostgreSQL Role Management' originalFilePath: 'src/declarative_role_management.md' --- diff --git a/product_docs/docs/postgres_for_kubernetes/1/evaluation.mdx b/product_docs/docs/postgres_for_kubernetes/1/evaluation.mdx index c4700e73644..c5cb758fde3 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/evaluation.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/evaluation.mdx @@ -5,41 +5,10 @@ originalFilePath: 'src/evaluation.md' EDB Postgres for Kubernetes is available for a free evaluation. -The process is different between Community PostgreSQL and EDB Postgres Advanced Server. +Use your EDB account to evaluate Postgres for Kubernetes. If you don't have an account, [register](https://www.enterprisedb.com/accounts/register) for one. Then follow the [installation guide](installation_upgrade.md) to install the operator, using the access token you obtained from your EDB account. ## Evaluating using PostgreSQL -By default, EDB Postgres for Kubernetes installs the latest available version of Community PostgreSQL. - -No license key is required. The operator automatically generates an implicit trial license for the cluster that lasts for 30 days. This trial license is ideal for evaluation, proof of concept, integration with CI/CD pipelines, and so on. +By default, EDB Postgres for Kubernetes installs the latest available version of Community Postgresql. PostgreSQL container images are available at [quay.io/enterprisedb/postgresql](https://quay.io/repository/enterprisedb/postgresql). - -## Evaluating using EDB Postgres Advanced Server - -There are two ways to obtain the EDB Postgres Advanced Server image for evaluation purposes. The easiest is through the EDB Image Repository, where all you’ll need is an EDB account to auto generate a repository access token. The other way is to download the image through [quay.io](http://quay.io) and request a trial license key from EDB support. - -### EDB Image Repository - -You can use EDB Postgres for Kubernetes with EDB Postgres Advanced Server. You can access the image by obtaining a repository access token to EDB's image repositories. - -### Obtaining your access token - -You can request a repository access token from the [EDB Repositories Download](https://www.enterprisedb.com/repos-downloads) page. You will also need to be signed into your EDB account. If you don't have an EDB Account, you can [register for one](https://www.enterprisedb.com/accounts/register) on the EDB site. - -### Quay Image Repository - -If you want to use the Quay image repository, you’ll need a trial license key for access to use the images. To request a trial license key for EDB Postgres Kubernetes please contact your sales representative or you can contact our EDB Technical Support Team by email at [techsupport@enterprisedb.com](mailto:techsupport@enterprisedb.com) or file a ticket on our support portal . Please allow 24 hours for your license to be generated and delivered to you and if you need any additional support please do not hesitate to contact us. - -Once you have your license key, EDB Postgres Advanced container images will be available at - -You can then use EDB Postgres Advanced Server by setting in the `spec` section of the `Cluster` deployment configuration file: - -- `imageName` to point to the quay.io/enterprisedb/edb-postgres-advanced repository -- `licenseKey` to your license key (in the form of a string) - -To see how `imageName` and `licenseKey` is set, refer to the [cluster-full-example](/postgres_for_kubernetes/latest/samples/cluster-example-full.yaml) file from the [configuration samples](/postgres_for_kubernetes/latest/samples/) section. - -## Further Information - -Refer to [License and License keys](license_keys.md) for terms and more details. 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 50b1497e534..5ee96fff19d 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/image_catalog.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/image_catalog.mdx @@ -35,7 +35,7 @@ spec: - major: 15 image: quay.io/enterprisedb/postgresql:15.6 - major: 16 - image: quay.io/enterprisedb/postgresql:17.0 + image: quay.io/enterprisedb/postgresql:17.2 ``` **Example of a Cluster-Wide Catalog using `ClusterImageCatalog` Resource:** @@ -50,7 +50,7 @@ spec: - major: 15 image: quay.io/enterprisedb/postgresql:15.6 - major: 16 - image: quay.io/enterprisedb/postgresql:17.0 + image: quay.io/enterprisedb/postgresql:17.2 ``` A `Cluster` resource has the flexibility to reference either an `ImageCatalog` 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 33b94841bed..87d60da95fe 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/installation_upgrade.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/installation_upgrade.mdx @@ -14,21 +14,79 @@ originalFilePath: 'src/installation_upgrade.md' ## Installation on Kubernetes +### Obtaining an EDB subscription token + +!!! Important + You must obtain an EDB subscription token to install EDB Postgres for Kubernetes. Without a token, you will not be able to access the EDB private software repositories. + +Installing EDB Postgres for Kubernetes requires an EDB Repos 2.0 token to gain access to the EDB private software repositories. + +You can obtain the token by visiting your [EDB Account Profile](https://www.enterprisedb.com/accounts/profile). You will have to sign in if you are not already logged in. + +Your account profile page displays the token to use next to **Repos 2.0 Token** label. By default, the token is obscured, click the "Show" button (an eye icon) to reveal it. + +Your token entitles you to access one of two repositories: standard or enterprise. + +- `standard` - Includes the operator and the EDB Postgres Extended operand images. +- `enterprise` - Includes the operator and the EDB Postgres Advanced and EDB Postgres Extended operand images. + +Set the relevant value, determined by your subscription, as an environment variable `EDB_SUBSCRIPTION_PLAN`. + +```shell +EDB_SUBSCRIPTION_PLAN=enterprise +``` + +then set the Repos 2.0 token to an environment variable `EDB_SUBSCRIPTION_TOKEN`. + +```shell +EDB_SUBSCRIPTION_TOKEN= +``` + +!!! Warning + The token is sensitive information. Please ensure that you don't expose it to unauthorized users. + +You can now proceed with the installation. + ### Using the Helm Chart The operator can be installed using the provided [Helm chart](https://github.com/EnterpriseDB/edb-postgres-for-kubernetes-charts). ### Directly using the operator manifest -The operator can be installed like any other resource in Kubernetes, -through a YAML manifest applied via `kubectl`. +#### Install the EDB pull secret + +Before installing EDB Postgres for Kubernetes, you need to create a pull secret for EDB software in the `postgresql-operator-system` namespace. + +The pull secret needs to be saved in the namespace where the operator will reside. Create the `postgresql-operator-system` namespace using this command: + +```shell +kubectl create namespace postgresql-operator-system +``` + +To create the pull secret itself, run the following command: + +```shell +kubectl create secret -n postgresql-operator-system docker-registry edb-pull-secret \ + --docker-server=docker.enterprisedb.com \ + --docker-username=k8s_$EDB_SUBSCRIPTION_PLAN \ + --docker-password=$EDB_SUBSCRIPTION_TOKEN +``` + +#### Install the operator + +Now that the pull-secret has been added to the namespace, the operator can be installed like any other resource in Kubernetes, +through a YAML manifest applied via `kubectl`. + +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.24.1.yaml). +- Enterprise: The [latest enterprise operator manifest](https://get.enterprisedb.io/pg4k/pg4k-enterprise-1.24.1.yaml). -You can install the [latest operator manifest](https://get.enterprisedb.io/cnp/postgresql-operator-1.24.1.yaml) -for this minor release as follows: +You can install the manifest for the latest version of the operator by running: ```sh kubectl apply --server-side -f \ - https://get.enterprisedb.io/cnp/postgresql-operator-1.24.1.yaml + https://get.enterprisedb.io/pg4k/pg4k-$EDB_SUBSCRIPTION_PLAN-1.24.1.yaml ``` You can verify that with: @@ -66,15 +124,13 @@ for a more comprehensive example. one of the allowed ones, or open the webhooks' port (`9443`) on the firewall. - ## Details about the deployment In Kubernetes, the operator is by default installed in the `postgresql-operator-system` namespace as a Kubernetes `Deployment`. The name of this deployment depends on the installation method. -When installed through the manifest or the `cnp` plugin, it is called -`postgresql-operator-controller-manager` by default. When installed via Helm, the default name -is `postgresql-operator-cloudnative-pg`. +When installed through the manifest or the `cnp` plugin, by default, it is called `postgresql-operator-controller-manager`. +When installed via Helm, by default, the deployment name is derived from the helm release name, appended with the suffix `-edb-postgres-for-kubernetes` (e.g., `-edb-postgres-for-kubernetes`). !!! Note With Helm you can customize the name of the deployment via the @@ -129,13 +185,13 @@ by applying the manifest of the newer version for plain Kubernetes installations, or using the native package manager of the used distribution (please follow the instructions in the above sections). -The second step is automatically executed after having updated the controller, -by default triggering a rolling update of every deployed PostgreSQL instance to -use the new instance manager. The rolling update procedure culminates with a -switchover, which is controlled by the `primaryUpdateStrategy` option, by -default set to `unsupervised`. When set to `supervised`, users need to complete -the rolling update by manually promoting a new instance through the `cnp` -plugin for `kubectl`. +The second step is automatically triggered after updating the controller. By +default, this initiates a rolling update of every deployed PostgreSQL cluster, +upgrading one instance at a time to use the new instance manager. The rolling +update concludes with a switchover, which is governed by the +`primaryUpdateStrategy` option. The default value, `unsupervised`, completes +the switchover automatically. If set to `supervised`, the user must manually +promote the new primary instance using the `cnp` plugin for `kubectl`. !!! Seealso "Rolling updates" This process is discussed in-depth on the [Rolling Updates](rolling_update.md) page. @@ -150,6 +206,21 @@ the instance manager. This approach does not require a restart of the PostgreSQL instance, thereby avoiding a switchover within the cluster. This feature, which is disabled by default, is described in detail below. +### Spread Upgrades + +By default, all PostgreSQL clusters are rolled out simultaneously, which may +lead to a spike in resource usage, especially when managing multiple clusters. +EDB Postgres for Kubernetes provides two configuration options at the [operator level](operator_conf.md) +that allow you to introduce delays between cluster roll-outs or even between +instances within the same cluster, helping to distribute resource usage over +time: + +- `CLUSTERS_ROLLOUT_DELAY`: Defines the number of seconds to wait between + roll-outs of different PostgreSQL clusters (default: `0`). +- `INSTANCES_ROLLOUT_DELAY`: Defines the number of seconds to wait between + roll-outs of individual instances within the same PostgreSQL cluster (default: + `0`). + ### In-place updates of the instance manager By default, EDB Postgres for Kubernetes issues a rolling update of the cluster diff --git a/product_docs/docs/postgres_for_kubernetes/1/kubectl-plugin.mdx b/product_docs/docs/postgres_for_kubernetes/1/kubectl-plugin.mdx index 47b0c615ef8..68094eea889 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/kubectl-plugin.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/kubectl-plugin.mdx @@ -34,53 +34,53 @@ them in your systems. #### Debian packages -For example, let's install the 1.22.2 release of the plugin, for an Intel based +For example, let's install the 1.24.1 release of the plugin, for an Intel based 64 bit server. First, we download the right `.deb` file. -``` sh -wget https://github.com/EnterpriseDB/kubectl-cnp/releases/download/v1.22.1/kubectl-cnp_1.22.2_linux_x86_64.deb +```sh +wget https://github.com/EnterpriseDB/kubectl-cnp/releases/download/v1.24.1/kubectl-cnp_1.24.1_linux_x86_64.deb \ + --output-document kube-plugin.deb ``` -Then, install from the local file using `dpkg`: +Then, with superuser privileges, install from the local file using `dpkg`: -``` sh -dpkg -i kubectl-cnp_1.22.2_linux_x86_64.deb -(Reading database ... 702524 files and directories currently installed.) -Preparing to unpack kubectl-cnp_1.22.2_linux_x86_64.deb ... -Unpacking cnp (1.22.2) over (1.22.2) ... -Setting up cnp (1.22.2) .. +```console +$ sudo dpkg -i kube-plugin.deb +Selecting previously unselected package cnp. +(Reading database ... 6688 files and directories currently installed.) +Preparing to unpack kube-plugin.deb ... +Unpacking kubectl-cnp (1.24.1) ... +Setting up kubectl-cnp (1.24.1) ... ``` #### RPM packages -As in the example for `.deb` packages, let's install the 1.22.2 release for an +As in the example for `.rpm` packages, let's install the 1.24.1 release for an Intel 64 bit machine. Note the `--output` flag to provide a file name. -``` sh -curl -L https://github.com/EnterpriseDB/kubectl-cnp/releases/download/v1.22.2/kubectl-cnp_1.22.2_linux_x86_64.rpm \ +```sh +curl -L https://github.com/EnterpriseDB/kubectl-cnp/releases/download/v1.24.1/kubectl-cnp_1.24.1_linux_x86_64.rpm \ --output kube-plugin.rpm ``` -Then install with `yum`, and you're ready to use: +Then, with superuser privileges, install with `yum`, and you're ready to use: -``` sh -yum --disablerepo=* localinstall kube-plugin.rpm -yum --disablerepo=* localinstall kube-plugin.rpm -__OUTPUT__ +```console +$ sudo yum --disablerepo=* localinstall kube-plugin.rpm Failed to set locale, defaulting to C.UTF-8 Dependencies resolved. ==================================================================================================== Package Architecture Version Repository Size ==================================================================================================== Installing: - cnp x86_64 1.22.2-1 @commandline 17 M + cnp x86_64 1.24.1-1 @commandline 20 M Transaction Summary ==================================================================================================== Install 1 Package -Total size: 14 M -Installed size: 43 M +Total size: 20 M +Installed size: 78 M Is this ok [y/N]: y ``` @@ -127,11 +127,34 @@ sudo mv kubectl_complete-cnp /usr/local/bin !!! Important The name of the script needs to be exactly the one provided since is used by the kubectl auto-complete process +### Configuring auto-completion + +To configure auto-completion for the plugin, a helper shell script needs to be +installed into your current PATH. Assuming the latter contains `/usr/local/bin`, +this can be done with the following commands: + +```sh +cat > kubectl_complete-cnp < ``` @@ -149,28 +172,28 @@ installation namespace, namespaces to watch, and so on. For details and available options, run: -```shell +```sh kubectl cnp install generate --help ``` The main options are: -- `-n`: specifies the namespace in which to install the operator (default: - `cnp-system`). -- `--control-plane`: if set to true, the operator deployment will include a - toleration and affinity for `node-role.kubernetes.io/control-plane`. -- `--replicas`: sets the number of replicas in the deployment. -- `--watch-namespace`: specifies a comma-separated list of namespaces to watch - (default: all namespaces). -- `--version`: defines the minor version of the operator to be installed, such - as `1.23`. If a minor version is specified, the plugin installs the latest - patch version of that minor version. If no version is supplied, the plugin - installs the latest `MAJOR.MINOR.PATCH` version of the operator. +- `-n`: specifies the namespace in which to install the operator (default: + `postgresql-operator-system`). +- `--control-plane`: if set to true, the operator deployment will include a + toleration and affinity for `node-role.kubernetes.io/control-plane`. +- `--replicas`: sets the number of replicas in the deployment. +- `--watch-namespace`: specifies a comma-separated list of namespaces to watch + (default: all namespaces). +- `--version`: defines the minor version of the operator to be installed, such + as `1.23`. If a minor version is specified, the plugin installs the latest + patch version of that minor version. If no version is supplied, the plugin + installs the latest `MAJOR.MINOR.PATCH` version of the operator. An example of the `generate` command, which will generate a YAML manifest that will install the operator, is as follows: -```shell +```sh kubectl cnp install generate \ -n king \ --version 1.23 \ @@ -180,11 +203,12 @@ kubectl cnp install generate \ ``` The flags in the above command have the following meaning: -- `-n king` install the cnp operator into the `king` namespace -- `--version 1.23` install the latest patch version for minor version 1.23 -- `--replicas 3` install the operator with 3 replicas -- `--watch-namespace "albert, bb, freddie"` have the operator watch for - changes in the `albert`, `bb` and `freddie` namespaces only + +- `-n king` install the PG4K operator into the `king` namespace +- `--version 1.23` install the latest patch version for minor version 1.23 +- `--replicas 3` install the operator with 3 replicas +- `--watch-namespace "albert, bb, freddie"` have the operator watch for + changes in the `albert`, `bb` and `freddie` namespaces only ### Status @@ -210,15 +234,15 @@ cluster, including: from the `Current LSN` field in the instances status as it is taken at two different time intervals. -```shell +```sh kubectl cnp status sandbox ``` -```shell +```output Cluster Summary Name: default/sandbox System ID: 7423474350493388827 -PostgreSQL Image: quay.io/enterprisedb/postgresql:17.0 +PostgreSQL Image: docker.enterprisedb.com/k8s_enterprise/edb-postgres-extended:16.4 Primary instance: sandbox-1 Primary start time: 2024-10-08 18:31:57 +0000 UTC (uptime 1m14s) Status: Cluster in healthy state @@ -248,15 +272,15 @@ sandbox-3 0/604DE38 Standby (async) OK BestEffort 1.24.1 k If you require more detailed status information, use the `--verbose` option (or `-v` for short). The level of detail increases each time the flag is repeated: -```shell +```sh kubectl cnp status sandbox --verbose ``` -```shell +```output Cluster Summary Name: default/sandbox System ID: 7423474350493388827 -PostgreSQL Image: quay.io/enterprisedb/postgresql:17.0 +PostgreSQL Image: docker.enterprisedb.com/k8s_enterprise/edb-postgres-extended:16.4 Primary instance: sandbox-1 Primary start time: 2024-10-08 18:31:57 +0000 UTC (uptime 2m4s) Status: Cluster in healthy state @@ -311,13 +335,13 @@ The command also supports output in `yaml` and `json` format. The meaning of this command is to `promote` a pod in the cluster to primary, so you can start with maintenance work or test a switch-over situation in your cluster -```shell +```sh kubectl cnp promote cluster-example cluster-example-2 ``` Or you can use the instance node number to promote -```shell +```sh kubectl cnp promote cluster-example 2 ``` @@ -329,19 +353,19 @@ a TLS authentication certificate. To get a certificate, you need to provide a name for the secret to store the credentials, the cluster name, and a user for this certificate -```shell +```sh kubectl cnp certificate cluster-cert --cnp-cluster cluster-example --cnp-user appuser ``` -After the secret is created, you can get it using `kubectl` +After the secret it's created, you can get it using `kubectl` -```shell +```sh kubectl get secret cluster-cert ``` And the content of the same in plain text using the following commands: -```shell +```sh kubectl get secret cluster-cert -o json | jq -r '.data | map(@base64d) | .[]' ``` @@ -358,7 +382,7 @@ The `kubectl cnp restart` command can be used in two cases: the cluster's primary or deleting and recreating the pod if it is a replica. -```shell +```sh # this command will restart a whole cluster in a rollout fashion kubectl cnp restart [clusterName] @@ -382,7 +406,7 @@ to cluster dependent objects, such as ConfigMaps containing custom monitoring qu The following command will reload all configurations for a given cluster: -```shell +```sh kubectl cnp reload [cluster_name] ``` @@ -407,13 +431,13 @@ all the cluster in the list. If you want to set in maintenance all the PostgreSQL in your Kubernetes cluster, just need to write the following command: -```shell +```sh kubectl cnp maintenance set --all-namespaces ``` And you'll have the list of all the cluster to update -```shell +```output The following are the new values for the clusters Namespace Cluster Name Maintenance reusePVC --------- ------------ ----------- -------- @@ -461,36 +485,36 @@ default time-stamped filename is created for the zip file. !!! Note The report plugin obeys `kubectl` conventions, and will look for objects constrained - by namespace. The CNP Operator will generally not be installed in the same + by namespace. The PG4K Operator will generally not be installed in the same namespace as the clusters. E.g. the default installation namespace is postgresql-operator-system -```shell +```sh kubectl cnp report operator -n ``` results in -```shell +```output Successfully written report to "report_operator_.zip" (format: "yaml") ``` With the `-f` flag set: -```shell +```sh kubectl cnp report operator -n -f reportRedacted.zip ``` Unzipping the file will produce a time-stamped top-level folder to keep the directory tidy: -```shell +```sh unzip reportRedacted.zip ``` will result in: -```shell +```output Archive: reportRedacted.zip creating: report_operator_/ creating: report_operator_/manifests/ @@ -506,7 +530,7 @@ Archive: reportRedacted.zip If you activated the `--logs` option, you'd see an extra subdirectory: -```shell +```output Archive: report_operator_.zip creating: report_operator_/operator-logs/ @@ -519,14 +543,14 @@ Archive: report_operator_.zip In all cases, it will also try to get the CURRENT operator logs. If current and previous logs are available, it will show them both. -``` json +```output ====== Begin of Previous Log ===== -2023-03-28T12:56:41.251711811Z {"level":"info","ts":"2023-03-28T12:56:41Z","logger":"setup","msg":"Starting EDB Postgres for Kubernetes Operator","version":"1.19.1","build":{"Version":"1.19.0+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} +2023-03-28T12:56:41.251711811Z {"level":"info","ts":"2023-03-28T12:56:41Z","logger":"setup","msg":"Starting EDB Postgres for Kubernetes Operator","version":"1.24.1","build":{"Version":"1.24.1+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} 2023-03-28T12:56:41.251851909Z {"level":"info","ts":"2023-03-28T12:56:41Z","logger":"setup","msg":"Starting pprof HTTP server","addr":"0.0.0.0:6060"} ====== End of Previous Log ===== -2023-03-28T12:57:09.854306024Z {"level":"info","ts":"2023-03-28T12:57:09Z","logger":"setup","msg":"Starting EDB Postgres for Kubernetes Operator","version":"1.19.1","build":{"Version":"1.19.0+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} +2023-03-28T12:57:09.854306024Z {"level":"info","ts":"2023-03-28T12:57:09Z","logger":"setup","msg":"Starting EDB Postgres for Kubernetes Operator","version":"1.24.1","build":{"Version":"1.24.1+dev107","Commit":"cc9bab17","Date":"2023-03-28"}} 2023-03-28T12:57:09.854363943Z {"level":"info","ts":"2023-03-28T12:57:09Z","logger":"setup","msg":"Starting pprof HTTP server","addr":"0.0.0.0:6060"} ``` @@ -535,7 +559,7 @@ and `====== End …` guards, with no content inside. You can verify that the confidential information is REDACTED by default: -```shell +```sh cd report_operator_/manifests/ head postgresql-operator-ca-secret.yaml ``` @@ -554,18 +578,18 @@ metadata: With the `-S` (`--stopRedaction`) option activated, secrets are shown: -```shell +```sh kubectl cnp report operator -n -f reportNonRedacted.zip -S ``` You'll get a reminder that you're about to view confidential information: -```shell +```output WARNING: secret Redaction is OFF. Use it with caution Successfully written report to "reportNonRedacted.zip" (format: "yaml") ``` -```shell +```sh unzip reportNonRedacted.zip head postgresql-operator-ca-secret.yaml ``` @@ -603,7 +627,7 @@ so the `-S` is disabled. Usage: -```shell +```sh kubectl cnp report cluster [flags] ``` @@ -611,17 +635,17 @@ Note that, unlike the `operator` sub-command, for the `cluster` sub-command you need to provide the cluster name, and very likely the namespace, unless the cluster is in the default one. -```shell +```sh kubectl cnp report cluster example -f report.zip -n example_namespace ``` and then: -```shell +```sh unzip report.zip ``` -```shell +```output Archive: report.zip creating: report_cluster_example_/ creating: report_cluster_example_/manifests/ @@ -633,21 +657,21 @@ Archive: report.zip Remember that you can use the `--logs` flag to add the pod and job logs to the ZIP. -```shell +```sh kubectl cnp report cluster example -n example_namespace --logs ``` will result in: -```shell +```output Successfully written report to "report_cluster_example_.zip" (format: "yaml") ``` -```shell +```sh unzip report_cluster_.zip ``` -```shell +```output Archive: report_cluster_example_.zip creating: report_cluster_example_/ creating: report_cluster_example_/manifests/ @@ -686,14 +710,14 @@ Successfully written report to "report_operator_.zip" (format: "yaml" You can find the OpenShift-related files in the `openshift` sub-folder: -```shell +```sh unzip report_operator_.zip cd report_operator_/ cd openshift head clusterserviceversions.yaml ``` -```text +```yaml apiVersion: operators.coreos.com/v1alpha1 items: - apiVersion: operators.coreos.com/v1alpha1 @@ -726,7 +750,7 @@ the `-h` flag: `kubectl cnp logs cluster -h` The `logs` command will display logs in JSON-lines format, unless the -`--timestamps` flag is used, in which case, a human readable timestamp will be +`--timestamps` flag is used, in which case, a human-readable timestamp will be prepended to each line. In this case, lines will no longer be valid JSON, and tools such as `jq` may not work as desired. @@ -749,7 +773,7 @@ The `--tail` flag can be used to specify how many log lines will be retrieved from each pod in the cluster. By default, the `logs cluster` sub-command will display all the logs from each pod in the cluster. If combined with the "follow" flag `-f`, the number of logs specified by `--tail` will be retrieved until the -current time, and and from then the new logs will be followed. +current time, and from then the new logs will be followed. NOTE: unlike other `cnp` plugin commands, the `-f` is used to denote "follow" rather than specify a file. This keeps with the convention of `kubectl logs`, @@ -757,24 +781,24 @@ which takes `-f` to mean the logs should be followed. Usage: -```shell +```sh kubectl cnp logs cluster [flags] ``` Using the `-f` option to follow: -```shell +```sh kubectl cnp report cluster cluster-example -f ``` Using `--tail` option to display 3 lines from each pod and the `-f` option to follow: -```shell +```sh kubectl cnp report cluster cluster-example -f --tail 3 ``` -``` json +```output {"level":"info","ts":"2023-06-30T13:37:33Z","logger":"postgres","msg":"2023-06-30 13:37:33.142 UTC [26] LOG: ending log output to stderr","source":"/controller/log/postgres","logging_pod":"cluster-example-3"} {"level":"info","ts":"2023-06-30T13:37:33Z","logger":"postgres","msg":"2023-06-30 13:37:33.142 UTC [26] HINT: Future log output will go to log destination \"csvlog\".","source":"/controller/log/postgres","logging_pod":"cluster-example-3"} … @@ -783,8 +807,8 @@ kubectl cnp report cluster cluster-example -f --tail 3 With the `-o` option omitted, and with `--output` specified: -``` sh -kubectl cnp logs cluster cluster-example --output my-cluster.log +```console +$ kubectl cnp logs cluster cluster-example --output my-cluster.log Successfully written logs to "my-cluster.log" ``` @@ -797,7 +821,7 @@ into a human-readable output, and attempts to sort the entries by timestamp. It can be used in combination with `kubectl cnp logs cluster`, as shown in the following example: -``` sh +```console $ kubectl cnp logs cluster cluster-example | kubectl cnp logs pretty 2024-10-15T17:35:00.336 INFO cluster-example-1 instance-manager Starting EDB Postgres for Kubernetes Instance Manager 2024-10-15T17:35:00.336 INFO cluster-example-1 instance-manager Checking for free disk space for WALs before starting PostgreSQL @@ -807,10 +831,10 @@ $ kubectl cnp logs cluster cluster-example | kubectl cnp logs pretty ``` Alternatively, it can be used in combination with other commands that produce -cnp logs in JSON format, such as `stern`, or `kubectl logs`, as in the +PG4K logs in JSON format, such as `stern`, or `kubectl logs`, as in the following example: -``` sh +```console $ kubectl logs cluster-example-1 | kubectl cnp logs pretty 2024-10-15T17:35:00.336 INFO cluster-example-1 instance-manager Starting EDB Postgres for Kubernetes Instance Manager 2024-10-15T17:35:00.336 INFO cluster-example-1 instance-manager Checking for free disk space for WALs before starting PostgreSQL @@ -824,7 +848,7 @@ to display logs for specific pods or loggers, or to filter logs by severity level. Here's an example: -``` sh +```console $ kubectl cnp logs cluster cluster-example | kubectl cnp logs pretty --pods cluster-example-1 --loggers postgres --log-level info 2024-10-15T17:35:00.509 INFO cluster-example-1 postgres 2024-10-15 17:35:00.509 UTC [29] LOG: redirecting log output to logging collector process 2024-10-15T17:35:00.509 INFO cluster-example-1 postgres 2024-10-15 17:35:00.509 UTC [29] HINT: Future log output will appear in directory "/controller/log"... @@ -841,7 +865,7 @@ mode. The sub-command will add a group separator line, `---`, at the end of each sorted group. The size of the grouping can be configured via the `--sorting-group-size` flag (default: 1000), as illustrated in the following example: -``` sh +```console $ kubectl cnp logs cluster cluster-example | kubectl cnp logs pretty --sorting-group-size=3 2024-10-15T17:35:20.426 INFO cluster-example-2 instance-manager Starting EDB Postgres for Kubernetes Instance Manager 2024-10-15T17:35:20.426 INFO cluster-example-2 instance-manager Checking for free disk space for WALs before starting PostgreSQL @@ -875,14 +899,14 @@ detached PVCs. Usage: -``` +```sh kubectl cnp destroy [CLUSTER_NAME] [INSTANCE_ID] ``` The following example removes the `cluster-example-2` pod and the associated PVCs: -``` +```sh kubectl cnp destroy cluster-example 2 ``` @@ -901,7 +925,7 @@ instance. You can hibernate a cluster with: -``` +```sh kubectl cnp hibernate on ``` @@ -924,13 +948,13 @@ available status, including content from `pg_controldata`. In case of error the operator will not be able to revert the procedure. You can still force the operation with: -``` +```sh kubectl cnp hibernate on cluster-example --force ``` A hibernated cluster can be resumed with: -``` +```sh kubectl cnp hibernate off ``` @@ -938,7 +962,7 @@ Once the cluster has been hibernated, it's possible to show the last configuration and the status that PostgreSQL had after it was shut down. That can be done with: -``` +```sh kubectl cnp hibernate status ``` @@ -947,7 +971,7 @@ kubectl cnp hibernate status Pgbench can be run against an existing PostgreSQL cluster with following command: -``` +```sh kubectl cnp pgbench -- --time 30 --client 1 --jobs 1 ``` @@ -958,7 +982,7 @@ details. fio can be run on an existing storage class with following command: -``` +```sh kubectl cnp fio -n ``` @@ -976,20 +1000,20 @@ an existing Postgres cluster by creating a new `Backup` resource. The following example requests an on-demand backup for a given cluster: -```shell +```sh kubectl cnp backup [cluster_name] ``` or, if using volume snapshots: -```shell +```sh kubectl cnp backup [cluster_name] -m volumeSnapshot ``` The created backup will be named after the request time: -```shell -kubectl cnp backup cluster-example +```console +$ kubectl cnp backup cluster-example backup/cluster-example-20230121002300 created ``` @@ -1002,7 +1026,7 @@ to request an online/hot backup or an offline/cold one: additionally, you can also tune online backups by explicitly setting the `--immediate-checkpoint` and `--wait-for-archive` options. -The ["Backup" section](./backup.md) contains more information about +The ["Backup" section](./backup.md#backup) contains more information about the configuration settings. ### Launching psql @@ -1015,8 +1039,8 @@ it from the actual pod. This means that you will be using the `postgres` user. As you will be connecting as `postgres` user, in production environments this method should be used with extreme care, by authorized personnel only. -```shell -kubectl cnp psql cluster-example +```console +$ kubectl cnp psql cluster-example psql (17.0 (Debian 17.0-1.pgdg110+1)) Type "help" for help. @@ -1027,8 +1051,9 @@ postgres=# By default, the command will connect to the primary instance. The user can select to work against a replica by using the `--replica` option: -```shell -kubectl cnp psql --replica cluster-example +```console +$ kubectl cnp psql --replica cluster-example + psql (17.0 (Debian 17.0-1.pgdg110+1)) Type "help" for help. @@ -1050,7 +1075,7 @@ When connecting to instances running on OpenShift, you must explicitly pass a username to the `psql` command, because of a [security measure built into OpenShift](https://cloud.redhat.com/blog/a-guide-to-openshift-and-uids): -```shell +```sh kubectl cnp psql cluster-example -- -U postgres ``` !!! @@ -1075,7 +1100,7 @@ Kubernetes deployment. !!! Important Deployment of pgAdmin in Kubernetes production environments is beyond the - scope of this document and, more broadly, of the CloudNativePG project. + scope of this document and, more broadly, of the EDB Postgres for Kubernetes project. However, **for the purposes of demonstration and evaluation**, EDB Postgres for Kubernetes offers a suitable solution. The `cnp` plugin implements the `pgadmin4` @@ -1164,13 +1189,13 @@ kubectl cnp publication create \ There are two primary use cases: -- With `--external-cluster`: Use this option to create a publication on an - external cluster (i.e. defined in the `externalClusters` stanza). The commands - will be issued from the ``, but the publication will be for the - data in ``. +- With `--external-cluster`: Use this option to create a publication on an + external cluster (i.e. defined in the `externalClusters` stanza). The commands + will be issued from the ``, but the publication will be for the + data in ``. -- Without `--external-cluster`: Use this option to create a publication in the - `` PostgreSQL `Cluster` (by default, the `app` database). +- Without `--external-cluster`: Use this option to create a publication in the + `` PostgreSQL `Cluster` (by default, the `app` database). !!! Warning When connecting to an external cluster, ensure that the specified user has @@ -1179,11 +1204,11 @@ There are two primary use cases: You have several options, similar to the [`CREATE PUBLICATION`](https://www.postgresql.org/docs/current/sql-createpublication.html) command, to define the group of tables to replicate. Notable options include: -- If you specify the `--all-tables` option, you create a publication `FOR ALL TABLES`. -- Alternatively, you can specify multiple occurrences of: - - `--table`: Add a specific table (with an expression) to the publication. - - `--schema`: Include all tables in the specified database schema (available - from PostgreSQL 15). +- If you specify the `--all-tables` option, you create a publication `FOR ALL TABLES`. +- Alternatively, you can specify multiple occurrences of: + - `--table`: Add a specific table (with an expression) to the publication. + - `--schema`: Include all tables in the specified database schema (available + from PostgreSQL 15). The `--dry-run` option enables you to preview the SQL commands that the plugin will execute. @@ -1204,7 +1229,7 @@ to `source-cluster`. We can run: -``` sh +```sh kubectl cnp publication create destination-cluster \ --external-cluster=source-cluster --all-tables ``` @@ -1214,7 +1239,7 @@ the SQL commands on the `destination-cluster`. Or instead, we can run: -``` sh +```sh kubectl cnp publication create source-cluster \ --publication=app --all-tables ``` @@ -1299,7 +1324,7 @@ As in the section on publications, we have a `source-cluster` and a The following command: -``` sh +```sh kubectl cnp subscription create destination-cluster \ --external-cluster=source-cluster \ --publication=app --subscription=app @@ -1373,7 +1398,7 @@ subscription, both called `app`, are already present. The following command will synchronize the sequences involved in the `app` subscription, from the source cluster into the destination cluster. -``` sh +```sh kubectl cnp subscription sync-sequences destination-cluster \ --subscription=app ``` @@ -1388,4 +1413,119 @@ kubectl cnp subscription sync-sequences destination-cluster \ The `cnp` plugin can be easily integrated in [K9s](https://k9scli.io/), a popular terminal-based UI to interact with Kubernetes clusters. -See [`k9s/plugins.yml`](../samples/k9s/plugins.yml) for details. +See [`k9s/plugins.yml`](samples/k9s/plugins.yml) for details. + +## Permissions required by the plugin + +The plugin requires a set of Kubernetes permissions that depends on the command +to execute. These permissions may affect resources and sub-resources like Pods, +PDBs, PVCs, and enable actions like `get`, `delete`, `patch`. The following +table contains the full details: + +| Command | Resource Permissions | +| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| backup | clusters: get
backups: create | +| certificate | clusters: get
secrets: get,create | +| destroy | pods: get,delete
jobs: delete,list
PVCs: list,delete,update | +| fencing | clusters: get,patch
pods: get | +| fio | PVCs: create
configmaps: create
deployment: create | +| hibernate | clusters: get,patch,delete
pods: list,get,delete
pods/exec: create
jobs: list
PVCs: get,list,update,patch,delete | +| install | none | +| logs | clusters: get
pods: list
pods/log: get | +| maintenance | clusters: get,patch,list
| +| pgadmin4 | clusters: get
configmaps: create
deployments: create
services: create
secrets: create | +| pgbench | clusters: get
jobs: create
| +| promote | clusters: get
clusters/status: patch
pods: get | +| psql | pods: get,list
pods/exec: create | +| publication | clusters: get
pods: get,list
pods/exec: create | +| reload | clusters: get,patch | +| report cluster | clusters: get
pods: list
pods/log: get
jobs: list
events: list
PVCs: list | +| report operator | configmaps: get
deployments: get
events: list
pods: list
pods/log: get
secrets: get
services: get
mutatingwebhookconfigurations: list[^1]
validatingwebhookconfigurations: list[^1]
If OLM is present on the K8s cluster, also:
clusterserviceversions: list
installplans: list
subscriptions: list | +| restart | clusters: get,patch
pods: get,delete | +| status | clusters: get
pods: list
pods/exec: create
pods/proxy: create
PDBs: list | +| subscription | clusters: get
pods: get,list
pods/exec: create | +| version | none | + +[^1]: The permissions are cluster scope ClusterRole resources. + +///Footnotes Go Here/// + +Additionally, assigning the `list` permission on the `clusters` will enable +autocompletion for multiple commands. + +### Role examples + +It is possible to create roles with restricted permissions. +The following example creates a role that only has access to the cluster logs: + +```yaml +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cnp-log +rules: + - verbs: + - get + apiGroups: + - postgresql.k8s.enterprisedb.io + resources: + - clusters + - verbs: + - list + apiGroups: + - '' + resources: + - pods + - verbs: + - get + apiGroups: + - '' + resources: + - pods/log +``` + +The next example shows a role with the minimal permissions required to get +the cluster status using the plugin's `status` command: + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + name: cnp-status +rules: + - verbs: + - get + apiGroups: + - postgresql.k8s.enterprisedb.io + resources: + - clusters + - verbs: + - list + apiGroups: + - '' + resources: + - pods + - verbs: + - create + apiGroups: + - '' + resources: + - pods/exec + - verbs: + - create + apiGroups: + - '' + resources: + - pods/proxy + - verbs: + - list + apiGroups: + - policy + resources: + - poddisruptionbudgets +``` + +!!! Important + Keeping the verbs restricted per `resources` and per `apiGroups` helps to + prevent inadvertently granting more than intended permissions. diff --git a/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx b/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx index cf7c1cef737..d397620c9ea 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/labels_annotations.mdx @@ -198,7 +198,7 @@ These predefined annotations are managed by EDB Postgres for Kubernetes. risk. `k8s.enterprisedb.io/skipWalArchiving` -: When set to `true` on a `Cluster` resource, the operator disables WAL archiving. +: When set to `enabled` on a `Cluster` resource, the operator disables WAL archiving. This will set `archive_mode` to `off` and require a restart of all PostgreSQL instances. Use at your own risk. diff --git a/product_docs/docs/postgres_for_kubernetes/1/license_keys.mdx b/product_docs/docs/postgres_for_kubernetes/1/license_keys.mdx index ef6c3994c98..e0c378f213a 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/license_keys.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/license_keys.mdx @@ -3,11 +3,11 @@ title: 'License and License keys' originalFilePath: 'src/license_keys.md' --- -A license key is always required for the operator to work. +License keys are a legacy management mechanism for EDB Postgres for Kubernetes. You do not need a license key if you have installed using an EDB subscription token, and in this case, the licensing commands in this section can be ignored. -The only exception is when you run the operator with Community PostgreSQL: -in this case, if the license key is unset, a cluster will be started with the default -trial license - which automatically expires after 30 days. +If you are not using an EDB subscription token and installing from public repositories, then you will need a license key. The only exception is when you run the operator with Community PostgreSQL: in this case, if the license key is unset, a cluster will be started with the default trial license - which automatically expires after 30 days. This is not the recommended way of trialing EDB Postgres for Kubernetes - see the [installation guide](installation_upgrade.md) for the recommended options. + +The following documentation is only for users who have installed the operator using a license key. ## Company level license keys diff --git a/product_docs/docs/postgres_for_kubernetes/1/logging.mdx b/product_docs/docs/postgres_for_kubernetes/1/logging.mdx index ace768a7e17..6a2cdd3a3f1 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/logging.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/logging.mdx @@ -39,10 +39,10 @@ You can configure the log level for the instance pods in the cluster specification using the `logLevel` option. Available log levels are: `error`, `warning`, `info` (default), `debug`, and `trace`. -!!!Important - Currently, the log level can only be set at the time the instance starts. - Changes to the log level in the cluster specification after the cluster has - started will only apply to new pods, not existing ones. +!!! Important + Currently, the log level can only be set at the time the instance starts. + Changes to the log level in the cluster specification after the cluster has + started will only apply to new pods, not existing ones. ## Operator Logs @@ -303,6 +303,6 @@ the `logger` field indicating the process that produced them. The possible - `wal-restore`: logs from the `wal-restore` subcommand of the instance manager - `instance-manager`: from the [PostgreSQL instance manager](./instance_manager.md) -With the exception of `postgres` and `edb_audit`, which follows a specific structure, all other -`logger` values contain the `msg` field with the escaped message that is +With the exception of `postgres` and `edb_audit`, which follows a specific structure, +all other `logger` values contain the `msg` field with the escaped message that is logged. diff --git a/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx b/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx new file mode 100644 index 00000000000..14ce50caae0 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/logical_replication.mdx @@ -0,0 +1,447 @@ +--- +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). +Logical replication replicates data objects and their changes based on a +defined replication identity, typically the primary key. + +Logical replication uses a publish-and-subscribe model, where subscribers +connect to publications on a publisher node. Subscribers pull data changes from +these publications and can re-publish them, enabling cascading replication and +complex topologies. + +This flexible model is particularly useful for: + +- Online data migrations +- Live PostgreSQL version upgrades +- Data distribution across systems +- Real-time analytics +- Integration with external applications + +!!! Info + For more details, examples, and limitations, please refer to the + [official PostgreSQL documentation on Logical Replication](https://www.postgresql.org/docs/current/logical-replication.html). + +**EDB Postgres for Kubernetes** enhances this capability by providing declarative support for +key PostgreSQL logical replication objects: + +- **Publications** via the `Publication` resource +- **Subscriptions** via the `Subscription` resource + +## Publications + +In PostgreSQL's publish-and-subscribe replication model, a +[**publication**](https://www.postgresql.org/docs/current/logical-replication-publication.html) +is the source of data changes. It acts as a logical container for the change +sets (also known as *replication sets*) generated from one or more tables within +a database. Publications can be defined on any PostgreSQL 10+ instance acting +as the *publisher*, including instances managed by popular DBaaS solutions in the +public cloud. Each publication is tied to a single database and provides +fine-grained control over which tables and changes are replicated. + +For publishers outside Kubernetes, you can [create publications using SQL](https://www.postgresql.org/docs/current/sql-createpublication.html) +or leverage the [`cnp publication create` plugin command](kubectl-plugin.md#logical-replication-publications). + +When managing `Cluster` objects with **EDB Postgres for Kubernetes**, PostgreSQL publications +can be defined declaratively through the `Publication` resource. + +!!! Info + Please refer to the [API reference](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-Publication) + for the full list of attributes you can define for each `Publication` object. + +Suppose you have a cluster named `freddie` and want to replicate all tables in +the `app` database. Here's a `Publication` manifest: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Publication +metadata: + name: freddie-publisher +spec: + cluster: + name: freddie + dbname: app + name: publisher + target: + allTables: true +``` + +In the above example: + +- The publication object is named `freddie-publisher` (`metadata.name`). +- The publication is created via the primary of the `freddie` cluster + (`spec.cluster.name`) with name `publisher` (`spec.name`). +- It includes all tables (`spec.target.allTables: true`) from the `app` + database (`spec.dbname`). + +!!! Important + While `allTables` simplifies configuration, PostgreSQL offers fine-grained + control for replicating specific tables or targeted data changes. For advanced + configurations, consult the [PostgreSQL documentation](https://www.postgresql.org/docs/current/logical-replication.html). + Additionally, refer to the [EDB Postgres for Kubernetes API reference](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-PublicationTarget) + for details on declaratively customizing replication targets. + +### Required Fields in the `Publication` Manifest + +The following fields are required for a `Publication` object: + +- `metadata.name`: Unique name for the Kubernetes `Publication` object. +- `spec.cluster.name`: Name of the PostgreSQL cluster. +- `spec.dbname`: Database name where the publication is created. +- `spec.name`: Publication name in PostgreSQL. +- `spec.target`: Specifies the tables or changes to include in the publication. + +The `Publication` object must reference a specific `Cluster`, determining where +the publication will be created. It is managed by the cluster's primary instance, +ensuring the publication is created or updated as needed. + +### Reconciliation and Status + +After creating a `Publication`, EDB Postgres for Kubernetes manages it on the primary +instance of the specified cluster. Following a successful reconciliation cycle, +the `Publication` status will reflect the following: + +- `applied: true`, indicates the configuration has been successfully applied. +- `observedGeneration` matches `metadata.generation`, confirming the applied + configuration corresponds to the most recent changes. + +If an error occurs during reconciliation, `status.applied` will be `false`, and +an error message will be included in the `status.message` field. + +### Removing a publication + +The `publicationReclaimPolicy` field controls the behavior when deleting a +`Publication` object: + +- `retain` (default): Leaves the publication in PostgreSQL for manual + management. +- `delete`: Automatically removes the publication from PostgreSQL. + +Consider the following example: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Publication +metadata: + name: freddie-publisher +spec: + cluster: + name: freddie + dbname: app + name: publisher + target: + allTables: true + publicationReclaimPolicy: delete +``` + +In this case, deleting the `Publication` object also removes the `publisher` +publication from the `app` database of the `freddie` cluster. + +## Subscriptions + +In PostgreSQL's publish-and-subscribe replication model, a +[**subscription**](https://www.postgresql.org/docs/current/logical-replication-subscription.html) +represents the downstream component that consumes data changes. +A subscription establishes the connection to a publisher's database and +specifies the set of publications (one or more) it subscribes to. Subscriptions +can be created on any supported PostgreSQL instance acting as the *subscriber*. + +!!! Important + Since schema definitions are not replicated, the subscriber must have the + corresponding tables already defined before data replication begins. + +EDB Postgres for Kubernetes simplifies subscription management by enabling you to define them +declaratively using the `Subscription` resource. + +!!! Info + Please refer to the [API reference](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-Subscription) + for the full list of attributes you can define for each `Subscription` object. + +Suppose you want to replicate changes from the `publisher` publication on the +`app` database of the `freddie` cluster (*publisher*) to the `app` database of +the `king` cluster (*subscriber*). Here's an example of a `Subscription` +manifest: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Subscription +metadata: + name: freddie-to-king-subscription +spec: + cluster: + name: king + dbname: app + name: subscriber + externalClusterName: freddie + publicationName: publisher +``` + +In the above example: + +- The subscription object is named `freddie-to-king-subscriber` (`metadata.name`). +- The subscription is created in the `app` database (`spec.dbname`) of the + `king` cluster (`spec.cluster.name`), with name `subscriber` (`spec.name`). +- It connects to the `publisher` publication in the external `freddie` cluster, + referenced by `spec.externalClusterName`. + +To facilitate this setup, the `freddie` external cluster must be defined in the +`king` cluster's configuration. Below is an example excerpt showing how to +define the external cluster in the `king` manifest: + +```yaml +externalClusters: + - name: freddie + connectionParameters: + host: freddie-rw.default.svc + user: postgres + dbname: app +``` + +!!! Info + For more details on configuring the `externalClusters` section, see the + ["Bootstrap" section](bootstrap.md#the-externalclusters-section) of the + documentation. + +As you can see, a subscription can connect to any PostgreSQL database +accessible over the network. This flexibility allows you to seamlessly migrate +your data into Kubernetes with nearly zero downtime. It’s an excellent option +for transitioning from various environments, including popular cloud-based +Database-as-a-Service (DBaaS) platforms. + +### Required Fields in the `Subscription` Manifest + +The following fields are mandatory for defining a `Subscription` object: + +- `metadata.name`: A unique name for the Kubernetes `Subscription` object + within its namespace. +- `spec.cluster.name`: The name of the PostgreSQL cluster where the + subscription will be created. +- `spec.dbname`: The name of the database in which the subscription will be + created. +- `spec.name`: The name of the subscription as it will appear in PostgreSQL. +- `spec.externalClusterName`: The name of the external cluster, as defined in + the `spec.cluster.name` cluster's configuration. This references the + publisher database. +- `spec.publicationName`: The name of the publication in the publisher database + to which the subscription will connect. + +The `Subscription` object must reference a specific `Cluster`, determining +where the subscription will be managed. EDB Postgres for Kubernetes ensures that the +subscription is created or updated on the primary instance of the specified +cluster. + +### Reconciliation and Status + +After creating a `Subscription`, EDB Postgres for Kubernetes manages it on the primary +instance of the specified cluster. Following a successful reconciliation cycle, +the `Subscription` status will reflect the following: + +- `applied: true`, indicates the configuration has been successfully applied. +- `observedGeneration` matches `metadata.generation`, confirming the applied + configuration corresponds to the most recent changes. + +If an error occurs during reconciliation, `status.applied` will be `false`, and +an error message will be included in the `status.message` field. + +### Removing a subscription + +The `subscriptionReclaimPolicy` field controls the behavior when deleting a +`Subscription` object: + +- `retain` (default): Leaves the subscription in PostgreSQL for manual + management. +- `delete`: Automatically removes the subscription from PostgreSQL. + +Consider the following example: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Subscription +metadata: + name: freddie-to-king-subscription +spec: + cluster: + name: king + dbname: app + name: subscriber + externalClusterName: freddie + publicationName: publisher + subscriptionReclaimPolicy: delete +``` + +In this case, deleting the `Subscription` object also removes the `subscriber` +subscription from the `app` database of the `king` cluster. + +## Limitations + +Logical replication in PostgreSQL has some inherent limitations, as outlined in +the [official documentation](https://www.postgresql.org/docs/current/logical-replication-restrictions.html). +Notably, the following objects are not replicated: + +- **Database schema and DDL commands** +- **Sequence data** +- **Large objects** + +### Addressing Schema Replication + +The first limitation, related to schema replication, can be easily addressed +using EDB Postgres for Kubernetes' capabilities. For instance, you can leverage the `import` +bootstrap feature to copy the schema of the tables you need to replicate. +Alternatively, you can manually create the schema as you would for any +PostgreSQL database. + +### Handling Sequences + +While sequences are not automatically kept in sync through logical replication, +EDB Postgres for Kubernetes provides a solution to be used in live migrations. +You can use the [`cnp` plugin](kubectl-plugin.md#synchronizing-sequences) +to synchronize sequence values, ensuring consistency between the publisher and +subscriber databases. + +## Example of live migration and major Postgres upgrade with logical replication + +To highlight the powerful capabilities of logical replication, this example +demonstrates how to replicate data from a publisher database (`freddie`) +running PostgreSQL 16 to a subscriber database (`king`) running the latest +PostgreSQL version. This setup can be deployed in your Kubernetes cluster for +evaluation and hands-on learning. + +This example illustrates how logical replication facilitates live migrations +and upgrades between PostgreSQL versions while ensuring data consistency. By +combining logical replication with EDB Postgres for Kubernetes, you can easily set up, +manage, and evaluate such scenarios in a Kubernetes environment. + +### Step 1: Setting Up the Publisher (`freddie`) + +The first step involves creating a `freddie` PostgreSQL cluster with version 16. +The cluster contains a single instance and includes an `app` database +initialized with a table, `n`, storing 10,000 numbers. A logical replication +publication named `publisher` is also configured to include all tables in the +database. + +Here’s the manifest for setting up the `freddie` cluster and its publication +resource: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: freddie +spec: + instances: 1 + + imageName: quay.io/enterprisedb/postgresql:16 + + storage: + size: 1Gi + + bootstrap: + initdb: + postInitApplicationSQL: + - CREATE TABLE n (i SERIAL PRIMARY KEY, m INTEGER) + - INSERT INTO n (m) (SELECT generate_series(1, 10000)) + - ALTER TABLE n OWNER TO app + + managed: + roles: + - name: app + login: true + replication: true +--- +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Publication +metadata: + name: freddie-publisher +spec: + cluster: + name: freddie + dbname: app + name: publisher + target: + allTables: true +``` + +### Step 2: Setting Up the Subscriber (`king`) + +Next, create the `king` PostgreSQL cluster, running the latest version of +PostgreSQL. This cluster initializes by importing the schema from the `app` +database on the `freddie` cluster using the external cluster configuration. A +`Subscription` resource, `freddie-to-king-subscription`, is then configured to +consume changes published by the `publisher` on `freddie`. + +Below is the manifest for setting up the `king` cluster and its subscription: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: king +spec: + instances: 1 + + storage: + size: 1Gi + + bootstrap: + initdb: + import: + type: microservice + schemaOnly: true + databases: + - app + source: + externalCluster: freddie + + externalClusters: + - name: freddie + connectionParameters: + host: freddie-rw.default.svc + user: app + dbname: app + password: + name: freddie-app + key: password +--- +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Subscription +metadata: + name: freddie-to-king-subscription +spec: + cluster: + name: king + dbname: app + name: subscriber + externalClusterName: freddie + publicationName: publisher +``` + +Once the `king` cluster is running, you can verify that the replication is +working by connecting to the `app` database and counting the records in the `n` +table. The following example uses the `psql` command provided by the `cnp` +plugin for simplicity: + +```console +kubectl cnp psql king -- app -qAt -c 'SELECT count(*) FROM n' +10000 +``` + +This command should return `10000`, confirming that the data from the `freddie` +cluster has been successfully replicated to the `king` cluster. + +Using the `cnp` plugin, you can also synchronize existing sequences to ensure +consistency between the publisher and subscriber. The example below +demonstrates how to synchronize a sequence for the `king` cluster: + +```console +kubectl cnp subscription sync-sequences king --subscription=subscriber +SELECT setval('"public"."n_i_seq"', 10000); + +10000 +``` + +This command updates the sequence `n_i_seq` in the `king` cluster to match the +current value, ensuring it is in sync with the source database. diff --git a/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx b/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx index 73a3ff65112..4e0c2a1958a 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/monitoring.mdx @@ -220,7 +220,7 @@ cnp_collector_up{cluster="cluster-example"} 1 # HELP cnp_collector_postgres_version Postgres version # TYPE cnp_collector_postgres_version gauge -cnp_collector_postgres_version{cluster="cluster-example",full="17.0"} 17.0 +cnp_collector_postgres_version{cluster="cluster-example",full="17.2"} 17.2 # HELP cnp_collector_last_failed_backup_timestamp The last failed backup as a unix timestamp # TYPE cnp_collector_last_failed_backup_timestamp gauge 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 abde40cb577..d74b8942080 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/object_stores.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/object_stores.mdx @@ -146,10 +146,31 @@ spec: [...] ``` -!!! Important - Suppose you configure an Object Storage provider which uses a certificate signed with a private CA, - like when using OpenShift or MinIO via HTTPS. In that case, you need to set the option `endpointCA` - referring to a secret containing the CA bundle so that Barman can verify the certificate correctly. +### Using Object Storage with a private CA + +Suppose you configure an Object Storage provider which uses a certificate +signed with a private CA, for example when using OpenShift or MinIO via HTTPS. In that case, +you need to set the option `endpointCA` inside `barmanObjectStore` referring +to a secret containing the CA bundle, so that Barman can verify the certificate +correctly. +You can find instructions on creating a secret using your cert files in the +[certificates](certificates.md#example) document. +Once you have created the secret, you can populate the `endpointCA` as in the +following example: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +[...] +spec: + [...] + backup: + barmanObjectStore: + endpointURL: + endpointCA: + name: my-ca-secret + key: ca.crt +``` !!! Note If you want ConfigMaps and Secrets to be **automatically** reloaded by instances, you can @@ -190,7 +211,7 @@ On the other side, using both **Storage account access key** or **Storage accoun the credentials need to be stored inside a Kubernetes Secret, adding data entries only when needed. The following command performs that: -``` +```sh kubectl create secret generic azure-creds \ --from-literal=AZURE_STORAGE_ACCOUNT= \ --from-literal=AZURE_STORAGE_KEY= \ @@ -230,7 +251,7 @@ spec: When using the Azure Blob Storage, the `destinationPath` fulfills the following structure: -``` +```sh ://..core.windows.net/ ``` @@ -242,7 +263,7 @@ which is also called **storage account name**, is included in the used host name If you are using a different implementation of the Azure Blob Storage APIs, the `destinationPath` will have the following structure: -``` +```sh ://:// ``` diff --git a/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx b/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx index 8d41b90bbae..5f9ba25dd86 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/openshift.mdx @@ -227,6 +227,38 @@ If you are currently using `stable`, you have two options for moving off of it: ## Installation via web console +### Ensuring access to EDB private registry + +!!! Important + You'll need access to the private EDB repository where both the operator + and operand images are stored. Access requires a valid + [EDB subscription plan](https://www.enterprisedb.com/products/plans-comparison). + Please refer to ["Accessing EDB private image registries"](private_edb_registries.md) for further details. + +The OpenShift install will use pull secrets in order to access the +operand and operator images, which are held in a private repository. + +Once you have credentials to the private repository, you will need to create +a pull secret in the `openshift-operators` namespace, named: + +- `postgresql-operator-pull-secret`, for the EDB Postgres for Kubernetes operator images + +You can create each secret via the `oc create` command, as follows: + +```sh +oc create secret docker-registry postgresql-operator-pull-secret \ + -n openshift-operators --docker-server=docker.enterprisedb.com \ + --docker-username="@@REPOSITORY@@" \ + --docker-password="@@TOKEN@@" +``` + +where: + +- `@@REPOSITORY@@` is the name of the repository, as explained in ["Which repository to + choose?"](private_edb_registries.md#which-repository-to-choose) +- `@@TOKEN@@` is the repository token for your EDB account, as explained in + ["How to retrieve the token"](private_edb_registries.md#how-to-retrieve-the-token) + The EDB Postgres for Kubernetes operator can be found in the Red Hat OperatorHub directly from your OpenShift dashboard. 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 1cde5f5ef73..afb2fdad6ff 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 @@ -78,7 +78,7 @@ of the EDB Postgres for Kubernetes deployment in your Kubernetes infrastructure. ### Self-contained instance manager Instead of relying on an external tool to -coordinate PostgreSQL instances in the Kubernetes cluster pods, +coordinate PostgreSQL instances in the Kubernetes cluster pods, such as Patroni or Stolon, the operator injects the operator executable inside each pod, in a file named `/controller/manager`. The application is used to control the underlying @@ -139,14 +139,18 @@ PostgreSQL outside Kubernetes. This is particularly useful for DBaaS purposes. ### Database configuration -The operator is designed to manage a PostgreSQL cluster with a single -database. The operator transparently manages access to the database through -three Kubernetes services provisioned and managed for read-write, +The operator is designed to bootstrap a PostgreSQL cluster with a single +database. The operator transparently manages network access to the cluster +through three Kubernetes services provisioned and managed for read-write, read, and read-only workloads. Using the convention-over-configuration approach, the operator creates a database called `app`, by default owned by a regular Postgres user with the same name. You can specify both the database name and the user name, if -required. +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. Although no configuration is required to run the cluster, you can customize both PostgreSQL runtime configuration and PostgreSQL host-based @@ -246,7 +250,7 @@ includes integration with cert-manager. ### Certificate authentication for streaming replication -To authorize streaming replication connections from the standby servers, +To authorize streaming replication connections from the standby servers, the operator relies on TLS client certificate authentication. This method is used instead of relying on a password (and therefore a secret). @@ -309,16 +313,20 @@ workload, in this case PostgreSQL servers. This includes PostgreSQL minor release updates (security and bug fixes normally) as well as major online upgrades. -### Upgrade of the operator +### Operator Upgrade + +Upgrading the operator is seamless and can be done as a new deployment. After +upgrading the controller, a rolling update of all deployed PostgreSQL clusters +is initiated. You can choose to update all clusters simultaneously or +distribute their upgrades over time. -You can upgrade the operator seamlessly as a new deployment. Because of the instance -manager's injection, a change in the -operator doesn't require a change in the operand. -The operator can manage older versions of the operand. +Thanks to the instance manager's injection, upgrading the operator does not +require changes to the operand, allowing the operator to manage older versions +of it. -EDB Postgres for Kubernetes also supports [in-place updates of the instance manager](installation_upgrade.md#in-place-updates-of-the-instance-manager) -following an upgrade of the operator. In-place updates don't require a rolling -update (and subsequent switchover) of the cluster. +Additionally, EDB Postgres for Kubernetes supports [in-place updates of the instance manager](installation_upgrade.md#in-place-updates-of-the-instance-manager) +following an operator upgrade. In-place updates do not require a rolling update +or a subsequent switchover of the cluster. ### Upgrade of the managed workload @@ -379,8 +387,8 @@ user action. The operator transparently sets the `archive_command` to rely on `barman-cloud-wal-archive` to ship WAL files to the defined endpoint. You can decide the compression algorithm, as well as the number of parallel jobs to concurrently upload WAL files -in the archive. In addition, `Instance Manager` checks -the correctness of the archive destination by performing the `barman-cloud-check-wal-archive` +in the archive. In addition, `Instance Manager` checks +the correctness of the archive destination by performing the `barman-cloud-check-wal-archive` command before beginning to ship the first set of WAL files. ### PostgreSQL backups @@ -397,7 +405,7 @@ Base backups can be saved on: Base backups are defined at the cluster level, declaratively, through the `backup` parameter in the cluster definition. -You can define base backups in two ways: +You can define base backups in two ways: - On-demand, through the `Backup` custom resource definition - Scheduled, through the `ScheduledBackup`custom resource definition, using a cron-like syntax @@ -606,6 +614,15 @@ and makes the use of the underlying PostgreSQL resources more efficient. Instead of connecting directly to a PostgreSQL service, applications can now connect to the PgBouncer service and start reusing any existing connection. +### Logical Replication + +EDB Postgres for Kubernetes supports PostgreSQL's logical replication in a declarative manner +using `Publication` and `Subscription` custom resource definitions. + +Logical replication is particularly useful together with the import facility +for online data migrations (even from public DBaaS solutions) and major +PostgreSQL upgrades. + ### Integration with external backup tools for Kubernetes EDB Postgres for Kubernetes provides add-ons to integrate with: @@ -621,7 +638,7 @@ Moreover, the [external backup adapter add-on](addons.md#external-backup-adapter provides a generic interface to integrate EDB Postgres for Kubernetes in any third-party tool for backups. -## Level 4: Deep Insights +## Level 4: Deep insights Capability level 4 is about *observability*: monitoring, alerting, trending, and log processing. This might involve the use of external tools, 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 6c9e50a95ea..49373e83b2b 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/operator_conf.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/operator_conf.mdx @@ -38,21 +38,24 @@ 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 | -| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `EDB_LICENSE_KEY` | default license key (to be used only if the cluster does not define one, and preferably in the `Secret`) | -| `ENABLE_REDWOOD_BY_DEFAULT` | Enable the Redwood compatibility by default when using EPAS. | -| `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 | -| `PULL_SECRET_NAME` | name of an additional pull secret to be defined in the operator's namespace and to be used to download images | -| `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`) | -| `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 | -| `CERTIFICATE_DURATION` | Determines the lifetime of the generated certificates in days. Default is 90. | -| `EXPIRING_CHECK_THRESHOLD` | Determines the threshold, in days, for identifying a certificate as expiring. Default is 7. | -| `CREATE_ANY_SERVICE` | when set to `true`, will create `-any` service for the cluster. Default is `false` | -| `EXTERNAL_BACKUP_ADDON_CONFIGURATION` | Configuration for the `external-backup-adapter` add-on. (See ["Customizing the adapter" in Add-ons](addons.md#customizing-the-adapter)) | +| 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 | 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`. @@ -67,11 +70,13 @@ will ignore the configuration parameter. ## Defining an operator config map -The example below customizes the behavior of the operator, by defining a -default license key (namely a company key), the label/annotation names to be -inherited by the resources created by any `Cluster` object that is deployed -at a later time, and by enabling -[in-place updates for the instance manager](installation_upgrade.md#in-place-updates-of-the-instance-manager). +The example below customizes the behavior of the operator, by defining +a default license key (namely a company key), +the label/annotation names to be inherited by the resources created by +any `Cluster` object that is deployed at a later time, by enabling +[in-place updates for the instance +manager](installation_upgrade.md#in-place-updates-of-the-instance-manager), +and by spreading upgrades. ```yaml apiVersion: v1 @@ -80,15 +85,23 @@ metadata: name: postgresql-operator-controller-manager-config namespace: postgresql-operator-system data: + CLUSTERS_ROLLOUT_DELAY: '60' + ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES: 'true' + EDB_LICENSE_KEY: INHERITED_ANNOTATIONS: categories INHERITED_LABELS: environment, workload, app - ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES: 'true' + INSTANCES_ROLLOUT_DELAY: '10' ``` ## Defining an operator secret -The example below customizes the behavior of the operator, by defining a -default license key. +The example below customizes the behavior of the operator, by defining +a default license key (namely a company key), +the label/annotation names to be inherited by the resources created by +any `Cluster` object that is deployed at a later time, and by enabling +[in-place updates for the instance +manager](installation_upgrade.md#in-place-updates-of-the-instance-manager), +and by spreading upgrades. ```yaml apiVersion: v1 @@ -97,8 +110,13 @@ metadata: name: postgresql-operator-controller-manager-config namespace: postgresql-operator-system type: Opaque -data: +stringData: + CLUSTERS_ROLLOUT_DELAY: '60' + ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES: 'true' EDB_LICENSE_KEY: + INHERITED_ANNOTATIONS: categories + INHERITED_LABELS: environment, workload, app + INSTANCES_ROLLOUT_DELAY: '10' ``` ## Restarting the operator to reload configs 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 f6e241b5ead..03f6cca2fb8 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,8 +1,9 @@ --- -title: API Reference - v1.24.1 +title: API Reference - v1.24.2 originalFilePath: src/pg4k.v1.md navTitle: API Reference navigation: + - v1.24.2 - v1.24.1 - v1.24.0 - v1.23.5 @@ -105,9 +106,12 @@ navigation: - [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)
@@ -211,6 +215,43 @@ More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api- +
+ +## 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 @@ -276,6 +317,40 @@ More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api- +
+ +## Publication + +**Appears in:** + +

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 @@ -313,6 +388,40 @@ More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api- +
+ +## Subscription + +**Appears in:** + +

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 @@ -573,7 +682,7 @@ plugin for this backup

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

-tablespaceName [Required]
+tablespaceName
string @@ -886,13 +995,20 @@ parameter is omitted

The backup method being used

-online [Required]
+online
bool

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

+pluginMetadata
+map[string]string + + +

A map containing the plugin metadata

+ + @@ -1040,6 +1156,48 @@ enabling checksums on data pages (default: false)

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 @@ -1715,7 +1873,7 @@ https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ for more information.

-ephemeralVolumesSizeLimit [Required]
+ephemeralVolumesSizeLimit
EphemeralVolumesSizeLimitConfiguration @@ -1790,7 +1948,7 @@ the license agreement that comes with the operator.

externalClusters
-[]ExternalCluster +ExternalClusterList

The list of external clusters which are used in the configuration

@@ -1863,8 +2021,8 @@ advisable for any PostgreSQL cluster employed for development/staging purposes.

-plugins [Required]
-PluginConfigurationList +plugins
+PluginConfigurationList

The plugins configuration, containing @@ -1965,7 +2123,7 @@ any plugin to be loaded with the corresponding configuration

during a switchover or a failover

-lastPromotionToken [Required]
+lastPromotionToken
string @@ -2207,7 +2365,7 @@ This field is reported when .spec.failoverDelay is populated or dur

Image contains the image name used by the pods

-pluginStatus [Required]
+pluginStatus
[]PluginStatus @@ -2259,6 +2417,19 @@ 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 @@ -2297,6 +2468,18 @@ PostgreSQL cluster from an existing storage

+
+ +## 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 @@ -2319,197 +2502,312 @@ PostgreSQL cluster from an existing storage

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

EPASConfiguration contains EDB Postgres Advanced Server specific configurations

+

DatabaseSpec is the specification of a Postgresql Database

- - - -
FieldDescription
audit
-bool +
cluster [Required]
+core/v1.LocalObjectReference 		-

If true enables edb_audit logging

+

The corresponding cluster
tde
-TDEConfiguration +
ensure
+EnsureOption 		-

TDE configuration

+

Ensure the PostgreSQL database is present or absent - defaults to "present"
- -
- -## EmbeddedObjectMetadata - -**Appears in:** - -- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) - -

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

- - - - - +

The name inside PostgreSQL

+ - +

The owner

+ - -
FieldDescription
labels
-map[string]string +
name [Required]
+string 		- No description provided.
annotations
-map[string]string +
owner [Required]
+string 		- No description provided.
- -
- -## EnsureOption - -(Alias of `string`) - -**Appears in:** - -- [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 [Required]
-k8s.io/apimachinery/pkg/api/resource.Quantity +
template
+string 		-

Shm is the size limit of the shared memory volume

+

The name of the template from which to create the new database
temporaryData [Required]
-k8s.io/apimachinery/pkg/api/resource.Quantity +
encoding
+string 		-

TemporaryData is the size limit of the temporary data volume

+

The encoding (cannot be changed)
- -
- -## 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]
+
locale
string 		-

The server name, required

+

The locale (cannot be changed)
connectionParameters
-map[string]string +
locale_provider
+string 		-

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

+

The locale provider (cannot be changed)
sslCert
-core/v1.SecretKeySelector +
lc_collate
+string 		-

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

+

The LC_COLLATE (cannot be changed)
sslKey
-core/v1.SecretKeySelector +
lc_ctype
+string 		-

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

+

The LC_CTYPE (cannot be changed)
sslRootCert
-core/v1.SecretKeySelector +
icu_locale
+string 		-

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

+

The ICU_LOCALE (cannot be changed)
password
-core/v1.SecretKeySelector +
icu_rules
+string 		-

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.

+

The ICU_RULES (cannot be changed)
barmanObjectStore
-github.com/cloudnative-pg/barman-cloud/pkg/api.BarmanObjectStoreConfiguration +
builtin_locale
+string 		-

The configuration for the barman-cloud tool suite

+

The BUILTIN_LOCALE (cannot be changed)
- -
- -## ImageCatalogRef - -**Appears in:** - -- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) - -

ImageCatalogRef defines the reference to a major version in an ImageCatalog

- - - - - + + + + + + + + + + + + + + + + + + +
FieldDescription
TypedLocalObjectReference
+
collation_version
+string +		 +

The COLLATION_VERSION (cannot be changed)

+
isTemplate
+bool +		 +

True when the database is a template

+
allowConnections
+bool +		 +

True when connections to this database are allowed

+
connectionLimit
+int +		 +

Connection limit, -1 means no limit and -2 means the +database is not valid

+
tablespace
+string +		 +

The default tablespace of this database

+
databaseReclaimPolicy
+DatabaseReclaimPolicy +		 +

The policy for end-of-life maintenance of this 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

+
+ +
+ +## 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:** + +- [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

+
+ +
+ +## 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.) @@ -2608,6 +2906,26 @@ database right after is imported - to be used with extreme care 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.

+
@@ -2938,7 +3256,7 @@ It includes the type of service and its associated template specification.

Valid values are "rw", "r", and "ro", representing read-write, read, and read-only services.

-updateStrategy [Required]
+updateStrategy
ServiceUpdateStrategy @@ -2976,7 +3294,7 @@ Valid values are "rw", "r", and "ro", representing Valid values are "r", and "ro", representing read, and read-only services.

-additional [Required]
+additional
[]ManagedService @@ -3006,7 +3324,7 @@ not using the core data types.

-
FieldDescription
name [Required]
+
name
string 		@@ -3342,6 +3660,55 @@ the operator calls PgBouncer's PAUSE and RESUME comman
+
+ +## PluginConfiguration + +**Appears in:** + +

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

+
parameters
+map[string]string +		 +

Parameters is the configuration of the plugin

+
+ +
+ +## PluginConfigurationList + +(Alias of `[]github.com/EnterpriseDB/cloud-native-postgres/api/v1.PluginConfiguration`) + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

PluginConfigurationList represent a set of plugin with their +configuration parameters

+
## PluginStatus @@ -3370,7 +3737,7 @@ the operator calls PgBouncer's PAUSE and RESUME comman latest reconciliation loop

-capabilities [Required]
+capabilities
[]string @@ -3378,7 +3745,7 @@ latest reconciliation loop

plugin

-operatorCapabilities [Required]
+operatorCapabilities
[]string @@ -3386,7 +3753,7 @@ plugin

plugin regarding the reconciler

-walCapabilities [Required]
+walCapabilities
[]string @@ -3394,7 +3761,7 @@ plugin regarding the reconciler

plugin regarding the WAL management

-backupCapabilities [Required]
+backupCapabilities
[]string @@ -3402,7 +3769,15 @@ plugin regarding the WAL management

plugin regarding the Backup management

-status [Required]
+restoreJobHookCapabilities
+[]string + + +

RestoreJobHookCapabilities are the list of capabilities of the +plugin regarding the RestoreJobHook management

+ + +status
string @@ -3806,6 +4181,225 @@ the primary server of the cluster as part of rolling updates

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

+
+ +## 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 @@ -3898,7 +4492,7 @@ cluster

- - - - -
FieldDescription
self [Required]
+
self
string 		@@ -3906,7 +4500,7 @@ cluster

or a replica cluster, comparing it with primary
primary [Required]
+
primary
string 		@@ -3921,7 +4515,7 @@ topology specified in externalClusters

The name of the external cluster which is the replication origin
enabled [Required]
+
enabled
bool 		@@ -3931,7 +4525,7 @@ object store or via streaming through pg_basebackup. Refer to the Replica clusters page of the documentation for more information.
promotionToken [Required]
+
promotionToken
string 		@@ -3939,7 +4533,7 @@ Refer to the Replica clusters page of the documentation for more information.
minApplyDelay [Required]
+
minApplyDelay
meta/v1.Duration 		@@ -4647,6 +5241,132 @@ Size cannot be decreased.
+
+ +## 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 @@ -4794,6 +5514,20 @@ only useful for priority-based synchronous replication).

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

+ + diff --git a/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.24.2.mdx b/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.24.2.mdx new file mode 100644 index 00000000000..7faef1c5f56 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/pg4k.v1/v1.24.2.mdx @@ -0,0 +1,5724 @@ +--- +title: API Reference - v1.24.2 +navTitle: v1.24.2 +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 + +

Backup is the Schema for the backups API

+ + + + + + + + + + + + + + + + +
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 + +**Appears in:** + +

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 + +**Appears in:** + +

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

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

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

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

+
azurePVCUpdateEnabled
+bool +		 +

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

+
image
+string +		 +

Image contains the image name used by the pods

+
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

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

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

The corresponding cluster

+
ensure
+EnsureOption +		 +

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

+
name [Required]
+string +		 +

The name inside PostgreSQL

+
owner [Required]
+string +		 +

The owner

+
template
+string +		 +

The name of the template from which to create the new database

+
encoding
+string +		 +

The encoding (cannot be changed)

+
locale
+string +		 +

The locale (cannot be changed)

+
locale_provider
+string +		 +

The locale provider (cannot be changed)

+
lc_collate
+string +		 +

The LC_COLLATE (cannot be changed)

+
lc_ctype
+string +		 +

The LC_CTYPE (cannot be changed)

+
icu_locale
+string +		 +

The ICU_LOCALE (cannot be changed)

+
icu_rules
+string +		 +

The ICU_RULES (cannot be changed)

+
builtin_locale
+string +		 +

The BUILTIN_LOCALE (cannot be changed)

+
collation_version
+string +		 +

The COLLATION_VERSION (cannot be changed)

+
isTemplate
+bool +		 +

True when the database is a template

+
allowConnections
+bool +		 +

True when connections to this database are allowed

+
connectionLimit
+int +		 +

Connection limit, -1 means no limit and -2 means the +database is not valid

+
tablespace
+string +		 +

The default tablespace of this database

+
databaseReclaimPolicy
+DatabaseReclaimPolicy +		 +

The policy for end-of-life maintenance of this 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

+
+ +
+ +## 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:** + +- [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

+
+ +
+ +## 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:** + +

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

+
parameters
+map[string]string +		 +

Parameters is the configuration of the plugin

+
+ +
+ +## PluginConfigurationList + +(Alias of `[]github.com/EnterpriseDB/cloud-native-postgres/api/v1.PluginConfiguration`) + +**Appears in:** + +- [ClusterSpec](#postgresql-k8s-enterprisedb-io-v1-ClusterSpec) + +

PluginConfigurationList represent a set of plugin with their +configuration parameters

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

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

+
+ +
+ +## 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/postgresql_conf.mdx b/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx index 73761f40a61..db307c2dd53 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/postgresql_conf.mdx @@ -337,6 +337,7 @@ local all all peer hostssl postgres streaming_replica all cert hostssl replication streaming_replica all cert +hostssl all cnp_pooler_pgbouncer all cert ``` Default rules: diff --git a/product_docs/docs/postgres_for_kubernetes/1/private_edb_registry.mdx b/product_docs/docs/postgres_for_kubernetes/1/private_edb_registries.mdx similarity index 96% rename from product_docs/docs/postgres_for_kubernetes/1/private_edb_registry.mdx rename to product_docs/docs/postgres_for_kubernetes/1/private_edb_registries.mdx index 950c836ac0f..0b124c005e0 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/private_edb_registry.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/private_edb_registries.mdx @@ -1,6 +1,6 @@ --- title: 'EDB private container registries' -originalFilePath: 'src/private_edb_registry.md' +originalFilePath: 'src/private_edb_registries.md' --- The images for the *EDB Postgres for Kubernetes* operator, as well as various @@ -17,7 +17,7 @@ operands, are kept in private container image registries under !!! Note When installing the operator and operands from the private registry, the - [license keys](./license_keys.md) are not needed. + [license keys](license_keys.md) are not needed. ## Which repository to choose? @@ -84,7 +84,7 @@ images available from the same private registries: `ghcr.io/enterprisedb/postgresql`. These images follow the requirements and the conventions described in the -["Container image requirements"](/postgres_for_kubernetes/latest/container_images/) +["Container image requirements"](container_images.md) page of the EDB Postgres for Kubernetes documentation. In the table below you can find the image name prefix for each Postgres distribution: @@ -146,7 +146,7 @@ and the token is the *password*. The same credentials can be used for kubernetes to access the registry by setting up a [`kubernetes.io/dockerconfigjson` pull secret](https://kubernetes.io/docs/concepts/configuration/secret/#secret-types). -As mentioned in the [installation document](./installation_upgrade.md), there +As mentioned in the [installation document](installation_upgrade.md), there are several different ways to install the operator. If you are going to install using images from the private registry, you will diff --git a/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx b/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx index aedcc448496..5407193ec89 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/quickstart.mdx @@ -33,8 +33,7 @@ cluster on your local Kubernetes/Openshift installation and experiment with it. ## Part 1 - Setup the local Kubernetes/Openshift Local playground -The first part is about installing Minikube, Kind, or OpenShift Local. Please spend some time -reading about the systems and decide which one to proceed with. +The first part is about installing Minikube, Kind, or OpenShift Local. Please spend some time reading about the systems and decide which one to proceed with. After setting up one of them, please proceed with part 2. We also provide instructions for setting up monitoring with Prometheus and @@ -112,6 +111,8 @@ with the deployment of a PostgreSQL cluster. ## Part 3: Deploy a PostgreSQL cluster +Unless specified in a cluster configuration file, EDB Postgres for Kubernetes will currently deploy Community Postgresql operands by default. See the section [Deploying EDB Postgres servers](#deploying-edb-postgres-servers) for more information. + As with any other deployment in Kubernetes, to deploy a PostgreSQL cluster you need to apply a configuration file that defines your desired `Cluster`. @@ -131,18 +132,11 @@ spec: size: 1Gi ``` -!!! Note "Installing other operands" - EDB Postgres for Kubernetes supports not just PostgreSQL, but EDB Postgres - Extended (PGE) and EDB Postgres Advanced (EPAS). - The images for those operands are kept in private registries. Please refer - to the [private registry](private_edb_registry.md) document for instructions - on deploying clusters using PGE or EPAS as operands. - !!! Note "There's more" For more detailed information about the available options, please refer to the ["API Reference" section](pg4k.v1.md). -In order to create the 3-node PostgreSQL cluster, you need to run the following command: +In order to create the 3-node Community PostgreSQL cluster, you need to run the following command: ```sh kubectl apply -f cluster-example.yaml @@ -169,10 +163,25 @@ kubectl get pods -l k8s.enterprisedb.io/cluster= have seen or used `postgresql`. This label is being deprecated, and will be dropped in the future. Please use `k8s.enterprisedb.io/cluster`. +### Deploying EDB Postgres servers + By default, the operator will install the latest available minor version -of the latest major version of PostgreSQL when the operator was released. +of the latest major version of Community PostgreSQL when the operator was released. You can override this by setting the `imageName` key in the `spec` section of -the `Cluster` definition. For example, to install PostgreSQL 13.6: +the `Cluster` definition. For example, to install EDB Postgres Advanced 16.4 you can use: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + # [...] +spec: + # [...] + imageName: docker.enterprisedb.com/k8s_enterprise/edb-postgres-advanced:16 + #[...] +``` + +And to install EDB Postgres Extended 16 you can use: ```yaml apiVersion: postgresql.k8s.enterprisedb.io/v1 @@ -181,7 +190,7 @@ metadata: # [...] spec: # [...] - imageName: quay.io/enterprisedb/postgresql:13.6 + imageName: docker.enterprisedb.com/k8s_enterprise/edb-postgres-extended:16 #[...] ``` diff --git a/product_docs/docs/postgres_for_kubernetes/1/replication.mdx b/product_docs/docs/postgres_for_kubernetes/1/replication.mdx index e09d7946a96..6c81d866c92 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/replication.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/replication.mdx @@ -4,46 +4,46 @@ 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 achieve high availability, physical replication also allows -scale-out of read-only workloads and offloading of some work from the primary. +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 +achieve high availability, physical replication also allows scale-out of +read-only workloads and offloading of some work from the primary. !!! Important This section is about replication within the same `Cluster` resource managed in the same Kubernetes cluster. For information about how to replicate with another Postgres `Cluster` resource, even across different - Kubernetes clusters, please refer to the ["Replica clusters"](replica_cluster.md) - section. + Kubernetes clusters, please refer to the + ["Replica clusters"](replica_cluster.md) section. ## Application-level replication -Having contributed throughout the years to the replication feature in PostgreSQL, -we have decided to build high availability in EDB Postgres for Kubernetes on top of -the native physical replication technology, and integrate it -directly in the Kubernetes API. +Having contributed throughout the years to the replication feature in +PostgreSQL, we have decided to build high availability in EDB Postgres for Kubernetes on top +of the native physical replication technology, and integrate it directly in the +Kubernetes API. -In Kubernetes terms, this is referred to as **application-level replication**, in -contrast with *storage-level replication*. +In Kubernetes terms, this is referred to as **application-level replication**, +in contrast with *storage-level replication*. ## A very mature technology PostgreSQL has a very robust and mature native framework for replicating data -from the primary instance to one or more replicas, built around the -concept of transactional changes continuously stored in the WAL (Write Ahead Log). +from the primary instance to one or more replicas, built around the concept of +transactional changes continuously stored in the WAL (Write Ahead Log). Started as the evolution of crash recovery and point in time recovery technologies, physical replication was first introduced in PostgreSQL 8.2 -(2006) through WAL shipping from the primary to a warm standby in -continuous recovery. +(2006) through WAL shipping from the primary to a warm standby in continuous +recovery. PostgreSQL 9.0 (2010) introduced WAL streaming and read-only replicas through *hot standby*. In 2011, PostgreSQL 9.1 brought synchronous replication at the -transaction level, supporting RPO=0 clusters. Cascading replication was added -in PostgreSQL 9.2 (2012). The foundations for logical replication were -established in PostgreSQL 9.4 (2014), and version 10 (2017) introduced native -support for the publisher/subscriber pattern to replicate data from an origin -to a destination. The table below summarizes these milestones. +transaction level, supporting RPO=0 clusters. Cascading replication was added in +PostgreSQL 9.2 (2012). The foundations for [logical replication](logical_replication.md) +were established in PostgreSQL 9.4 (2014), and version 10 (2017) introduced +native support for the publisher/subscriber pattern to replicate data from an +origin to a destination. The table below summarizes these milestones. | Version | Year | Feature | | :-----: | :--: | --------------------------------------------------------------------- | @@ -59,9 +59,9 @@ versions. ## Streaming replication support -At the moment, EDB Postgres for Kubernetes natively and transparently manages -physical streaming replicas within a cluster in a declarative way, based on -the number of provided `instances` in the `spec`: +At the moment, EDB Postgres for Kubernetes natively and transparently manages physical +streaming replicas within a cluster in a declarative way, based on the number of +provided `instances` in the `spec`: ``` replicas = instances - 1 (where instances > 0) @@ -72,13 +72,13 @@ called `streaming_replica` as follows: ```sql CREATE USER streaming_replica WITH REPLICATION; - -- NOSUPERUSER INHERIT NOCREATEROLE NOCREATEDB NOBYPASSRLS +-- NOSUPERUSER INHERIT NOCREATEROLE NOCREATEDB NOBYPASSRLS ``` Out of the box, the operator automatically sets up streaming replication within the cluster over an encrypted channel and enforces TLS client certificate -authentication for the `streaming_replica` user - as highlighted by the following -excerpt taken from `pg_hba.conf`: +authentication for the `streaming_replica` user - as highlighted by the +following excerpt taken from `pg_hba.conf`: ``` # Require client certificate authentication for the streaming_replica user @@ -104,9 +104,9 @@ the primary's storage, even after a failover or switchover. ### Continuous backup integration In case continuous backup is configured in the cluster, EDB Postgres for Kubernetes -transparently configures replicas to take advantage of `restore_command` when -in continuous recovery. As a result, PostgreSQL can use the WAL archive -as a fallback option whenever pulling WALs via streaming replication fails. +transparently configures replicas to take advantage of `restore_command` when in +continuous recovery. As a result, PostgreSQL can use the WAL archive as a +fallback option whenever pulling WALs via streaming replication fails. ## Synchronous Replication @@ -114,16 +114,19 @@ EDB Postgres for Kubernetes supports both [quorum-based and priority-based synchronous replication for PostgreSQL](https://www.postgresql.org/docs/current/warm-standby.html#SYNCHRONOUS-REPLICATION). !!! Warning - Please be aware that synchronous replication will halt your write - operations if the required number of standby nodes to replicate WAL data for - transaction commits is unavailable. In such cases, write operations for your - applications will hang. This behavior differs from the previous implementation - in EDB Postgres for Kubernetes but aligns with the expectations of a PostgreSQL DBA for this - capability. - -While direct configuration of the `synchronous_standby_names` option is -prohibited, EDB Postgres for Kubernetes allows you to customize its content and extend -synchronous replication beyond the `Cluster` resource through the + By default, synchronous replication pauses write operations if the required + number of standby nodes for WAL replication during transaction commits is + unavailable. This behavior prioritizes data durability and aligns with + PostgreSQL DBA best practices. However, if self-healing is a higher priority + than strict data durability in your setup, this setting can be adjusted. For + details on managing this behavior, refer to the [Data Durability and Synchronous Replication](#data-durability-and-synchronous-replication) + section. + +Direct configuration of the `synchronous_standby_names` option is not +permitted. However, EDB Postgres for Kubernetes automatically populates this option with the +names of local pods, while also allowing customization to extend synchronous +replication beyond the `Cluster` resource. +This can be achieved through the [`.spec.postgresql.synchronous` stanza](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-SynchronousReplicaConfiguration). Synchronous replication is disabled by default (the `synchronous` stanza is not @@ -135,17 +138,39 @@ defined). When defined, two options are mandatory: ### Quorum-based Synchronous Replication -PostgreSQL's quorum-based synchronous replication makes transaction commits -wait until their WAL records are replicated to at least a certain number of -standbys. To use this method, set `method` to `any`. +In PostgreSQL, quorum-based synchronous replication ensures that transaction +commits wait until their WAL records are replicated to a specified number of +standbys. To enable this, set the `method` to `any`. -#### Migrating from the Deprecated Synchronous Replication Implementation +This replication method is the most common setup for a EDB Postgres for Kubernetes cluster. -This section provides instructions on migrating your existing quorum-based -synchronous replication, defined using the deprecated form, to the new and more -robust capability in EDB Postgres for Kubernetes. +#### Example -Suppose you have the following manifest: +The example below, based on a typical `cluster-example` configuration with +three instances, sets up quorum-based synchronous replication with at least one +instance: + +```yaml +postgresql: + synchronous: + method: any + number: 1 +``` + +With this configuration, EDB Postgres for Kubernetes automatically sets the content of +`synchronous_standby_names` as follows: + +```console +ANY 1 (cluster-example-2, cluster-example-3, cluster-example-1) +``` + +#### Migrating from Deprecated Synchronous Replication Implementation + +This section outlines how to migrate from the deprecated quorum-based +synchronous replication format to the newer, more robust implementation in +EDB Postgres for Kubernetes. + +Given the following manifest: ```yaml apiVersion: postgresql.k8s.enterprisedb.io/v1 @@ -154,7 +179,6 @@ metadata: name: angus spec: instances: 3 - minSyncReplicas: 1 maxSyncReplicas: 1 @@ -162,7 +186,7 @@ spec: size: 1G ``` -You can convert it to the new quorum-based format as follows: +You can update it to the new format as follows: ```yaml apiVersion: postgresql.k8s.enterprisedb.io/v1 @@ -179,14 +203,11 @@ spec: synchronous: method: any number: 1 + dataDurability: required ``` -!!! Important - The primary difference with the new capability is that PostgreSQL will - always prioritize data durability over high availability. Consequently, if no - replica is available, write operations on the primary will be blocked. However, - this behavior is consistent with the expectations of a PostgreSQL DBA for this - capability. +To prioritize self-healing over strict data durability, set `dataDurability` +to `preferred` instead. ### Priority-based Synchronous Replication @@ -225,31 +246,16 @@ the PostgreSQL cluster. You can customize the content of !!! Warning You are responsible for ensuring the correct names in `standbyNamesPre` and - `standbyNamesPost`. EDB Postgres for Kubernetes expects that you manage any standby with an - `application_name` listed here, ensuring their high availability. Incorrect - entries can jeopardize your PostgreSQL database uptime. + `standbyNamesPost`. EDB Postgres for Kubernetes expects that you manage any standby with + an `application_name` listed here, ensuring their high availability. + Incorrect entries can jeopardize your PostgreSQL database uptime. -### Examples +#### Examples Here are some examples, all based on a `cluster-example` with three instances: If you set: -```yaml -postgresql: - synchronous: - method: any - number: 1 -``` - -The content of `synchronous_standby_names` will be: - -```console -ANY 1 (cluster-example-2, cluster-example-3) -``` - -If you set: - ```yaml postgresql: synchronous: @@ -305,14 +311,151 @@ The `synchronous_standby_names` option will look like: FIRST 2 (angus, cluster-example-2, malcolm) ``` +### Data Durability and Synchronous Replication + +The `dataDurability` option in the `.spec.postgresql.synchronous` stanza +controls the trade-off between data safety and availability for synchronous +replication. It can be set to `required` or `preferred`, with the default being +`required` if not specified. + +!!! Important + `preferred` can only be used when `standbyNamesPre` and `standbyNamesPost` + are unset. + +#### Required Data Durability + +When `dataDurability` is set to `required`, PostgreSQL only considers +transactions committed once WAL (Write-Ahead Log) records have been replicated +to the specified number of synchronous standbys. This setting prioritizes data +safety over availability, meaning write operations will pause if the required +number of synchronous standbys is unavailable. This ensures zero data loss +(RPO=0) but may reduce database availability during network disruptions or +standby failures. + +Synchronous standbys are selected in this priority order: + +1. Healthy instances +2. Unhealthy instances +3. Primary + +The list is then truncated based on `maxStandbyNamesFromCluster` if this value +is set, prioritizing healthy instances and ensuring `synchronous_standby_names` +is populated. + +##### Example + +Consider the following example: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: foo +spec: + instances: 3 + postgresql: + synchronous: + method: any + number: 1 + dataDurability: required +``` + +1. Initial state. The content of `synchronous_standby_names` is: + + ``` + ANY 1 ("foo-2","foo-3","foo-1") + ``` + +2. `foo-2` becomes unavailable. It gets pushed back in priority: + + ``` + ANY 1 ("foo-3","foo-2","foo-1") + ``` + +3. `foo-3` also becomes unavailable. The list contains no healthy standbys: + + ``` + ANY 1 ("foo-2","foo-3","foo-1") + ``` + + At this point no write operations will be allowed until at least one of the + standbys is available again. + +4. When the standbys are available again, `synchronous_standby_names` will + be back to the initial state. + +#### Preferred Data Durability + +When `dataDurability` is set to `preferred`, the required number of synchronous +instances adjusts based on the number of available standbys. PostgreSQL will +attempt to replicate WAL records to the designated number of synchronous +standbys, but write operations will continue even if fewer than the requested +number of standbys are available. + +This setting balances data safety with availability, enabling applications to +continue writing during temporary standby unavailability—hence, it’s also known +as *self-healing mode*. + +!!! Warning + This mode may result in data loss if all standbys become unavailable. + +With `preferred` data durability, **only healthy replicas** are included in +`synchronous_standby_names`. + +##### Example + +Consider the following example. For demonstration, we’ll use a cluster named +`bar` with 5 instances and 2 synchronous standbys: + +```yaml +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: bar +spec: + instances: 5 + postgresql: + synchronous: + method: any + number: 2 + dataDurability: required +``` + +1. Initial state. The content of `synchronous_standby_names` is: + + ``` + ANY 2 ("bar-2","bar-3", "bar-4", "bar-5") + ``` + +2. `bar-2` and `bar-3` become unavailable. They are removed from the list: + + ``` + ANY 2 ("bar-4", "bar-5") + ``` + +3. `bar-4` also becomes unavailable. It gets removed from the list. Since the + number of available standbys is less than the requested number, the requested + amount gets reduced: + + ``` + ANY 1 ("bar-5") + ``` + +4. `bar-5` also becomes unavailable. `synchronous_standby_names` becomes empty, + disabling synchronous replication completely. Write operations will continue, + but with the risk of potential data loss in case of a primary failure. + +5. When the replicas are back, `synchronous_standby_names` will be back to + the initial state. + ## Synchronous Replication (Deprecated) !!! Warning Prior to EDB Postgres for Kubernetes 1.24, only the quorum-based synchronous replication - implementation was supported. Although this method is now deprecated, it will - not be removed anytime soon. - The new method prioritizes data durability over self-healing and offers - more robust features, including priority-based synchronous replication and full + implementation was supported. Although this method is now deprecated, it + will not be removed anytime soon. + The new method prioritizes data durability over self-healing and offers more + robust features, including priority-based synchronous replication and full control over the `synchronous_standby_names` option. It is recommended to gradually migrate to the new configuration method for synchronous replication, as explained in the previous paragraph. @@ -383,12 +526,13 @@ Postgres pod are. legacy implementation of synchronous replication (see ["Synchronous Replication (Deprecated)"](replication.md#synchronous-replication-deprecated)). -As an example use-case for this feature: in a cluster with a single sync replica, -we would be able to ensure the sync replica will be in a different availability -zone from the primary instance, usually identified by the `topology.kubernetes.io/zone` +As an example use-case for this feature: in a cluster with a single sync +replica, we would be able to ensure the sync replica will be in a different +availability zone from the primary instance, usually identified by +the `topology.kubernetes.io/zone` [label on a node](https://kubernetes.io/docs/reference/labels-annotations-taints/#topologykubernetesiozone). -This would increase the robustness of the cluster in case of an outage in a single -availability zone, especially in terms of recovery point objective (RPO). +This would increase the robustness of the cluster in case of an outage in a +single availability zone, especially in terms of recovery point objective (RPO). The idea of anti-affinity is to ensure that sync replicas that participate in the quorum are chosen from pods running on nodes that have different values for @@ -403,8 +547,8 @@ the replicas are eligible for synchronous replication. The example below shows how this can be done through the `syncReplicaElectionConstraint` section within `.spec.postgresql`. -`nodeLabelsAntiAffinity` allows you to specify those node labels that need to -be evaluated to make sure that synchronous replication will be dynamically +`nodeLabelsAntiAffinity` allows you to specify those node labels that need to be +evaluated to make sure that synchronous replication will be dynamically configured by the operator between the current primary and the replicas which are located on nodes having a value of the availability zone label different from that of the node where the primary is: @@ -428,22 +572,24 @@ as storage, CPU, or memory. [Replication slots](https://www.postgresql.org/docs/current/warm-standby.html#STREAMING-REPLICATION-SLOTS) are a native PostgreSQL feature introduced in 9.4 that provides an automated way to ensure that the primary does not remove WAL segments until all the attached -streaming replication clients have received them, and that the primary -does not remove rows which could cause a recovery conflict even when the -standby is (temporarily) disconnected. +streaming replication clients have received them, and that the primary does not +remove rows which could cause a recovery conflict even when the standby is ( +temporarily) disconnected. A replication slot exists solely on the instance that created it, and PostgreSQL -does not replicate it on the standby servers. As a result, after a failover -or a switchover, the new primary does not contain the replication slot from -the old primary. This can create problems for the streaming replication clients -that were connected to the old primary and have lost their slot. +does not replicate it on the standby servers. As a result, after a failover or a +switchover, the new primary does not contain the replication slot from the old +primary. This can create problems for the streaming replication clients that +were connected to the old primary and have lost their slot. EDB Postgres for Kubernetes provides a turn-key solution to synchronize the content of physical replication slots from the primary to each standby, addressing two use cases: - the replication slots automatically created for the High Availability of the - Postgres cluster (see ["Replication slots for High Availability" below](#replication-slots-for-high-availability) for details) + Postgres cluster ( + see ["Replication slots for High Availability" below](#replication-slots-for-high-availability) + for details) - [user-defined replication slots](#user-defined-replication-slots) created on the primary @@ -451,22 +597,22 @@ cases: EDB Postgres for Kubernetes fills this gap by introducing the concept of cluster-managed replication slots, starting with high availability clusters. This feature -automatically manages physical replication slots for each hot standby replica -in the High Availability cluster, both in the primary and the standby. +automatically manages physical replication slots for each hot standby replica in +the High Availability cluster, both in the primary and the standby. In EDB Postgres for Kubernetes, we use the terms: - **Primary HA slot**: a physical replication slot whose lifecycle is entirely - managed by the current primary of the cluster and whose purpose is to map to - a specific standby in streaming replication. Such a slot lives on the primary + managed by the current primary of the cluster and whose purpose is to map to a + specific standby in streaming replication. Such a slot lives on the primary only. -- **Standby HA slot**: a physical replication slot for a standby whose - lifecycle is entirely managed by another standby in the cluster, based on the - content of the `pg_replication_slots` view in the primary, and updated at regular +- **Standby HA slot**: a physical replication slot for a standby whose lifecycle + is entirely managed by another standby in the cluster, based on the content of + the `pg_replication_slots` view in the primary, and updated at regular intervals using `pg_replication_slot_advance()`. -This feature is enabled by default and can be disabled via configuration. -For details, please refer to the +This feature is enabled by default and can be disabled via configuration. For +details, please refer to the ["replicationSlots" section in the API reference](pg4k.v1.md#postgresql-k8s-enterprisedb-io-v1-ReplicationSlotsConfiguration). Here follows a brief description of the main options: @@ -474,13 +620,13 @@ Here follows a brief description of the main options: : if `true`, the feature is enabled (`true` is the default) `.spec.replicationSlots.highAvailability.slotPrefix` -: the prefix that identifies replication slots managed by the operator - for this feature (default: `_cnp_`) +: the prefix that identifies replication slots managed by the operator for this +feature (default: `_cnp_`) `.spec.replicationSlots.updateInterval` : how often the standby synchronizes the position of the local copy of the - replication slots with the position on the current primary, expressed in - seconds (default: 30) +replication slots with the position on the current primary, expressed in +seconds (default: 30) Although it is not recommended, if you desire a different behavior, you can customize the above options. @@ -582,18 +728,18 @@ spec: ### Capping the WAL size retained for replication slots -When replication slots is enabled, you might end up running out of disk -space due to PostgreSQL trying to retain WAL files requested by a replication -slot. This might happen due to a standby that is (temporarily?) down, or -lagging, or simply an orphan replication slot. +When replication slots is enabled, you might end up running out of disk space +due to PostgreSQL trying to retain WAL files requested by a replication slot. +This might happen due to a standby that is (temporarily?) down, or lagging, or +simply an orphan replication slot. Starting with PostgreSQL 13, you can take advantage of the [`max_slot_wal_keep_size`](https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-MAX-SLOT-WAL-KEEP-SIZE) configuration option controlling the maximum size of WAL files that replication -slots are allowed to retain in the `pg_wal` directory at checkpoint time. -By default, in PostgreSQL `max_slot_wal_keep_size` is set to `-1`, meaning that -replication slots may retain an unlimited amount of WAL files. -As a result, our recommendation is to explicitly set `max_slot_wal_keep_size` +slots are allowed to retain in the `pg_wal` directory at checkpoint time. By +default, in PostgreSQL `max_slot_wal_keep_size` is set to `-1`, meaning that +replication slots may retain an unlimited amount of WAL files. As a result, our +recommendation is to explicitly set `max_slot_wal_keep_size` when replication slots support is enabled. For example: ```ini diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples.mdx b/product_docs/docs/postgres_for_kubernetes/1/samples.mdx index 52ab68303fb..da47256caea 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/samples.mdx @@ -20,6 +20,14 @@ your PostgreSQL cluster. : [`cluster-example.yaml`](../samples/cluster-example.yaml) A basic example of a cluster. +**EDB Postgres Advanced Server (EPAS) cluster** +: [`cluster-example-epas.yaml`](../samples/cluster-example-epas.yaml) + A basic example of an EPAS cluster. + +**EDB Postgres Extended (PGE) cluster** +: [`cluster-example-pge.yaml`](../samples/cluster-example-pge.yaml) + A basic example of a PGE cluster. + **Custom cluster** : [`cluster-example-custom.yaml`](../samples/cluster-example-custom.yaml) A basic cluster that uses the default storage class and custom parameters for diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-epas.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-epas.yaml index c06d19e1b7d..b8c3c4475fe 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-epas.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-epas.yaml @@ -1,14 +1,10 @@ apiVersion: postgresql.k8s.enterprisedb.io/v1 kind: Cluster metadata: - name: cluster-example + name: postgresql-advanced-cluster spec: instances: 3 - # imageName: docker-epas:13 - - bootstrap: - initdb: - redwood: false + imageName: docker.enterprisedb.com/k8s_enterprise/edb-postgres-advanced:16 storage: size: 1Gi diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-full.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-full.yaml index 3b4ba3d50d4..ce80fd505ef 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-full.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-full.yaml @@ -35,7 +35,7 @@ metadata: name: cluster-example-full spec: description: "Example of cluster" - imageName: quay.io/enterprisedb/postgresql:17.0 + imageName: quay.io/enterprisedb/postgresql:17.2 # imagePullSecret is only required if the images are located in a private registry # imagePullSecrets: # - name: private_registry_access diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-initdb-icu.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-initdb-icu.yaml new file mode 100644 index 00000000000..9db3edec3d5 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-initdb-icu.yaml @@ -0,0 +1,19 @@ +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: cluster-example-initdb-icu +spec: + instances: 3 + + bootstrap: + initdb: + encoding: UTF8 + localeCollate: en_US.UTF8 + localeCType: en_US.UTF8 + localeProvider: icu + icuLocale: en-US + # we want to order g and G after A (and before b) + icuRules: '&A < g <<< G' + + storage: + size: 1Gi diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-logical-destination.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-logical-destination.yaml index b717973e3eb..71a6a8fe31d 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-logical-destination.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-logical-destination.yaml @@ -22,12 +22,20 @@ spec: - name: cluster-example connectionParameters: host: cluster-example-rw.default.svc - # We're using the superuser to allow the publication to be - # created directly when connected to the target server. - # See cluster-example-logical-source.yaml for more information - # about this. - user: postgres + user: app dbname: app password: - name: cluster-example-superuser + name: cluster-example-app key: password +--- +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Subscription +metadata: + name: cluster-example-dest-sub +spec: + cluster: + name: cluster-example-dest + name: sub + dbname: app + publicationName: pub + externalClusterName: cluster-example diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-logical-source.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-logical-source.yaml index 7242d5bfd86..06032bf3ddf 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-logical-source.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-logical-source.yaml @@ -5,7 +5,7 @@ metadata: spec: instances: 1 - imageName: quay.io/enterprisedb/postgresql:13 + imageName: quay.io/enterprisedb/postgresql:16 storage: size: 1Gi @@ -15,18 +15,30 @@ spec: postInitApplicationSQL: - CREATE TABLE numbers (i SERIAL PRIMARY KEY, m INTEGER) - INSERT INTO numbers (m) (SELECT generate_series(1,10000)) - - ALTER TABLE numbers OWNER TO app; + - ALTER TABLE numbers OWNER TO app - CREATE TABLE numbers_two (i SERIAL PRIMARY KEY, m INTEGER) - INSERT INTO numbers_two (m) (SELECT generate_series(1,10000)) - - ALTER TABLE numbers_two OWNER TO app; - - CREATE TABLE numbers_three (i SERIAL PRIMARY KEY, m INTEGER) - - INSERT INTO numbers_three (m) (SELECT generate_series(1,10000)) - - ALTER TABLE numbers_three OWNER TO app; - - enableSuperuserAccess: true + - ALTER TABLE numbers_two OWNER TO app + - CREATE SCHEMA another_schema + - ALTER SCHEMA another_schema OWNER TO app + - CREATE TABLE another_schema.numbers_three (i SERIAL PRIMARY KEY, m INTEGER) + - INSERT INTO another_schema.numbers_three (m) (SELECT generate_series(1,10000)) + - ALTER TABLE another_schema.numbers_three OWNER TO app managed: roles: - name: app login: true replication: true +--- +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Publication +metadata: + name: cluster-example-pub +spec: + name: pub + dbname: app + cluster: + name: cluster-example + target: + allTables: true diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-pge.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-pge.yaml new file mode 100644 index 00000000000..8d4f74adf21 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-pge.yaml @@ -0,0 +1,10 @@ +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Cluster +metadata: + name: postgresql-extended-cluster +spec: + instances: 3 + imageName: docker.enterprisedb.com/k8s_enterprise/edb-postgres-extended:16 + + storage: + size: 1Gi diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-tde.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-tde.yaml index 79ae2b0b8b8..88f34e73752 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-tde.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-example-tde.yaml @@ -13,7 +13,7 @@ metadata: name: cluster-example spec: instances: 3 - imageName: ghcr.io/enterprisedb/edb-postgres-advanced:16 + imageName: docker.enterprisedb.com/k8s_enterprise/edb-postgres-advanced:16 postgresql: epas: tde: @@ -22,9 +22,5 @@ spec: name: tde-key key: key - bootstrap: - initdb: - redwood: true - storage: size: 1Gi diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-import-snapshot-basicauth.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-import-snapshot-basicauth.yaml index 6ab2a501fc2..11878b8a3b5 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-import-snapshot-basicauth.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/cluster-import-snapshot-basicauth.yaml @@ -13,6 +13,10 @@ spec: - app source: externalCluster: cluster-example + pgDumpExtraOptions: + - '--jobs=2' + pgRestoreExtraOptions: + - '--jobs=2' storage: size: 1Gi externalClusters: diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/database-example-fail.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/database-example-fail.yaml new file mode 100644 index 00000000000..44260589b88 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/database-example-fail.yaml @@ -0,0 +1,9 @@ +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Database +metadata: + name: db-two +spec: + name: two + owner: app-two + cluster: + name: cluster-example diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/database-example-icu.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/database-example-icu.yaml new file mode 100644 index 00000000000..0251f5b5b6e --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/database-example-icu.yaml @@ -0,0 +1,16 @@ +# NOTE: this manifest will only work properly if the Postgres version supports +# ICU locales and rules (version 16 and newer) +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Database +metadata: + name: db-icu +spec: + name: declarative-icu + owner: app + encoding: UTF8 + locale_provider: icu + icu_locale: en + icu_rules: fr + template: template0 + cluster: + name: cluster-example diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/database-example.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/database-example.yaml new file mode 100644 index 00000000000..c951ecdce4d --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/database-example.yaml @@ -0,0 +1,9 @@ +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Database +metadata: + name: db-one +spec: + name: one + owner: app + cluster: + name: cluster-example diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/monitoring/prometheusrule.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/monitoring/prometheusrule.yaml index 34aae13b846..68ef76e5540 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/monitoring/prometheusrule.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/monitoring/prometheusrule.yaml @@ -29,7 +29,7 @@ spec: description: Over 150,000,000 transactions from frozen xid on pod {{ $labels.pod }} summary: Number of transactions from the frozen XID to the current one expr: |- - cnp_pg_database_xid_age > 150000000 + cnp_pg_database_xid_age > 300000000 for: 1m labels: severity: warning diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/pooler-tls.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/pooler-tls.yaml index b878c00e977..f11fd830723 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/samples/pooler-tls.yaml +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/pooler-tls.yaml @@ -10,3 +10,5 @@ spec: type: rw pgbouncer: poolMode: session + parameters: + server_tls_protocols: tlsv1.3 diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/publication-example-objects.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/publication-example-objects.yaml new file mode 100644 index 00000000000..4e47ecb73ed --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/publication-example-objects.yaml @@ -0,0 +1,16 @@ +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Publication +metadata: + name: publication-example-objects +spec: + cluster: + name: cluster-example + name: pub-objects + dbname: app + target: + objects: + - tablesInSchema: public + - table: + schema: another_schema + name: numbers_three + only: true diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/publication-example.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/publication-example.yaml new file mode 100644 index 00000000000..40eca1acdea --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/publication-example.yaml @@ -0,0 +1,11 @@ +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Publication +metadata: + name: publication-example +spec: + cluster: + name: cluster-example + name: pub-all + dbname: app + target: + allTables: true diff --git a/product_docs/docs/postgres_for_kubernetes/1/samples/subscription-example.yaml b/product_docs/docs/postgres_for_kubernetes/1/samples/subscription-example.yaml new file mode 100644 index 00000000000..500b8717a52 --- /dev/null +++ b/product_docs/docs/postgres_for_kubernetes/1/samples/subscription-example.yaml @@ -0,0 +1,11 @@ +apiVersion: postgresql.k8s.enterprisedb.io/v1 +kind: Subscription +metadata: + name: subscription-sample +spec: + name: sub + dbname: app + publicationName: pub-all + cluster: + name: cluster-example-dest + externalClusterName: cluster-example diff --git a/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx b/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx index 8148c9f1dbb..298187b4fd5 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/scheduling.mdx @@ -43,7 +43,7 @@ metadata: name: cluster-example spec: instances: 3 - imageName: quay.io/enterprisedb/postgresql:17.0 + imageName: quay.io/enterprisedb/postgresql:17.2 affinity: enablePodAntiAffinity: true # Default value 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 7ee20950297..f14eafe5079 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/ssl_connections.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/ssl_connections.mdx @@ -176,7 +176,7 @@ Output: version -------------------------------------------------------------------------------------- ------------------ -PostgreSQL 17.0 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 8.3.1 20191121 (Red Hat +PostgreSQL 17.2 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 8.3.1 20191121 (Red Hat 8.3.1-5), 64-bit (1 row) ``` diff --git a/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx b/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx index 53e0bd8bf10..2e8c6b4c2c0 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/troubleshooting.mdx @@ -223,7 +223,7 @@ Cluster in healthy state Name: cluster-example Namespace: default System ID: 7044925089871458324 -PostgreSQL Image: quay.io/enterprisedb/postgresql:17.0-3 +PostgreSQL Image: quay.io/enterprisedb/postgresql:17.2-3 Primary instance: cluster-example-1 Instances: 3 Ready instances: 3 @@ -291,7 +291,7 @@ kubectl describe cluster -n | grep "Image Name" Output: ```shell - Image Name: quay.io/enterprisedb/postgresql:17.0-3 + Image Name: quay.io/enterprisedb/postgresql:17.2-3 ``` !!! Note 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 a1f40c17d1f..dd110221ac6 100644 --- a/product_docs/docs/postgres_for_kubernetes/1/wal_archiving.mdx +++ b/product_docs/docs/postgres_for_kubernetes/1/wal_archiving.mdx @@ -16,7 +16,8 @@ the ["Backup on object stores" section](backup_barmanobjectstore.md) to set up the WAL archive. !!! Info - Please refer to [`BarmanObjectStoreConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration) for a full list of options. + Please refer to [`BarmanObjectStoreConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration) + in the barman-cloud API for a full list of options. If required, you can choose to compress WAL files as soon as they are uploaded and/or encrypt them: