docs: import CloudNativePG v1.29.0

Author: cnpg-bot

website/docusaurus.config.ts

@@ -6,7 +6,7 @@ import type * as Preset from '@docusaurus/preset-classic';
 
 const versionsConfig = require('./versions_config.json') as Record<string, import('@docusaurus/plugin-content-docs').VersionOptions>;
 
-const lastVersion = '1.28';
+const lastVersion = '1.29';
 
 const config: Config = {
   title: 'CloudNativePG',

website/versioned_docs/version-1.29/cloudnative-pg.v1.md

@@ -996,6 +996,26 @@ _Appears in:_
 | `dynamic_library_path` _string array_ | The list of directories inside the image which should be added to dynamic_library_path.<br />If not defined, defaults to "/lib". |  |  |  |
 | `ld_library_path` _string array_ | The list of directories inside the image which should be added to ld_library_path. |  |  |  |
 | `bin_path` _string array_ | A list of directories within the image to be appended to the<br />PostgreSQL process's `PATH` environment variable. |  |  |  |
+| `env` _[ExtensionEnvVar](#extensionenvvar) array_ | Env is a list of custom environment variables to be set in the<br />PostgreSQL process for this extension. It is the responsibility of the<br />cluster administrator to ensure the variables are correct for the<br />specific extension. Note that changes to these variables require<br />a manual cluster restart to take effect. |  |  |  |
+
+
+#### ExtensionEnvVar
+
+
+
+ExtensionEnvVar defines an environment variable for a specific extension
+image volume.
+
+
+
+_Appears in:_
+
+- [ExtensionConfiguration](#extensionconfiguration)
+
+| Field | Description | Required | Default | Validation |
+| --- | --- | --- | --- | --- |
+| `name` _string_ | Name of the environment variable to be injected into the<br />PostgreSQL process. | True |  | MinLength: 1 <br />Pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$` <br /> |
+| `value` _string_ | Value of the environment variable. CloudNativePG performs a direct<br />replacement of this value, with support for placeholder expansion.<br />The $\{`image_root`\} placeholder resolves to the absolute mount path<br />of the extension's volume (e.g., `/extensions/my-extension`). This<br />is particularly useful for allowing applications or libraries to<br />locate specific directories within the mounted image.<br />Unrecognized placeholders are rejected. To include a literal $\{...\}<br />in the value, escape it as $$\{...\}. | True |  | MinLength: 1 <br /> |
 
 
 #### ExtensionSpec

website/versioned_docs/version-1.29/cluster_conf.md

@@ -91,6 +91,12 @@ Use this field only in case of
 
 ## Environment variables
 
+:::important
+Environment variables reserved for operator usage (names starting with `PG` or
+`CNPG_`, plus `POD_NAME`, `NAMESPACE`, and `CLUSTER_NAME`) cannot be set
+through the `env` and `envFrom` fields and are rejected at admission time.
+:::
+
 You can customize some system behavior using environment variables. One example
 is the `LDAPCONF` variable, which can point to a custom LDAP configuration
 file. Another example is the `TZ` environment variable, which represents the

website/versioned_docs/version-1.29/cnpg_i.md

@@ -41,7 +41,7 @@ CNPG-I is inspired by the Kubernetes
 The operator communicates with registered plugins using **gRPC**, following the
 [CNPG-I protocol](https://github.com/cloudnative-pg/cnpg-i/blob/main/docs/protocol.md).
 
-CloudNativePG discovers plugins **at startup**. You can register them in one of two ways:
+You can register plugins in one of two ways:
 
 - Sidecar container – run the plugin inside the operator’s Deployment
 - Standalone Deployment – run the plugin as a separate workload in the same
@@ -51,7 +51,9 @@ In both cases, the plugin must be packaged as a container image.
 
 ### Sidecar Container
 
-When running as a sidecar, the plugin must expose its gRPC server via a **Unix
+Sidecar plugins are discovered once at operator startup.
+
+The plugin must expose its gRPC server via a **Unix
 domain socket**. This socket must be placed in a directory shared with the
 operator container, mounted at the path set in `PLUGIN_SOCKET_DIR` (default:
 `/plugin`).
@@ -89,11 +91,8 @@ spec:
 Running a plugin as its own Deployment decouples its lifecycle from the
 operator’s and allows independent scaling. In this setup, the plugin exposes a
 TCP gRPC endpoint behind a Service, with **mTLS** for secure communication.
-
-:::warning
-    CloudNativePG does **not** discover plugins dynamically. If you deploy a new
-    plugin, you must **restart the operator** to detect it.
-:::
+Standalone plugins are discovered dynamically by watching for Services with the
+required labels and annotations — no operator restart is needed.
 
 Example Deployment:
 

website/versioned_docs/version-1.29/imagevolume_extensions.md

@@ -374,6 +374,7 @@ extension image, particularly when:
 - Multiple extensions are bundled in the same image.
 - The image uses a custom directory structure.
 - The extension requires external binaries to function properly.
+- The extension requires setting specific environment variables.
 
 Following the *"convention over configuration"* paradigm, CloudNativePG allows
 you to finely control the configuration of each extension image through the
@@ -392,6 +393,8 @@ following fields:
 - `bin_path`: A list of relative paths within the container image to be
   appended to the `PATH` environment variable of the Postgres process,
   allowing PostgreSQL to locate binaries at runtime.
+- `env`: A list of `name` and `value` pairs to be set as environment variables within
+  the Postgres process.
 
 This flexibility enables you to support complex or non-standard extension
 images while maintaining clarity and predictability.
@@ -539,6 +542,94 @@ need to manually restart the cluster (e.g., using `cnpg restart`) after
 modifying `bin_path`.
 :::
 
+### Environment variables for extensions
+
+Certain extensions require specific environment variables to be set within the
+PostgreSQL process to function correctly. You can define these variables using
+the `env` field within the extension's configuration.
+
+The following example demonstrates how to set a static variable (`FOO`) and a
+variable using a placeholder (`BAR`):
+
+```yaml
+# ...
+spec:
+  # ... <snip>
+  postgresql:
+    # ... <snip>
+    extensions:
+      - name: my-extension
+        image:
+          reference: "ghcr.io/org/my-extension:latest"
+        env:
+          - name: FOO
+            value: "static_value"
+          - name: BAR
+            value: "${image_root}/lib"
+      # ... <snip>
+# ...
+```
+
+#### Dynamic Placeholder Expansion
+
+The `value` field supports placeholder expansion to allow for dynamic
+configuration based on the extension's environment.
+The following placeholders are currently supported:
+
+| Placeholder | Description |
+| :--- | :--- |
+| `${image_root}` | Resolves to the absolute mount path of the extension's volume (e.g., `/extensions/my-extension`). |
+
+The `${image_root}` placeholder is particularly useful when an application or a
+shared library within the extension image needs an environment variable to
+point to a specific subdirectory or file inside its own mounted volume.
+
+In the example above, if the extension is mounted at
+`/extensions/my-extension`, the variable `BAR` will resolve to
+`/extensions/my-extension/lib`, allowing the library to locate its
+dependencies regardless of the specific mount path chosen by the operator.
+
+:::tip
+Unrecognized placeholders (e.g., `${typo}`) are rejected at admission time.
+If you need a literal `${...}` in a value, escape it by doubling the dollar
+sign: `$${...}`. For example, a value of `$${not_expanded}` will produce the
+literal string `${not_expanded}`.
+:::
+
+#### Precedence and Conflict Resolution
+
+Environment variables for the PostgreSQL process can be defined in multiple
+places. When the same variable name appears in more than one location, the
+following precedence order applies (highest priority last):
+
+1. **`spec.env` / `spec.envFrom`**: Variables defined at the cluster level are
+   injected by Kubernetes into the container environment and serve as the base.
+2. **Extension `env`**: Variables defined in the `env` field of each extension
+   override any cluster-level variable with the same name.
+3. **Extension order**: If multiple extensions define the same variable, the
+   extension listed last in the `extensions` array takes precedence.
+
+CloudNativePG emits a warning in the instance manager logs when an extension
+environment variable overwrites a value that was already set by a previous
+extension, to help diagnose potential conflicts.
+
+:::important
+**Reserved variables**: Environment variables reserved for operator usage
+(names starting with `PG` or `CNPG_`, plus `POD_NAME`, `NAMESPACE`, and
+`CLUSTER_NAME`) and variables managed by dedicated fields (`PATH` via
+`bin_path`, `LD_LIBRARY_PATH` via `ld_library_path`) cannot be set through
+the `env` field and are rejected at admission time.
+:::
+
+:::warning
+**Manual Restart Required**: Because environment variables are injected when
+the PostgreSQL process starts, any changes to the `env` section **require a
+cluster restart**. CloudNativePG does **not** automatically trigger a rollout
+for these changes. After updating the `env` field in your manifest, you must
+manually restart the cluster (e.g., using `kubectl cnpg restart`) for the new
+values to take effect.
+:::
+
 ## Image Specifications
 
 A standard extension container image for CloudNativePG includes two

website/versioned_docs/version-1.29/index.md

@@ -64,7 +64,7 @@ container images for both the operator and PostgreSQL (the operand).
 
 The CloudNativePG operator container images are available on the
 [`cloudnative-pg` project's GitHub Container Registry](https://github.com/cloudnative-pg/cloudnative-pg/pkgs/container/cloudnative-pg)
-in three different flavors:
+in two different flavors:
 
 - Debian 12 distroless
 - Red Hat UBI 9 micro (suffix `-ubi9`)

website/versioned_docs/version-1.29/installation_upgrade.md

@@ -14,12 +14,12 @@ title: Installation and upgrades
 The operator can be installed like any other resource in Kubernetes,
 through a YAML manifest applied via `kubectl`.
 
-You can install the [latest operator manifest](https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/releases/cnpg-1.29.0-rc1.yaml)
+You can install the [latest operator manifest](https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.29/releases/cnpg-1.29.0.yaml)
 for this minor release as follows:
 
 ```sh
 kubectl apply --server-side -f \
-  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/releases/cnpg-1.29.0-rc1.yaml
+  https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/release-1.29/releases/cnpg-1.29.0.yaml
 ```
 
 You can verify that with:
@@ -267,22 +267,16 @@ removed before installing the new one. This won't affect user data but
 only the operator itself.
 
 
-### Upgrading to 1.28.0 or 1.27.x
+### Upgrading to 1.29.0 or 1.28.x
 
 :::info[Important]
     We strongly recommend that all CloudNativePG users upgrade to version
-    1.28.0, or at least to the latest stable version of your current minor release
-    (e.g., 1.27.x).
+    1.29.0, or at least to the latest stable version of your current minor release
+    (e.g., 1.28.x).
 :::
 
 ### Upgrading to 1.27 from a previous minor version
 
-:::info[Important]
-    We strongly recommend that all CloudNativePG users upgrade to version
-    1.27.0, or at least to the latest stable version of your current minor release
-    (e.g., 1.26.1).
-:::
-
 Version 1.27 introduces a change in the default behavior of the
 [liveness probe](instance_manager.md#liveness-probe): it now enforces the
 [shutdown of an isolated primary](instance_manager.md#primary-isolation)
@@ -299,65 +293,6 @@ spec:
         enabled: false
 ```
 
-### Upgrading to 1.26 from a previous minor version
-
-:::warning
-    Due to changes in the startup probe for the manager component
-    ([#6623](https://github.com/cloudnative-pg/cloudnative-pg/pull/6623)),
-    upgrading the operator will trigger a restart of your PostgreSQL clusters,
-    even if in-place updates are enabled (`ENABLE_INSTANCE_MANAGER_INPLACE_UPDATES=true`).
-    Your applications will need to reconnect to PostgreSQL after the upgrade.
-:::
-
-#### Deprecation of backup metrics and fields in the `Cluster` `.status`
-
-With the transition to a backup and recovery agnostic approach based on CNPG-I
-plugins in CloudNativePG, which began with version 1.26.0 for Barman Cloud, we
-are starting the deprecation period for the following fields in the `.status`
-section of the `Cluster` resource:
-
-- `firstRecoverabilityPoint`
-- `firstRecoverabilityPointByMethod`
-- `lastSuccessfulBackup`
-- `lastSuccessfulBackupByMethod`
-- `lastFailedBackup`
-
-The following Prometheus metrics are also deprecated:
-
-- `cnpg_collector_first_recoverability_point`
-- `cnpg_collector_last_failed_backup_timestamp`
-- `cnpg_collector_last_available_backup_timestamp`
-
-:::warning
-    If you have migrated to a plugin-based backup and recovery solution such as
-    Barman Cloud, these fields and metrics are no longer synchronized and will
-    not be updated. Users still relying on the in-core support for Barman Cloud
-    and volume snapshots can continue to use these fields for the time being.
-:::
-
-Under the new plugin-based approach, multiple backup methods can operate
-simultaneously, each with its own timeline for backup and recovery. For
-example, some plugins may provide snapshots without WAL archiving, while others
-support continuous archiving.
-
-Because of this flexibility, maintaining centralized status fields in the
-`Cluster` resource could be misleading or confusing, as they would not
-accurately represent the state across all configured backup methods.
-For this reason, these fields are being deprecated.
-
-Instead, each plugin is responsible for exposing its own backup status
-information and providing metrics back to the instance manager for monitoring
-and operational awareness.
-
-#### Declarative Hibernation in the `cnpg` plugin
-
-In this release, the `cnpg` plugin for `kubectl` transitions from an imperative
-to a [declarative approach for cluster hibernation](declarative_hibernation.md).
-The `hibernate on` and `hibernate off` commands are now convenient shortcuts
-that apply declarative changes to enable or disable hibernation.
-The `hibernate status` command has been removed, as its purpose is now
-fulfilled by the standard `status` command.
-
 ## Verifying release assets
 
 CloudNativePG cryptographically signs all official release assets. Verifying these