feat(pooler): operator-generated PgBouncer config by mkm29 · Pull Request #3104 · zalando/postgres-operator

mkm29 · 2026-06-07T21:21:29Z

feat(pooler): operator-generated PgBouncer config

Summary

Adds an opt-in mode where the operator renders pgbouncer.ini itself and manages it as an operator-owned ConfigMap, instead of relying on the pooler image to generate its own config from environment variables.

Motivation

The default Spilo/PgBouncer image renders pgbouncer.ini at startup, but some images (e.g. the Chainguard PgBouncer distroless image) ship no such entrypoint. Supporting them previously required a static ConfigMap plus a mutating webhook. This PR moves that responsibility into the operator and removes the workaround.

What changes

When connection_pooler_generate_config: true, for each pooler role the operator:

renders pgbouncer.ini (pool mode, auth type/query, TLS, sizes) and writes it to a <pooler>-config ConfigMap (create/sync/delete in the pooler lifecycle);
mounts it at config_path via subPath, and overrides the container command/args to point PgBouncer at it;
stamps a config checksum annotation on the pod template so config changes trigger a rollout.

Default is false — no behavior change for existing clusters.

New configuration (ConfigMap + `OperatorConfiguration` CRD)

Parameter	Default	Notes
`connection_pooler_generate_config`	`false`	master switch
`connection_pooler_command`	(unset)	keeps image entrypoint when empty
`connection_pooler_args`	`["/etc/pgbouncer/pgbouncer.ini"]`	applied only when generating
`connection_pooler_auth_type`	`scram-sha-256`	written into `pgbouncer.ini`
`connection_pooler_config_path`	`/etc/pgbouncer/pgbouncer.ini`	mount path

Tests

New/extended coverage in config_test.go, connection_pooler_test.go, and pgbouncer_config_test.go (ini rendering incl. TLS, checksum stability, ConfigMap generation, pod-template on/off, and sync create + update-on-drift). Verify by running the tests:

go generate ./...
go test ./pkg/util/config/ -run TestConnectionPoolerGenerateConfigDefaults -v
go test ./pkg/cluster/ -run 'TestConnectionPoolerSizes|TestPoolerEnv|ConnectionPooler|TestGeneratePgBouncerIni' -v

Also updated

Helm values.yaml, operator_parameters.md, both OperatorConfiguration CRDs, and the default operator-configuration manifest.

…rConfiguration

…ackage

Signed-off-by: Mitchell Murphy <mitchell.murphy@defenseunicorns.com>

…on struct

cross-du · 2026-07-15T20:35:33Z

Any chance of this PR and #3105 getting a review soon? It would be a big help for my use case.

FxKu · 2026-07-21T06:49:23Z

The PR is too big for the next release which I plan to drop this week, but I like to review and include it after that.

FxKu · 2026-09-16T13:34:37Z

+                  connection_pooler_config_path:
+                    type: string
+                    default: "/etc/pgbouncer/pgbouncer.ini"
+              patroni:


this diff does not look correct. You only need to add new fields to the pkg.api. package and the CRDs will be generated when running make for example

FxKu · 2026-09-16T13:37:29Z

@@ -0,0 +1,133 @@
+<h1>Operator-generated PgBouncer config (Helm)</h1>


this isn't specific to helm chart, right? Not sure about a new single docs file. Can you move this section to the administrator.md (global config) and add one for users.md, too (local config)

FxKu · 2026-09-16T13:38:09Z

@@ -0,0 +1,986 @@
+---


pls remove this file from the PR

FxKu · 2026-09-16T13:38:20Z

@@ -0,0 +1,84 @@
+---


pls remove this file from the PR

FxKu · 2026-09-16T13:38:47Z

+                  connection_pooler_config_path:
+                    type: string
+                    default: "/etc/pgbouncer/pgbouncer.ini"
+              patroni:


again, looks like the new fields got inserted incorrectly

FxKu · 2026-09-16T13:39:20Z

-                not:
-                  required:
-                  - s3_wal_path
-                  - gs_wal_path


do not remove fields in postgresql CRD

FxKu · 2026-09-16T13:39:30Z

@@ -0,0 +1,4824 @@
+---


pls remove this file from the PR

FxKu · 2026-09-16T13:41:04Z

+	// +kubebuilder:default="scram-sha-256"
+	AuthType string `json:"connection_pooler_auth_type,omitempty"`
+	// +kubebuilder:default="/etc/pgbouncer/pgbouncer.ini"
+	ConfigPath string `json:"connection_pooler_config_path,omitempty"`


I think, it makes sense to also add these fields to the postgresql_type, too. At least we would need this for some teams to still use pgbouncer with md5 while globally we want scram to be the default

