pgAgroal Enterprise · How-to

Run health-gated upgrades

Upgrades of the managed pgagroal image are staged, observed, and reversible. The Enterprise control plane upgrades a canary first, evaluates its health against thresholds, and only then rolls the rest of the fleet forward — automatically reverting on regression. There is no upstream pgagroal change.

Unknown health is treated as a breach. If the control plane cannot scrape an instance's metrics, it does not roll forward on the uncertainty — it rolls back. This fail-safe default keeps every upgrade traceable and aligned with our audit-readiness goals.

This page covers upgrading the managed pooler image. To upgrade the Helm chart itself (operator + CRD), note that helm upgrade does not upgrade CRDs — apply the new CRD explicitly after upgrading. See the CRD-upgrade step in the install tutorial.

The flow

The orchestrator (control-plane/internal/upgrade) moves through five steps, auditing each one before and after it acts:

Plan— record each instance's current image (for an exact rollback) and the target image, then audit the plan.
Canary — upgrade a subset first (one instance or a fleet group). The intent is persisted before the image change (audit-before-act).
Observe + gate— after an observation window, evaluate the canary's native metrics and control-plane health against thresholds. A breach, or a failed image change, rolls the canary back to its prior image.
Roll forward — upgrade the remainder, then gate the whole fleet again. Any breach rolls back everything moved.
Audit — every step (plan, apply, rollback, final outcome) is recorded in the tamper-evident audit log.

What the health gate evaluates

The ThresholdEvaluator checks the canary against three signals. A breach of any one fails the gate and triggers a rollback:

saturation — connection pool saturation on the upgraded instances.
queueing — client queueing waiting for a backend connection.
failed servers — backend servers reported as failed.

A metrics scrape error is not a pass. Unknown health is treated as a breach, so the evaluator never lets an upgrade proceed on missing data.

Wire it to your environment

Two interfaces connect the orchestrator to a real cluster:

ImageSetter — applies an image to an instance and reads its current image. Backed by the operator (it updates the Pgagroal CR's image) or by the control-plane Configurator.
MetricsSource— samples an instance's pgagroal metrics. Backed by the health prober that scrapes the Prometheus endpoint.

Relationship to GitOps

GitOps applies the desired image; the health-gated upgrade provides the safe path to get there — canary, watch, and automatically revert on regression — instead of a blind rolling update.

Next steps

Run preflight checks — validate the target version before you start the upgrade.
Control plane reference — the fleet, health, and audit packages the orchestrator builds on.