feat(pooler): allow PgBouncer image management via image catalogs (cloudnative-pg#10568)

Users can now manage the PgBouncer image centrally by referencing an
entry in an `ImageCatalog` or `ClusterImageCatalog` through the new
`spec.pgbouncer.imageCatalogRef` field. Alternatively, a specific image
can still be pinned via `spec.pgbouncer.image`.

When a catalog entry is updated, all `Poolers` referencing it are
automatically reconciled and the `Deployment` rolls out the new image
without any change to the `Pooler` spec. The resolved image is reported
in `status.image`. A new `status.phase` (`active`, `paused`, `inactive`,
or `failed`) summarises the lifecycle, with `status.phaseReason`
carrying a human-readable cause when something is wrong.

`kubectl get pooler` also gains a `Phase` column for at-a-glance
visibility.

Upgrade note: after upgrading, each existing `Pooler`-managed
`Deployment` receives a one-time annotation patch
(`cnpg.io/poolerSpecHash`). The pod template is unchanged, so this patch
alone does not roll pgbouncer pods. If the upgrade also bumps the
default pgbouncer image, that bump (not the hash change) will trigger a
normal rolling restart.

Signed-off-by: Leonardo Cecchi <leonardo.cecchi@enterprisedb.com>
Signed-off-by: Armando Ruocco <armando.ruocco@enterprisedb.com>
Signed-off-by: Niccolò Fei <niccolo.fei@enterprisedb.com>
Signed-off-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>
Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Co-authored-by: Armando Ruocco <armando.ruocco@enterprisedb.com>
Co-authored-by: Niccolò Fei <niccolo.fei@enterprisedb.com>
Co-authored-by: Marco Nenciarini <marco.nenciarini@enterprisedb.com>
Co-authored-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>

Author: 5 people

.wordlist-en-custom.txt

@@ -71,6 +71,7 @@ CVE
 CVEs
 CannotReconcile
 Canovai
+CatalogComponentImage
 CatalogImage
 CatalogImages
 Cecchi
@@ -97,6 +98,7 @@ ClusterSpec
 ClusterStatus
 CodeQL
 ColumnName
+ComponentImages
 ConditionStatus
 ConfigMap
 ConfigMapKeySelector
@@ -215,6 +217,7 @@ IaC
 Ibryam
 IfNotPresent
 ImageCatalog
+ImageCatalogComponentRef
 ImageCatalogRef
 ImageCatalogSpec
 ImageInfo
@@ -369,6 +372,11 @@ PoolerIntegrations
 PoolerList
 PoolerMonitoringConfiguration
 PoolerMonitoringTLSConfiguration
+PoolerPhase
+PoolerPhaseActive
+PoolerPhaseFailed
+PoolerPhaseInactive
+PoolerPhasePaused
 PoolerSecrets
 PoolerSpec
 PoolerStatus
@@ -698,6 +706,7 @@ cGFzc
 caSecretVersion
 cannotReconcile
 catalogName
+catalogcomponentimage
 catalogimage
 cb
 cd
@@ -743,6 +752,7 @@ collationVersion
 columnValue
 commandError
 commandOutput
+componentImages
 conf
 config
 config's
@@ -963,6 +973,7 @@ imagePullPolicy
 imagePullSecrets
 imageVolume
 imagecatalog
+imagecatalogcomponentref
 imagecatalogref
 imagecatalogs
 imagecatalogspec
@@ -1251,6 +1262,7 @@ poolerName
 poolerintegrations
 poolermonitoringconfiguration
 poolermonitoringtlsconfiguration
+poolerphase
 poolers
 poolersecrets
 poolerspec

api/v1/imagecatalog_funcs.go

@@ -60,3 +60,14 @@ func (spec *ImageCatalogSpec) FindExtensionsForMajor(major int) ([]ExtensionConf
 
 	return nil, false
 }
+
+// FindComponentImageForKey finds the image string for a given component-image key.
+func (spec *ImageCatalogSpec) FindComponentImageForKey(key string) (string, bool) {
+	for _, entry := range spec.ComponentImages {
+		if entry.Key == key {
+			return entry.Image, true
+		}
+	}
+
+	return "", false
+}

api/v1/imagecatalog_funcs_test.go

@@ -88,3 +88,42 @@ var _ = Describe("image catalog", func() {
 		Expect(extensions).To(BeNil())
 	})
 })
