pgAgroal Enterprise · How-to

Manage users & credentials

pgagroal authenticates the users that connect through it. This guide covers registering those users, the users file, the hardened allow_unknown_users default, and rotating credentials — including sourcing them from a cloud Secrets Manager.

The hardened default

The Elevarq pgAgroal Enterprise image ships with allow_unknown_users=false by default (matching the hardened free container). Unknown users are not passed through to the backend — every user that connects through the pooler must be registered with pgagroal first. This is the secure posture: the pooler is an explicit auth gate, not an open passthrough.

To restore transparent passthrough, set spec.allowUnknownUsers: true on the Pgagroal custom resource (the operator applies it to the pod), or PGAGROAL_ALLOW_UNKNOWN_USERS=true when running the container directly — but the recommended path is to register users, as below.

Register a user

pgagroal keeps its frontend users in a users file, managed with pgagroal-admin. Add a user (you are prompted for, or pipe in, the password):

pgagroal-admin -f /etc/pgagroal/pgagroal_users.conf user add

The users file is referenced by pgagroal at startup. In Kubernetes, keep it on a writable mount and treat it as derived state — generate it at startup rather than baking credentials into the image. For the full command set (add / edit / delete / list) and the user-vault details, see the upstream manual:

Remote management — admin users and the management interface.
Vault — the user vault.
Configuration — the full reference.

Source credentials from a Secrets Manager

Rather than managing passwords by hand, resolve them from a cloud Secrets Manager at startup and on rotation. The Enterprise secret-resolve tool materializes a credential into the users file for a given user — no plaintext on disk, central rotation:

secret-resolve \
  -ref <secret_ref> \
  -user app_user \
  -out /etc/pgagroal/pgagroal_users.conf

See Resolve secrets from a Secrets Manager for providers, JSON payloads, rotation and the fail-closed behaviour.

Rotate credentials

Manual: update the user with pgagroal-admin, then trigger a pgagroal reload/restart.
Secrets-manager-backed: rotate the secret centrally; a periodic secret-resolve rewrites the users file, and your reload hook picks it up.

Next steps

Migrating from PgBouncer? Carry your existing users across via the PgBouncer migration guide.
Harden the surrounding deployment in Security & compliance.