pgAgroal Enterprise · How-to

Resolve secrets from a Secrets Manager

Instead of static passwords stored on disk, pgagroal can obtain its credentials from a cloud Secrets Manager via ambient workload identity — so you rotate centrally, never ship plaintext secrets in images or config, and pass audits. The Enterprise secret-resolve tool fetches the secret and materializes it into pgagroal's users file before the pooler starts.

How it works

secret-resolveruns in the managed-image entrypoint or an init container: it resolves a credential using ambient identity and writes it into pgagroal’s users file, so pgagroal reads a freshly-resolved credential with no source change (consistent with the attach-alongside model). The secret value is never printed or logged, and on any failure it exits non-zero and writes nothing — it fails closed.

Supported providers

AWS — Secrets Manager and SSM Parameter Store (by ARN).
Azure — Key Vault (by secret URL).
Google Cloud — Secret Manager (by resource name).
file:// — a local file, for development and air-gapped testing.

Authentication is the cloud’s ambient workload identity (IRSA on EKS, workload identity on GKE, managed identity on AKS) — no static cloud keys.

Resolve a credential

Materialize a secret into the users file for a given pgagroal user:

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

-ref is the provider reference (an AWS ARN, an Azure Key Vault URL, a GCP resource name, or a file:// path). If the secret is a JSON payload, extract one field with -json-key:

secret-resolve \
  -ref arn:aws:secretsmanager:eu-west-1:123456789012:secret:pgagroal/app \
  -user app_user \
  -json-key password \
  -out /etc/pgagroal/pgagroal_users.conf

Rotation

Credentials are resolved on demand with a TTL-bounded cache; cap reuse with -max-cache-ttl (e.g. 1h). For automatic refresh, run secret-resolveperiodically to rewrite the users file when the upstream secret rotates; signalling pgagroal to reload is the operator’s hook. The users file is written atomically with 0600 permissions.

The resolver fails closed: if the secret cannot be fetched it exits non-zero and writes nothing, so pgagroal never starts with a stale or empty credential. Wire it as an init container so a resolution failure blocks pod startup rather than degrading silently.

On Kubernetes (the operator)

With the operator you do not set any of this by hand — declare the backend credential on the Pgagroal resource and the managed pod resolves and registers it for you, with no plaintext in the manifest:

apiVersion: pgagroal.elevarq.com/v1alpha1
kind: Pgagroal
metadata:
  name: pg1
spec:
  image: ghcr.io/elevarq/pgagroal-enterprise:<released-version>
  backendHost: my-postgres.default.svc.cluster.local
  backendPort: 5432
  backendSecretRef: arn:aws:secretsmanager:eu-west-1:123456789012:secret:pgagroal/app
  backendUsername: app_user
  backendSecretJSONKey: password

backendUsername is required whenever backendSecretRef is set; point it at a Secrets Manager ARN, Azure Key Vault URL, or GCP resource name, and add backendSecretJSONKeyif the secret is a JSON payload. The pod’s workload identity (IRSA and equivalents) must be allowed to read the secret.

Next steps

Register the users these credentials belong to — see Manage users & credentials.
Review the audit and compliance posture in Security & compliance.