Kubernetes Deployment (Helm)

The Helm chart at deploy/helm/abrq-dip/ is the primary production deployment path. It deploys four application components — API (default 2 replicas), Celery worker (default 2 replicas), a singleton Celery beat scheduler, and the nginx-served frontend — plus, by default, an in-cluster PostgreSQL and Redis via vendored subcharts.

Prerequisites#

The chart's own version is 0.2.0 (Chart.yaml); the subchart dependencies — postgresql 16.7.27 and redis 20.13.4 — are vendored as committed tarballs in deploy/helm/abrq-dip/charts/, so installation needs no chart-repository access.

The required runtime Secret#

The chart refuses to render without an existing Secret named by existingSecret (default abrq-dip-runtime). Every backend pod loads it via envFrom. With the in-cluster subcharts on (the default), the database and Redis URLs are auto-wired, so the Secret only needs the non-connection secrets:

kubectl create secret generic abrq-dip-runtime \
  --from-literal=ABRQ_MASTER_KEY=<FERNET_KEY> \
  --from-literal=ABRQ_JWT_SECRET=<JWT_SECRET> \
  --from-literal=ABRQ_INITIAL_ADMIN_PASSWORD=<ADMIN_PASSWORD> \
  --from-literal=ABRQ_CORS_ALLOWED_ORIGINS=https://abrq.example.com

With external database and Redis (postgresql.enabled=false, redis.enabled=false), also add ABRQ_DATABASE_URL, ABRQ_DATASTORE_URL, and ABRQ_REDIS_URL to this Secret. Generation commands for the secret values are in choosing a deployment path. The full environment reference is in environment variables.

Install walkthrough#

# 1. Create the namespace and the runtime Secret (previous section).
kubectl create namespace abrq

# 2. Install the chart from the repository checkout.
helm install abrq-dip deploy/helm/abrq-dip --namespace abrq

# 3. Watch the rollout.
kubectl -n abrq get pods -w

On first install the bundled PostgreSQL StatefulSet initializes, an initdb script creates the second (datastore) database, each app pod's migrate init container waits for the database and applies migrations under an advisory lock, and then the API pods pass their readiness probe.

values.yaml reference#

Every key the chart accepts, with its default and effect.

Images and frontend#

API#

Worker#

Beat (singleton)#

Warning. Beat is a hard singleton: the template hardcodes replicas: 1 with a Recreate strategy — there is no beat.replicaCount value, no probes, no HPA, and no PDB for it. Never run more than one beat.

Backups (ADR 0040)#

Auto-backup is on by default in the application; without this PVC it still runs but writes to each pod's ephemeral filesystem. Production installs should enable it against RWX storage. See backup and restore.

Migrations#

Secrets and common environment#

Any additional key added under commonEnv is applied to every backend component. Auto-wired connection URLs take precedence over the same keys in existingSecret.

Ingress#

Why the /api split exists: the frontend nginx has an internal /api proxy, but its upstream host is literally backend — a hostname that only exists on the Docker Compose network. In Kubernetes that proxy target does not resolve, so the Ingress must route /api (and hence all API traffic) directly to the api Service, before the catch-all / rule sends everything else to the frontend.

Service account, security context, availability#

Beat deliberately has no PDB: it is a singleton, one eviction during a drain is acceptable, and the runner-side advisory lock keeps schedules from double-firing.

In-cluster PostgreSQL subchart#

In-cluster Redis subchart#

Warning. The subchart images are pinned to the frozen bitnamilegacy Docker Hub mirror, because Bitnami removed its free images in 2025 (docker.io/bitnami/* no longer pulls). Legacy images receive no security patches. For production, prefer external managed PostgreSQL and Redis: set postgresql.enabled=false and redis.enabled=false and put ABRQ_DATABASE_URL, ABRQ_DATASTORE_URL, and ABRQ_REDIS_URL in the runtime Secret.

Note. nameOverride and fullnameOverride are honoured by the chart's name helpers but are not listed in values.yaml. Do not rely on the chart's README.md, which is out of date; the templates and values.yaml are authoritative.

Post-install verification#

helm status abrq-dip -n abrq
kubectl -n abrq get pods

All pods should reach Running with ready containers (the migrate init containers show as Init:0/1 while migrations apply on first install). Then check application health end to end:

kubectl -n abrq port-forward svc/abrq-dip-frontend 8080:80

curl -fsS http://localhost:8080/health

The API's own health endpoint reports both dependencies:

kubectl -n abrq port-forward svc/abrq-dip-api 8000:8000
curl -fsS http://localhost:8000/health

Expected shape: {"status": "ok", ... "deps": {"framework_db": "ok", "redis": "ok"}}. A 503 with a dep marked down names the broken dependency.

Finally, open the UI (through your Ingress host or the frontend port-forward), log in as the initial admin user with the password from your runtime Secret (ABRQ_INITIAL_ADMIN_PASSWORD), and complete the forced password change.

Failure modes#

Install fails immediately: existingSecret missing#

If the Secret named by existingSecret does not exist or the value is empty, rendering fails with:

existingSecret is required — create a Secret with ABRQ_MASTER_KEY,
ABRQ_JWT_SECRET, etc. and set .Values.existingSecret to its name
(see deploy/ENVIRONMENT.md).

Create the Secret (see above) and retry. Note the chart validates the name at render time; a Secret that exists but is missing keys (for example no ABRQ_MASTER_KEY) surfaces later as backend pods failing startup with a configuration error in their logs.

Backend pods crash-loop: license#

In prod (the chart's default ABRQ_ENV), startup verifies the license file and exits on failure, so license problems present as api, worker, and beat pods in CrashLoopBackOff. Check the logs:

kubectl -n abrq logs deploy/abrq-dip-api

A healthy startup logs license_verified with the customer name and expiry. Failures log license_check_failed with the reason — file not found at ABRQ_LICENSE_FILE (default /var/abrq-dip/license.json), invalid signature, or expired.

Warning. The chart currently ships no values key for mounting the license file — no template mounts one into the pods. You must make license.json available at the ABRQ_LICENSE_FILE path on the api, worker, and beat pods yourself (for example by adding a Secret volume mount to the rendered manifests through your deployment tooling), or point ABRQ_LICENSE_FILE (via commonEnv) at a path you provide. This is a known packaging gap — raise it with your vendor contact. See installing a license.

Probe crash loops#

• API pods restart repeatedly: the liveness probe is GET /health, which requires the framework DB and Redis to answer. If either is down, the API is killed and restarted in a loop. Fix the data tier first; the probe is telling the truth.
• Worker pods restart repeatedly: the exec probe runs celery inspect ping — it fails when the worker cannot reach the Redis broker (bad ABRQ_REDIS_URL, Redis auth mismatch, Redis down), even if the process itself is alive.
• First install on a slow cluster: image pulls plus Postgres init plus migrations can exceed the API's 30s liveness initial delay on very slow nodes. The migrate init container absorbs the migration wait; if you still see restarts before first readiness, check whether the data tier is actually up rather than tuning probe timings first.

Air-gapped clusters#

For clusters without registry egress — saving, retagging, and pushing images into a private registry, plus the current pull-secret limitation — see air-gapped installation. Upgrades and rollback are covered in upgrade and rollback.