FxKu · 2026-09-16T13:54:38Z

+		})
+		volumeMounts = append(volumeMounts, v1.VolumeMount{
+			Name:      configVolumeName,
+			MountPath: c.OpConfig.ConnectionPooler.ConfigPath,


not 100% sure that this variable is always set at this point

FxKu · 2026-09-16T13:55:22Z

+		if len(c.OpConfig.ConnectionPooler.Command) > 0 {
+			poolerContainer.Command = c.OpConfig.ConnectionPooler.Command
+		}
+		poolerContainer.Args = c.OpConfig.ConnectionPooler.Args


same here. Can Args be empty? Should we always set it or use an if like with Command

FxKu · 2026-09-16T13:58:57Z

+		checksum, err := c.connectionPoolerConfigChecksum(role)
+		if err != nil {
+			return nil, err
+		}


when we maybe just raise a warning when the checksum annotation is missing? I would not break the cluster creation just because an annotation of a pooler could not get generated

FxKu · 2026-09-16T14:00:49Z

  - Postgres Operator UI: 'operator-ui.md'
  - Admin guide: 'administrator.md'
  - User guide: 'user.md'
+  - PgBouncer generated config: 'pgbouncer-generated-config.md'


like I wrote above I would not create a dedicated docs file for this config option now but rather include it in admin and user docs

mkm29 added 16 commits June 5, 2026 13:44

feat(config): add connection_pooler generate-config fields

9787922

test(config): cover ConfigPath and Command overrides

c49aac8

feat(crd): mirror connection_pooler generate-config fields in Operato…

bf0aa1e

…rConfiguration

style(crd): gofmt connection pooler config fields

1383829

refactor(pooler): extract connectionPoolerSizes helper

ac8668a

docs(pooler): fix godoc placement after sizes extraction

db68903

feat(pooler): render pgbouncer.ini, checksum, and config map

3dabf6c

style(pooler): use acid.zalan.do domain for config checksum annotation

be3fbda

feat(pooler): mount generated config and override command/args

8641fbd

refactor(pooler): extract connectionPoolerConfigMapName helper

c5e0b43

feat(pooler): create/sync/delete generated config map in lifecycle

e79c7d3

test(pooler): cover config map update-on-drift branch

c6d0476

docs(pooler): document and expose generate-config parameters

3d97c71

docs(pooler): align values.yaml args with manifest and tidy param docs

4557229

test(pooler): refactor connection pooler config tests to use assert p…

964fc73

…ackage

docs(pooler): add documentation for operator-generated PgBouncer config

b8bd7ed

Signed-off-by: Mitchell Murphy <mitchell.murphy@defenseunicorns.com>

mkm29 requested review from FxKu, Jan-M, idanovinda, jopadi, mikkeloscar and sdudoladov as code owners June 7, 2026 21:21

FxKu added the minor label Jun 8, 2026

mkm29 and others added 3 commits June 25, 2026 17:13

Merge branch 'master' into feat/enhanced-pooler-config

4af7b5a

Merge branch 'master' into feat/enhanced-pooler-config

67046ef

Merge branch 'master' into feat/enhanced-pooler-config

8781170

FxKu added this to the wishlist milestone Jun 29, 2026

fix(pooler): resolved duplicate fields in ConnectionPoolerConfigurati…

b11f5e5

…on struct

Merge branch 'master' into feat/enhanced-pooler-config

d762e70

FxKu reviewed Sep 16, 2026

View reviewed changes

Comment thread manifests/acid.zalan.do_postgresteams.yaml

@@ -0,0 +1,84 @@

---

FxKu Sep 16, 2026

Copy link
Copy Markdown

Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pls remove this file from the PR

FxKu reviewed Sep 16, 2026

View reviewed changes

Comment thread manifests/postgresql.crd.yaml-e

@@ -0,0 +1,4824 @@

---

FxKu Sep 16, 2026

Copy link
Copy Markdown

Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pls remove this file from the PR

FxKu reviewed Sep 16, 2026

View reviewed changes

		@@ -0,0 +1,133 @@
		<h1>Operator-generated PgBouncer config (Helm)</h1>

Conversation

mkm29 commented Jun 7, 2026

feat(pooler): operator-generated PgBouncer config

Summary

Motivation

What changes

New configuration (ConfigMap + OperatorConfiguration CRD)

Tests

Also updated

Uh oh!

cross-du commented Jul 15, 2026

Uh oh!

FxKu commented Jul 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FxKu Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FxKu Sep 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

New configuration (ConfigMap + `OperatorConfiguration` CRD)

FxKu Sep 16, 2026 •

edited

Loading

FxKu Sep 16, 2026 •

edited

Loading