pgAgroal Enterprise · Reference
Fleet control plane
The fleet control plane manages many standard pgagroal instances as one fleet — inventory, health, drift, and audited config-apply — over pgagroal's existing public interfaces only. This page catalogues its subsystems, bundled CLI tools, operator authentication, secret-resolution backends, and the tamper-evident audit log.
Subsystems
The control plane is composed of focused internal packages, each owning one responsibility:
fleet— domain types plus theStore(in-memory store and PostgreSQL).cluster— Postgres leader-lease and fencing token for delegated consensus.limits— lease-based global resource cap using no-overshoot share leasing.discovery— static registry plus Kubernetes discovery of pgagroal instances.health— probes instances with a real metrics prober, aggregates results, and marks unreachable instances stale.pgctl— applies configuration via pgagroal-cli remote management (the write path).drift— read-only declared-vs-actual configuration diff.audit— hash-chained tamper-evident log with audit-before-act semantics.apply— mutating apply with dry-run, authorization, and partial-failure handling.auth— operator authentication (bearer token, OIDC-ready).pgbconv— convertspgbouncer.inito pgagroal config plus[databases]routing and a migration report.secrets— resolves credentials from AWS SM/SSM, Azure KV, and GCP SM, then materializes them for pgagroal.auditexport— scope-limited export with redaction, file/S3 sinks, an async buffer, and verification.
Bundled CLI tools
The control plane ships standalone command-line tools alongside the server entrypoint:
pgbouncer-import— migratepgbouncer.initopgagroal.confand emit a migration report.secret-resolve— resolve asecret_refand materialize pgagroal's users file.audit-verify— re-verify an exported audit batch's hash chain.support— collect a support bundle.
Operator authentication
The auth subsystem authenticates operators with bearer tokens and is OIDC-ready, so it can be wired to an identity provider without source changes. Authorization is enforced on the mutating apply path: unauthorized requests are rejected before any configuration is written.
Secret-resolution backends
The secretssubsystem resolves pgagroal credentials from a secret manager via ambient workload identity, then materializes them into pgagroal's users file atomically with 0600 permissions — no pgagroal source change. The backend is inferred from the reference shape. Supported backends:
- AWS Secrets Manager
- AWS SSM Parameter Store
- Azure Key Vault
- GCP Secret Manager
The Resolver adds a TTL-bounded cache, JSON-key extraction, and fail-closed behaviour. The secret value is never logged. Real cloud SDKs are compiled in; unit tests use a Fetcher seam, and a live test is env-gated behind PGAGROAL_SECRETS_LIVE=1.
Resolve a reference and materialize the users file with the bundled CLI:
secret-resolve -ref <secret_ref> -user <name> -out /etc/pgagroal/pgagroal_users.confTamper-evident audit log
The audit subsystem records actions to a hash-chained, tamper-evident log and follows audit-before-act semantics: the action is recorded before it is performed. Because each entry is chained to the previous one, tampering with or removing an entry breaks the chain and is detectable.
Exported batches (via auditexport) can be re-verified independently using the bundled CLI:
audit-verify <exported-batch>The hash-chained log is part of the audit-readiness posture, aligned with our compliance-readiness goals. See Security and compliance for how it fits the broader hardening story.
Related
- Architecture — the alongside attach model and the data-plane / control-plane split.
- Upgrades — managed, audited upgrades across the fleet.
- Security and compliance — operator auth, secrets, and the audit log in context.