docs: import CloudNativePG main

Author: cnpg-bot

website/docs/cloudnative-pg.v1.md

@@ -429,6 +429,24 @@ _Appears in:_
 | `secret` _[LocalObjectReference](https://pkg.go.dev/github.com/cloudnative-pg/machinery/pkg/api#LocalObjectReference)_ | Name of the secret containing the initial credentials for the<br />owner of the user database. If empty a new secret will be<br />created from scratch |  |  |  |
 
 
+#### CatalogComponentImage
+
+
+
+CatalogComponentImage is a named image entry for a non-PostgreSQL component.
+
+
+
+_Appears in:_
+
+- [ImageCatalogSpec](#imagecatalogspec)
+
+| Field | Description | Required | Default | Validation |
+| --- | --- | --- | --- | --- |
+| `key` _string_ | Key is the unique identifier for this image within the catalog. | True |  | MaxLength: 63 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br /> |
+| `image` _string_ | Image is the container image reference. | True |  |  |
+
+
 #### CatalogImage
 
 
@@ -1150,6 +1168,27 @@ ImageCatalog is the Schema for the imagecatalogs API
 | `spec` _[ImageCatalogSpec](#imagecatalogspec)_ | Specification of the desired behavior of the ImageCatalog.<br />More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status | True |  |  |
 
 
+#### ImageCatalogComponentRef
+
+
+
+ImageCatalogComponentRef identifies a named image within the componentImages list of an
+ImageCatalog or ClusterImageCatalog.
+
+
+
+_Appears in:_
+
+- [PgBouncerSpec](#pgbouncerspec)
+
+| Field | Description | Required | Default | Validation |
+| --- | --- | --- | --- | --- |
+| `apiGroup` _string_ | APIGroup is the group for the resource being referenced.<br />If APIGroup is not specified, the specified Kind must be in the core API group.<br />For any other third-party types, APIGroup is required. |  |  |  |
+| `kind` _string_ | Kind is the type of resource being referenced | True |  |  |
+| `name` _string_ | Name is the name of resource being referenced | True |  |  |
+| `key` _string_ | Key identifies the entry within the catalog's componentImages list. | True |  | MaxLength: 63 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$` <br /> |
+
+
 #### ImageCatalogRef
 
 
@@ -1186,6 +1225,7 @@ _Appears in:_
 | Field | Description | Required | Default | Validation |
 | --- | --- | --- | --- | --- |
 | `images` _[CatalogImage](#catalogimage) array_ | List of CatalogImages available in the catalog | True |  | MaxItems: 8 <br />MinItems: 1 <br /> |
+| `componentImages` _[CatalogComponentImage](#catalogcomponentimage) array_ | ComponentImages is a list of named images for components other than PostgreSQL<br />(e.g. pgbouncer). Keys must be unique within a catalog. |  |  | MaxItems: 32 <br /> |
 
 
 #### ImageInfo
@@ -1697,6 +1737,8 @@ _Appears in:_
 | `parameters` _object (keys:string, values:string)_ | Additional parameters to be passed to PgBouncer - please check<br />the CNPG documentation for a list of options you can configure |  |  |  |
 | `pg_hba` _string array_ | PostgreSQL Host Based Authentication rules (lines to be appended<br />to the pg_hba.conf file) |  |  |  |
 | `paused` _boolean_ | When set to `true`, PgBouncer will disconnect from the PostgreSQL<br />server, first waiting for all queries to complete, and pause all new<br />client connections until this value is set to `false` (default). Internally,<br />the operator calls PgBouncer's `PAUSE` and `RESUME` commands. |  | false |  |
+| `image` _string_ | Image is the pgbouncer container image to use. When set, it takes<br />precedence over ImageCatalogRef and the operator default, but is<br />overridden by an explicit image set in the pod template. |  |  |  |
+| `imageCatalogRef` _[ImageCatalogComponentRef](#imagecatalogcomponentref)_ | ImageCatalogRef points to an entry in an ImageCatalog or ClusterImageCatalog.<br />Mutually exclusive with Image. |  |  |  |
 
 
 #### PluginConfiguration
@@ -1933,6 +1975,28 @@ _Appears in:_
 | `enabled` _boolean_ | Enable TLS for the monitoring endpoint.<br />Changing this option will force a rollout of all instances. |  | false |  |
 
 
+#### PoolerPhase
+
+_Underlying type:_ _string_
+
+PoolerPhase represents the lifecycle phase of a Pooler.
+
+_Validation:_
+
+- Enum: [active paused inactive failed]
+
+_Appears in:_
+
+- [PoolerStatus](#poolerstatus)
+
+| Field | Description |
+| --- | --- |
+| `active` | PoolerPhaseActive means the pooler is running normally and serving traffic.<br /> |
+| `paused` | PoolerPhasePaused means PgBouncer is up and running but holding new client<br />connections in the queue because spec.pgbouncer.paused is true. The Deployment<br />keeps reconciling; lifting the pause transitions back to Active.<br /> |
+| `inactive` | PoolerPhaseInactive means the pooler cannot make progress because a<br />prerequisite resource is missing (cluster, secret, certificate). The<br />controller retries periodically until the prerequisite shows up. Check<br />status.phaseReason for the specific cause.<br /> |
+| `failed` | PoolerPhaseFailed means the pooler cannot be reconciled due to a<br />configuration error. Check status.phaseReason for details.<br /> |
+
+
 #### PoolerSecrets
 
 
@@ -1995,6 +2059,9 @@ _Appears in:_
 | --- | --- | --- | --- | --- |
 | `secrets` _[PoolerSecrets](#poolersecrets)_ | The resource version of the config object |  |  |  |
 | `instances` _integer_ | The number of pods trying to be scheduled |  |  |  |
+| `phase` _[PoolerPhase](#poolerphase)_ | Phase summarizes the overall lifecycle state of the Pooler. |  |  | Enum: [active paused inactive failed] <br /> |
+| `phaseReason` _string_ | PhaseReason is a human-readable explanation of the current Phase. |  |  |  |
+| `image` _string_ | Image is the resolved pgbouncer container image that the operator is<br />using for this Pooler, including any override coming from spec.template.<br />While Phase is Active or Paused this field reflects what the Deployment<br />actually runs; while Phase is Inactive or Failed it may carry the last<br />successfully resolved value (or be empty if the Pooler has never reconciled<br />successfully). |  |  |  |
 
 
 #### PoolerType

website/docs/connection_pooling.md

@@ -283,10 +283,63 @@ spec:
             topologyKey: "kubernetes.io/hostname"
 ```
 
-#### Custom image and resource limits
+#### Resource limits
 
-You can specify a custom image and define resource requests/limits. Note that
-the container name is explicitly set to `pgbouncer`.
+You can define resource requests and limits by adding a container named
+`pgbouncer` to the `template` section:
+
+```yaml
+# ...
+  template:
+    metadata:
+      # ...
+    spec:
+      containers:
+        # This name MUST be "pgbouncer"
+        - name: pgbouncer
+          resources:
+            requests:
+              cpu: "0.1"
+              memory: 100Mi
+            limits:
+              cpu: "0.5"
+              memory: 500Mi
+```
+
+## PgBouncer image
+
+By default, CloudNativePG deploys the
+[latest stable PgBouncer image](https://ghcr.io/cloudnative-pg/pgbouncer)
+the operator was built against. You can override that default in three ways.
+When more than one is set, the sources are evaluated top-down — the first
+match in the list below is used; if none match, the operator's built-in
+default applies:
+
+1. An explicit image set on the `pgbouncer` container inside
+   `spec.template.spec.containers` (escape hatch — see
+   [Pod-template override](#pod-template-override) below).
+2. `spec.pgbouncer.image` — an image reference set directly on the `Pooler`.
+3. `spec.pgbouncer.imageCatalogRef` — a reference to an entry in an
+   `ImageCatalog` or `ClusterImageCatalog`.
+
+`spec.pgbouncer.image` and `spec.pgbouncer.imageCatalogRef` are mutually
+exclusive — set at most one.
+
+:::warning[Policy gating]
+    If you enforce admission policies that restrict which PgBouncer images
+    may run, those policies **must gate all three** image sources:
+    `spec.pgbouncer.image`, `spec.pgbouncer.imageCatalogRef`, and the
+    `image` field on a `pgbouncer` container inside
+    `spec.template.spec.containers`. A policy that covers only the first
+    two leaves the pod-template override as an unguarded escape hatch.
+    The same consideration applies to `Cluster.spec.imageName` and
+    `Cluster.spec.imageCatalogRef`.
+:::
+
+### Setting an explicit image
+
+Use `spec.pgbouncer.image` to pin a specific PgBouncer version or pull from
+a private registry:
 
 ```yaml
 apiVersion: postgresql.cnpg.io/v1
@@ -298,29 +351,92 @@ spec:
     name: cluster-example
   instances: 3
   type: rw
+  pgbouncer:
+    poolMode: session
+    image: ghcr.io/cloudnative-pg/pgbouncer:1.25.1
+```
+
+### Using an image catalog
+
+The `Pooler` resource can manage the PgBouncer container image centrally via
+an `ImageCatalog` or `ClusterImageCatalog`, following the same pattern as
+`Cluster` resources (see [Image Catalog](image_catalog.md)). The catalog
+entry is selected by the `key` defined in the catalog's `componentImages`
+list.
 
+Reference a catalog entry with `spec.pgbouncer.imageCatalogRef`:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Pooler
+metadata:
+  name: pooler-example-rw
+spec:
+  cluster:
+    name: cluster-example
+  instances: 3
+  type: rw
+  pgbouncer:
+    poolMode: session
+    imageCatalogRef:
+      apiGroup: postgresql.cnpg.io
+      kind: ImageCatalog
+      name: my-catalog
+      key: pgbouncer
+```
+
+To use a cluster-wide catalog instead, set `kind: ClusterImageCatalog` and
+point `name` at the corresponding resource — the rest of the spec is
+identical.
+
+When a catalog entry is updated, the operator automatically reconciles all
+poolers referencing it and rolls out the new image without any change to the
+`Pooler` spec.
+
+### Pod-template override
+
+The pod template can also carry an `image` on the `pgbouncer` container, in
+which case it overrides every other source (including `spec.pgbouncer.image`
+and `spec.pgbouncer.imageCatalogRef`). Treat this as an **escape hatch** —
+use it only when you need to customize other container-level settings
+(resources, environment, security context) and happen to want to pin the
+image in the same place. For routine image changes, prefer
+`spec.pgbouncer.image` or an image catalog: those fields are validated,
+mutually exclusive, and visible to admission policies that gate the
+PgBouncer image (see [Pod templates](#pod-templates) for the broader
+template mechanics):
+
+```yaml
+# ...
   template:
-    metadata:
-      labels:
-        app: pooler
     spec:
       containers:
-        # This name MUST be "pgbouncer"
         - name: pgbouncer
           image: my-pgbouncer:latest
-          resources:
-            requests:
-              cpu: "0.1"
-              memory: 100Mi
-            limits:
-              cpu: "0.5"
-              memory: 500Mi
 ```
 
+### Monitoring the resolved image
+
+The operator stores the resolved image in `status.image` and reflects the
+outcome in `status.phase`, one of `active`, `paused`, `inactive`, or
+`failed`. On `failed`, `status.phaseReason` describes the cause (for
+example, if the catalog or key does not exist). You can inspect the
+current state with:
+
+```shell
+kubectl get pooler pooler-example-rw -o jsonpath='{.status.image}'
+```
+
+:::note[API reference]
+    For details, see [`PgBouncerSpec`](cloudnative-pg.v1.md#pgbouncerspec)
+    in the API reference.
+:::
+
 ## Service Template
 
-Sometimes, your pooler will require some different labels, annotations, or even change
-the type of the service, you can achieve that by using the `serviceTemplate` field:
+Sometimes, your pooler will require some different labels, annotations, or
+even a different Service type. You can achieve that by using the
+`serviceTemplate` field:
 
 ```yaml
 apiVersion: postgresql.cnpg.io/v1
@@ -740,7 +856,7 @@ following example:
 ## Pausing connections
 
 The `Pooler` specification allows you to take advantage of PgBouncer's `PAUSE`
-and `RESUME` commands, using only declarative configuration. You can ado this
+and `RESUME` commands, using only declarative configuration. You can do this
 using the `paused` option, which by default is set to `false`. When set to
 `true`, the operator internally invokes the `PAUSE` command in PgBouncer,
 which:

website/docs/image_catalog.md

@@ -34,6 +34,9 @@ Both resources share a common schema:
 - **Uniqueness**: The `major` field must be unique within a single catalog.
 - **Extensions**: Support for certified extension container images (available for
   PostgreSQL 18+ via `extension_control_path`).
+- **Component images**: An optional list of named images for non-PostgreSQL
+  components such as PgBouncer (see
+  [Component images](#component-images)).
 
 :::warning
 While the operator trusts the user-defined `major` version without performing
@@ -44,6 +47,45 @@ must ensure the declared major version matches the actual PostgreSQL images to
 maintain compatibility.
 :::
 
+## Component images
+
+In addition to PostgreSQL images, a catalog can store images for other
+components via the `componentImages` field. Each entry is identified by a string
+**key** — a lowercase alphanumeric identifier (hyphens allowed, 1–63
+characters) that must be unique within the catalog.
+
+Currently, the only consumer of component images is the `Pooler` resource,
+which can reference a component image entry to centrally manage the PgBouncer
+container image (see
+[Using an image catalog](connection_pooling.md#using-an-image-catalog)).
+
+The following example defines a namespaced `ImageCatalog` with a PgBouncer
+component image:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: ImageCatalog
+metadata:
+  name: my-catalog
+  namespace: default
+spec:
+  images:
+    - major: 18
+      image: ghcr.io/cloudnative-pg/postgresql:18.4-system-trixie
+  componentImages:
+    - key: pgbouncer
+      image: ghcr.io/cloudnative-pg/pgbouncer:1.25.1
+```
+
+For a cluster-wide catalog, use `kind: ClusterImageCatalog` and drop the
+`metadata.namespace` field (the `spec` is otherwise identical).
+
+:::info
+A catalog may contain up to 32 component image entries. Keys are lowercase
+alphanumeric characters or hyphens, starting and ending with an alphanumeric
+character, up to 63 characters long.
+:::
+
 ## Configuration examples
 
 ### Defining a catalog

website/docs/operator_capability_levels.md

@@ -85,6 +85,9 @@ Beyond just the core PostgreSQL engine, image catalogs now allow you to define
 ensuring that the database and its associated modules are always compatible,
 version-aligned, and treated as a single cohesive unit across your entire
 infrastructure.
+The same catalog mechanism also governs [PgBouncer](connection_pooling.md)
+pooler images, making image catalogs a unified supply-chain primitive across
+the entire PostgreSQL stack managed by the operator.
 
 ### Labels and annotations
 

website/docs/samples/pooler-example-cluster-image-catalog.yaml

@@ -0,0 +1,42 @@
+apiVersion: postgresql.cnpg.io/v1
+kind: ClusterImageCatalog
+metadata:
+  name: cluster-image-catalog-example
+spec:
+  images:
+    - image: ghcr.io/cloudnative-pg/postgresql:18.4-system-trixie
+      major: 18
+  componentImages:
+    - key: pgbouncer
+      image: ghcr.io/cloudnative-pg/pgbouncer:1.25.1
+---
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: cluster-example
+spec:
+  instances: 1
+  imageCatalogRef:
+    apiGroup: postgresql.cnpg.io
+    kind: ClusterImageCatalog
+    name: cluster-image-catalog-example
+    major: 18
+  storage:
+    size: 1Gi
+---
+apiVersion: postgresql.cnpg.io/v1
+kind: Pooler
+metadata:
+  name: pooler-example-rw
+spec:
+  cluster:
+    name: cluster-example
+  instances: 1
+  type: rw
+  pgbouncer:
+    poolMode: session
+    imageCatalogRef:
+      apiGroup: postgresql.cnpg.io
+      kind: ClusterImageCatalog
+      name: cluster-image-catalog-example
+      key: pgbouncer