pgAgroal Enterprise · How-to

Run preflight checks

The preflight checker tells an operator whether a pgAgroal Enterprise install is production-ready before traffic is moved to it. It runs a set of independent checks and exits non-zero if any required check fails. It ships in the Enterprise image, so it runs the same way as a CLI or a Kubernetes Job.

Advisory results report WARN and do not fail the run. Only a failed required check produces a non-zero exit. Gating a rollout on a green preflight keeps cutovers traceable and aligned with our audit-readiness goals.

The checks

Preflight runs a set of independent checks: a core set always runs, plus optional checks that are added only when the input they need is configured. Required checks fail the run; advisory checks only warn. So a given run reports between five and six checks depending on what you have configured.

required-config (required) — required env is set, for example PG_BACKEND_HOST.
backend-reachable (required when a backend is set) — TCP reach to the backend PostgreSQL.
metrics-scrapeable (required) — the pgagroal Prometheus endpoint returns 200 and pgagroal_* metrics.
image-signature (advisory) — cosign verify of the image; warns if cosign is absent.
sbom-attestation (advisory) — cosign verify-attestation --type spdxjson.
secret-resolve (advisory, only when PGAGROAL_BACKEND_SECRET_REF is set) — the backend secret reference resolves; the value is never printed. Without a secret reference this check is skipped entirely and does not appear in the output.

Run it as a CLI

Set the environment the checks read and run preflight from inside the Enterprise image:

PG_BACKEND_HOST=db.internal PG_BACKEND_PORT=5432 \
PGAGROAL_METRICS_URL=http://pg1:2346/metrics \
PGAGROAL_IMAGE=ghcr.io/elevarq/pgagroal-enterprise@sha256:... \
preflight

Exit code 0 means ready. Exit code 1 means a required check failed; the FAIL lines say what to fix.

Run it as a Kubernetes Job

The same binary runs as a one-shot Job. Use restartPolicy: Never so the exit code surfaces as a Succeeded or Failed Job:

apiVersion: batch/v1
kind: Job
metadata:
  name: pgagroal-preflight
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: preflight
          image: ghcr.io/elevarq/pgagroal-enterprise:<version>
          command: ["preflight"]
          env:
            - name: PG_BACKEND_HOST
              value: db.internal
            - name: PGAGROAL_METRICS_URL
              value: http://pg1.default.svc:2346/metrics

Gate a rollout on the result

Because preflight exits non-zero on a required failure, you can gate a rollout on the Job succeeding — for example an Argo CD PreSync hook, or a CI step that blocks promotion until the Job reports Succeeded.

Next steps

Install with Helm — stand up the install the preflight checks validate.
Run an upgrade — run preflight against the new version before cutting traffic over.