+
+var _ = Describe("image catalog component images", func() {
+	catalogSpec := ImageCatalogSpec{
+		Images: []CatalogImage{
+			{Image: "test:16", Major: 16},
+		},
+		ComponentImages: []CatalogComponentImage{
+			{Key: "pgbouncer", Image: "pgbouncer:1.24.0"},
+			{Key: "other-tool", Image: "other-tool:1.0.0"},
+		},
+	}
+
+	It("looks up a component image by key", func() {
+		image, ok := catalogSpec.FindComponentImageForKey("pgbouncer")
+		Expect(ok).To(BeTrue())
+		Expect(image).To(Equal("pgbouncer:1.24.0"))
+	})
+
+	It("looks up a second component image by key", func() {
+		image, ok := catalogSpec.FindComponentImageForKey("other-tool")
+		Expect(ok).To(BeTrue())
+		Expect(image).To(Equal("other-tool:1.0.0"))
+	})
+
+	It("returns false when the key is not present", func() {
+		image, ok := catalogSpec.FindComponentImageForKey("nonexistent")
+		Expect(ok).To(BeFalse())
+		Expect(image).To(BeEmpty())
+	})
+
+	It("returns false when componentImages is empty", func() {
+		emptySpec := ImageCatalogSpec{
+			Images: []CatalogImage{{Image: "test:16", Major: 16}},
+		}
+		image, ok := emptySpec.FindComponentImageForKey("pgbouncer")
+		Expect(ok).To(BeFalse())
+		Expect(image).To(BeEmpty())
+	})
+})

api/v1/imagecatalog_types.go

@@ -30,6 +30,26 @@ type ImageCatalogSpec struct {
 	// +kubebuilder:validation:MaxItems=8
 	// +kubebuilder:validation:XValidation:rule="self.all(e, self.filter(f, f.major==e.major).size() == 1)",message=Images must have unique major versions
 	Images []CatalogImage `json:"images"`
+
+	// ComponentImages is a list of named images for components other than PostgreSQL
+	// (e.g. pgbouncer). Keys must be unique within a catalog.
+	// +optional
+	// +listType=map
+	// +listMapKey=key
+	// +kubebuilder:validation:MaxItems=32
+	// +kubebuilder:validation:XValidation:rule="self.all(e, self.filter(f, f.key==e.key).size() == 1)",message="Component image keys must be unique"
+	ComponentImages []CatalogComponentImage `json:"componentImages,omitempty"`
+}
+
+// CatalogComponentImage is a named image entry for a non-PostgreSQL component.
+type CatalogComponentImage struct {
+	// Key is the unique identifier for this image within the catalog.
+	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
+	// +kubebuilder:validation:MaxLength=63
+	Key string `json:"key"`
+
+	// Image is the container image reference.
+	Image string `json:"image"`
 }
 
 // CatalogImage defines the image and major version

api/v1/pooler_types.go

@@ -26,6 +26,30 @@ import (
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 )
 
+// PoolerPhase represents the lifecycle phase of a Pooler.
+// +kubebuilder:validation:Enum=active;paused;inactive;failed
+type PoolerPhase string
+
+const (
+	// PoolerPhaseActive means the pooler is running normally and serving traffic.
+	PoolerPhaseActive PoolerPhase = "active"
+
+	// PoolerPhasePaused means PgBouncer is up and running but holding new client
+	// connections in the queue because spec.pgbouncer.paused is true. The Deployment
+	// keeps reconciling; lifting the pause transitions back to Active.
+	PoolerPhasePaused PoolerPhase = "paused"
+
+	// PoolerPhaseInactive means the pooler cannot make progress because a
+	// prerequisite resource is missing (cluster, secret, certificate). The
+	// controller retries periodically until the prerequisite shows up. Check
+	// status.phaseReason for the specific cause.
+	PoolerPhaseInactive PoolerPhase = "inactive"
+
+	// PoolerPhaseFailed means the pooler cannot be reconciled due to a
+	// configuration error. Check status.phaseReason for details.
+	PoolerPhaseFailed PoolerPhase = "failed"
+)
+
 // PoolerType is the type of the connection pool, meaning the service
 // we are targeting. Allowed values are `rw` and `ro`.
 // +kubebuilder:validation:Enum=rw;ro;r
@@ -188,7 +212,21 @@ type ServiceTemplateSpec struct {
 	Spec corev1.ServiceSpec `json:"spec,omitempty"`
 }
 
