pgagroal 1.1.0 is out: what changed, what to migrate, how it's signed

Today we shipped elevarq/pgagroal:1.1.0, our container packaging of upstream pgagroal 2.1.0. This is a feature release with a security-relevant migration. If you run pgagroal in production today, you'll need to do work to upgrade — there is no transparent path from 1.0.x.

This post covers what's new in pgagroal 2.1.0, what operators need to do to migrate, and how the release is verifiable end-to-end.

What changed upstream

pgagroal 2.1.0 is a feature release with two operator-visible breaking changes:

New vault security. AES-256-GCM with a per-installation salt and 600,000 PBKDF2 iterations for key derivation. Existing user/admin/superuser/vault files cannot be decrypted with the new master key.
Management protocol. Exclusively AEAD (GCM); legacy CBC and CTR are removed. A 2.0.x pgagroal-cli cannot speak to a 2.1.0 server, and a 2.1.0 cli cannot speak to a 2.0.x server.

Plus a set of non-breaking improvements:

Built-in health check — pgagroal-cli ping now also reports PostgreSQL backend connectivity, not just the daemon's own state.
Improved failover support — better detection of PostgreSQL primary changes and inconsistencies between server replicas.
Prometheus web console — a built-in UI on the metrics port for inspecting pool state.
RFC 4013 SASLprep for password handling.

The upstream release notes are at github.com/pgagroal/pgagroal/releases/tag/2.1.0.

Why migration is mandatory

The vault re-keying is not optional. Existing encrypted user files cannot be opened with the new format, and a 2.0.x pgagroal-cli cannot use the 2.1.0 management protocol. So upgrading is a coordinated cutover, not a rolling change:

Stop pgagroal.
Delete the encrypted user files (pgagroal_users.conf, pgagroal_frontend_users.conf, pgagroal_admins.conf, pgagroal_superuser.conf, vault users file if you use one) and master.key.
Pull elevarq/pgagroal:1.1.0.
Regenerate the master key with pgagroal-admin master-key. Choose a new passphrase and store it in your secrets manager — there is no recovery if it is lost.
Re-add users with pgagroal-admin user add -f ....
Restart pgagroal.
Upgrade every pgagroal-cli and pgagroal-vault client that talks to this deployment to 2.1.0 in lockstep — operator workstations, CI pipelines, ad-hoc scripts.

Step-by-step procedure with verification, rollback, and the rationale for the Class: breaking-config classification is in our migration guide.

Plan a maintenance window. Connections through pgagroal will be interrupted while the pod or container restarts. Take a snapshot of /etc/pgagroal/ before starting — it is your only roll-back path.

What's in our 1.1.0

The container side is mostly metadata. The real change is the bundled pgagroal version:

Component	Version
pgagroal	2.1.0
Project / Helm chart	1.1.0
Debian base	`bookworm-20260316-slim`
Architectures	`linux/amd64`, `linux/arm64`

Plus an updated CHANGELOG that documents the current Trivy findings: 1 CRITICAL (will_not_fix on zlib's minizip API, not used by pgagroal) and several HIGH advisories with no Debian patch upstream. We checked each with ldd against pgagroal, pgagroal-cli, and pgagroal-admin — none of the affected libraries (libgcrypt20, systemd, ncurses) are linked by any pgagroal binary. They sit in the image as transitive dependencies of postgresql-client and apt tooling, never loaded into a pgagroal process.

How to verify what you pulled

Every release is signed (cosign keyless, GitHub OIDC) and has SBOM and SLSA provenance attached as OCI attestations. To verify the signature:

cosign verify elevarq/pgagroal:1.1.0 \
  --certificate-identity-regexp "https://github.com/Elevarq/pgAgroal/.*" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

That confirms the image was built by the Elevarq publish workflow at refs/tags/v1.1.0 and recorded in the public Sigstore transparency log.

The SBOM (SPDX) and SLSA provenance ride inside the OCI attestation manifest — the third manifest in the index, with platform unknown/unknown. To inspect:

docker buildx imagetools inspect elevarq/pgagroal:1.1.0

For Kubernetes admission, both Sigstore Policy Controller and Kyverno can enforce the cosign signature at admit time. Pin clusters to the exact tag in production:

image:
  repository: elevarq/pgagroal
  tag: "1.1.0"
  pullPolicy: IfNotPresent

Upstream contributions

Several PRs in this release were ours. A representative selection:

Tests for configuration parsing — boolean and byte-size types (#797)
Recognising [prometheus] as a global configuration section (#805)
Tests for log rotation configuration parsing (#810)
Pool saturation test configuration and test case (#815)
Documentation improvements for pipeline behaviour and defaults (#850)
Logging the pipeline=auto fallback when it lands on the session pipeline (#853)
Stop logging backend_secret in cancel-request paths (#868)
Container-side hygiene in upstream Dockerfiles: .dockerignore, removing dev packages from runtime, HEALTHCHECK (#827, #828, #829)

If you maintain a PostgreSQL pooler, upstream welcomes contributions. The codebase is approachable C, the maintainers are responsive, and the test framework recently moved to MCTF for nicer reporting.

What's next for the container

A few things on the near horizon:

Surfacing pgagroal 2.1.0's new Prometheus web console as a dashboard preset.
Integrating pool saturation and pipeline-fallback signals with Arq Signals so plan regressions can correlate with pool state.
Tightening the release-readiness gate that runs before every tag — we just added a check that catches stale elevarq/pgagroal:<old> references in the README and Docker Hub overview, the kind of drift that's easy to miss otherwise.

If you ship elevarq/pgagroal:1.1.0 in production and hit something we missed, the issue tracker is at github.com/Elevarq/pgAgroal/issues.

Verify before you deploy: cosign verify elevarq/pgagroal:1.1.0 ...