Production-grade Docker container and Helm chart for pgagroal -- a high-performance PostgreSQL connection pooler.
From Elevarq — PostgreSQL tools for engineering teams.
- pgagroal 2.1.0
- Base image: debian:bookworm-20260316-slim
- Architectures: amd64, arm64
A ready-to-deploy packaging of pgagroal that builds from source, runs as a non-root container, and deploys to Kubernetes via Helm. Designed for AWS EKS with RDS backends, but works anywhere Docker or Kubernetes runs.
- Multi-stage Dockerfile building pgagroal from source (pinned versions, reproducible)
- Helm chart with PDB, security contexts, probes, and Prometheus metrics
- Non-root runtime (UID 1000), all capabilities dropped, seccomp enforced, read-only root filesystem
- Configuration via environment variables -- no config files to mount
- Automated test suite: integration, resilience, pooling validation, failure modes
- CI pipeline: hadolint, ShellCheck, Helm lint, integration and resilience tests
- Scripted monthly upstream refresh workflow with dry-run support
make run
psql -h localhost -p 6432 -U testuser -d testdb -c 'SELECT 1;'
make stopmake build
helm install pgagroal helm/pgagroal/ \
--set postgresql.host=my-postgres \
--set credentials.username=app \
--set credentials.password=secret \
-n pgagroal --create-namespace| Guide | Description |
|---|---|
| First client deployment | Step-by-step EKS install with acceptance checklist |
| Post-deployment verification | 8-step verification and handoff procedure |
| EKS infrastructure reference | ECR, IRSA, Security Groups, monitoring |
Example values files:
helm/pgagroal/values-client-minimal.yaml # 3 fields: image, RDS host, secret
helm/pgagroal/values-client-example.yaml # Full template with CHANGEME markers
helm/pgagroal/values-eks-example.yaml # Production EKS with AZ anti-affinity| Guide | Description |
|---|---|
| Operations | Startup sequence, probes, scaling, troubleshooting |
| Failure modes | 9 failure scenarios with recovery paths |
| Secret rotation | Credential rotation for Docker and K8s |
Production defaults: ev_backend = epoll (avoids upstream io_uring segfault), rolling restart for all config changes (reload is unsafe), pgagroal-cli ping checks daemon only (not backend). See operations guide for details.
make test # integration (CI)
make test-backend-restart # resilience (CI)
make test-concurrent # concurrent load
make test-pooling # pool behavior validation
make test-startup-failure # startup failure mode (CI)
make test-invalid-creds # credential error handling
make test-all # everything| Variable / Helm value | Default | Description |
|---|---|---|
PGAGROAL_HOST / pgagroal.host |
* |
Bind address |
PGAGROAL_PORT / pgagroal.port |
6432 |
Bind port |
PG_BACKEND_HOST / postgresql.host |
postgres |
PostgreSQL host |
PG_BACKEND_PORT / postgresql.port |
5432 |
PostgreSQL port |
MAX_CONNECTIONS / pgagroal.maxConnections |
100 |
Maximum pool connections |
PGAGROAL_LOG_LEVEL / pgagroal.logLevel |
info |
Log level |
Update the bundled pgagroal version:
make refresh-dry-run VERSION=2.1.0 # preview
make refresh VERSION=2.1.0 # update, build, testGuide: docs/release/monthly-refresh.md | Spec: specifications/release-refresh/spec.md
make prepare-release # check consistency, print tag/push commands
make release-check # non-interactive consistency checkGuide: docs/release/release-process.md | Checklist: docs/release/release-checklist.md
Published images are built by GitHub Actions from this repository and
pushed to Docker Hub as multi-arch manifests (linux/amd64,
linux/arm64). Each image includes:
- SBOM attestation (build-time software bill of materials)
- Provenance attestation (SLSA,
mode=max) - Cosign signature (keyless, via GitHub OIDC)
Verify a signature before deployment:
cosign verify elevarq/pgagroal:latest \
--certificate-identity-regexp "https://github.com/Elevarq/pgAgroal/.*" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"Inspect attestations:
docker buildx imagetools inspect elevarq/pgagroal:latestIn production, pin a version tag rather than latest:
image:
repository: elevarq/pgagroal
tag: "1.1.0"
pullPolicy: IfNotPresentVerify the pinned image before rolling out:
cosign verify elevarq/pgagroal:1.1.0 \
--certificate-identity-regexp "https://github.com/Elevarq/pgAgroal/.*" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com"Cosign verification confirms the image was signed by the Elevarq GitHub Actions workflow. SBOM and provenance attestations provide additional supply-chain metadata for audit and compliance.
Clusters that enforce image trust can require valid Cosign signatures at admission time using tools such as Sigstore Policy Controller or Kyverno.
├── Dockerfile, entrypoint.sh, *.template Container build
├── docker-compose.yml Local dev stack
├── Makefile All targets
├── helm/pgagroal/ Helm chart + values examples
├── test/
│ ├── integration/ Connectivity tests
│ ├── resilience/ Restart, concurrent, startup failure
│ ├── validation/ Pooling, credentials
│ └── refresh/ Refresh script tests
├── scripts/ Refresh and release tooling
├── docs/
│ ├── deployment/ Install, verify, EKS
│ ├── operations/ Ops guide, failure modes, secrets
│ └── release/ Process, checklist, refresh, GitHub
├── specifications/ STDD specs
└── VERSION, CHANGELOG.md, LICENSE Metadata
- Prometheus metrics validation and Grafana dashboard template
- Elevarq observability sidecar integration (chart stub exists)
- TLS termination configuration guide
| Component | Version |
|---|---|
| Project | 1.1.0 |
| pgagroal | 2.1.0 |
| Debian base | bookworm-20260316-slim |
| PostgreSQL (compose) | 17.4-bookworm |
| Helm chart | 1.1.0 |
- Elevarq — PostgreSQL tools for engineering teams
- Project page on elevarq.com — documentation, examples, and support contracts
- Arq-Signals — open-source PostgreSQL telemetry collector
- Upstream pgagroal — the connection pooler this container packages