+// ImageCatalogComponentRef identifies a named image within the componentImages list of an
+// ImageCatalog or ClusterImageCatalog.
+type ImageCatalogComponentRef struct {
+	// +kubebuilder:validation:XValidation:rule="self.kind == 'ImageCatalog' || self.kind == 'ClusterImageCatalog'",message="Only ImageCatalog and ClusterImageCatalog are supported"
+	// +kubebuilder:validation:XValidation:rule="self.apiGroup == 'postgresql.cnpg.io'",message="apiGroup must be postgresql.cnpg.io"
+	corev1.TypedLocalObjectReference `json:",inline"`
+
+	// Key identifies the entry within the catalog's componentImages list.
+	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`
+	// +kubebuilder:validation:MaxLength=63
+	Key string `json:"key"`
+}
+
 // PgBouncerSpec defines how to configure PgBouncer
+// +kubebuilder:validation:XValidation:rule="!(has(self.image) && has(self.imageCatalogRef))",message="image and imageCatalogRef are mutually exclusive"
 type PgBouncerSpec struct {
 	// The pool mode. Default: `session`.
 	// +kubebuilder:default:=session
@@ -250,16 +288,45 @@ type PgBouncerSpec struct {
 	// +kubebuilder:default:=false
 	// +optional
 	Paused *bool `json:"paused,omitempty"`
+
+	// Image is the pgbouncer container image to use. When set, it takes
+	// precedence over ImageCatalogRef and the operator default, but is
+	// overridden by an explicit image set in the pod template.
+	// +optional
+	Image string `json:"image,omitempty"`
+
+	// ImageCatalogRef points to an entry in an ImageCatalog or ClusterImageCatalog.
+	// Mutually exclusive with Image.
+	// +optional
+	ImageCatalogRef *ImageCatalogComponentRef `json:"imageCatalogRef,omitempty"`
 }
 
 // PoolerStatus defines the observed state of Pooler
 type PoolerStatus struct {
 	// The resource version of the config object
 	// +optional
 	Secrets *PoolerSecrets `json:"secrets,omitempty"`
+
 	// The number of pods trying to be scheduled
 	// +optional
 	Instances int32 `json:"instances,omitempty"`
+
+	// Phase summarizes the overall lifecycle state of the Pooler.
+	// +optional
+	Phase PoolerPhase `json:"phase,omitempty"`
+
+	// PhaseReason is a human-readable explanation of the current Phase.
+	// +optional
+	PhaseReason string `json:"phaseReason,omitempty"`
+
+	// Image is the resolved pgbouncer container image that the operator is
+	// using for this Pooler, including any override coming from spec.template.
+	// While Phase is Active or Paused this field reflects what the Deployment
+	// actually runs; while Phase is Inactive or Failed it may carry the last
+	// successfully resolved value (or be empty if the Pooler has never reconciled
+	// successfully).
+	// +optional
+	Image string `json:"image,omitempty"`
 }
 
 // PoolerSecrets contains the versions of all the secrets used
@@ -310,6 +377,7 @@ type SecretVersion struct {
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
 // +kubebuilder:printcolumn:name="Cluster",type="string",JSONPath=".spec.cluster.name"
 // +kubebuilder:printcolumn:name="Type",type="string",JSONPath=".spec.type"
+// +kubebuilder:printcolumn:name="Phase",type="string",JSONPath=".status.phase"
 // +kubebuilder:subresource:scale:specpath=.spec.instances,statuspath=.status.instances
 
 // Pooler is the Schema for the poolers API

api/v1/zz_generated.deepcopy.go

@@ -46,6 +46,35 @@ spec:
               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
             properties:
+              componentImages:
+                description: |-
+                  ComponentImages is a list of named images for components other than PostgreSQL
+                  (e.g. pgbouncer). Keys must be unique within a catalog.
+                items:
+                  description: CatalogComponentImage is a named image entry for a
+                    non-PostgreSQL component.
+                  properties:
+                    image:
+                      description: Image is the container image reference.
+                      type: string
+                    key:
+                      description: Key is the unique identifier for this image within
+                        the catalog.
+                      maxLength: 63
+                      pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
+                      type: string
+                  required:
+                  - image
+                  - key
+                  type: object
+                maxItems: 32
+                type: array
+                x-kubernetes-list-map-keys:
+                - key
+                x-kubernetes-list-type: map
+                x-kubernetes-validations:
+                - message: Component image keys must be unique
+                  rule: self.all(e, self.filter(f, f.key==e.key).size() == 1)
               images:
                 description: List of CatalogImages available in the catalog
                 items: