Reference — the hort-server Helm chart

Operator reference for the chart at deploy/helm/hort-server/. It covers the chart structure: what Kubernetes objects it renders and under which conditions, the install-time validation rules, Helm hook ordering, what each workload actually runs, the probes, and the chart-vs-binary caveats that bite operators.

This page is deliberately not a per-key values.yaml walkthrough — that already exists:

Authority. Ground truth is the chart itself — deploy/helm/hort-server/{Chart.yaml,values.yaml,values.schema.json,templates/}. Where this page and the chart disagree, the chart wins and this page is the bug; fix it in the same change.

1. Chart metadata

The chart deploys two workloads from two images: hort-server (the HTTP edge, image.*) and hort-worker (the scanner-bundled job dispatcher, worker.image.*, enabled by default — worker.enabled: true; quarantine is the default ingest posture and the release predicate needs a ScanCompleted from a running worker, so vanilla deploys need the worker present. Set worker.enabled: false only alongside a ScanPolicy declaring scan_backends: [] — see values.yaml's own comment on the key). It ships no Ingress / Gateway / HTTPRoute — the operator owns the edge.

2. Topology & required values

The schema permits exactly two consistent topologies and blocks the inconsistent middle:

Minimum required values for any install (schema-enforced at helm install — see §5):

3. Rendered-resource matrix

Default install (helm install with only the required values set) renders everything in the Always rows plus: the worker Deployment

• ConfigMap + ServiceAccount (worker.enabled: true by default), the

NetworkPolicy pair (networkPolicy.enabled: true by default), and the two default-enabled executionPath: dsn-direct CronJobs — scrub and quarantine-release-sweep. All executionPath: admin-task CronJobs (and the svc-token bootstrap Job + RBAC) stay off until scheduledTasks.adminTasksEnabled=true — except replaySeenPrune and scannerRegistryPrune, which default enabled: true within that umbrella (so they still only render once the umbrella itself is flipped on).

The <fullname>-svc-token Secret is created at run time by the bootstrap Job's kubectl apply — it is not a chart template and does not appear in helm template output.

4. Helm hooks, install ordering & workload wiring

Only three templates carry helm.sh/hook annotations:

Ordering guarantee: migrate Job (pre-install, w=-5) → all non-hook resources incl. server Deployment + bootstrap RBAC (w=0) → svc-token bootstrap Job (post-install, w=5). Net effect: the schema is migrated before the server serves; the service-account row and its RBAC exist before the token bootstrap runs; CronJobs are created in the main phase but only fire on schedule, by which time the bootstrap Job has populated the -svc-token Secret they mount. The migrate Job runs under the namespace default ServiceAccount on purpose — as a pre-install hook it precedes the SA template.

What each workload runs (hort-server / hort-worker / hort-cli):

All five hort-cli CronJobs use concurrencyPolicy: Forbid. The Idempotency-Key window is minute-granular, which makes a 5-minute period the practical floor for any schedule: you set on the admin-task CronJobs.

4a. Probes

Server Deployment — all three are httpGet on port name http:

terminationGracePeriodSeconds = shutdown.gracefulSeconds + 30.

Worker Deployment — one exec liveness probe, no readiness/startup (it serves no traffic):

hort-worker healthcheck verifies env parse + a single Postgres SELECT 1 (internal budget 2.5 s, pool-acquire 2 s — both kept below the 3 s probe timeout). Worker terminationGracePeriodSeconds is a fixed 45.

5. Install-time validation

values.schema.json (JSON Schema draft-07) rejects a bad helm install/upgrade before anything reaches the cluster.

Strict schema — unknown keys fail

additionalProperties: false is set on the top-level object and every nested object block the chart owns the shape of. An unknown, mistyped, or retired key fails helm install/helm template with Additional property <key> is not allowed, instead of being silently accepted and ignored (the pre-078 worst-case: an operator sets a value that has no effect and never finds out). This catches typos (worker.scanner.osvv), top-level slips (replicaCountt), and every pre-078 retired key — apiBindAddr (now api.bindAddr), worker.scanner.osvScanner (now worker.scanner.osv), http.ociUploadTimeoutSeconds (now oci.uploadTimeoutSeconds), the old cronJobs.* tree (now scheduledTasks.*). Free-form passthrough blocks the operator owns the shape of — resources, probes.*, affinity, nodeSelector, the *SecurityContext blocks, gitopsConfig, and the verbatim Kubernetes arrays (extraEnv, extraVolumes, networkPolicy.ingress, …) — stay permissive: the strict lint guards the chart's own config keys, not arbitrary pod-spec content. The regression is locked by the test-values-strict-schema-typo.yaml fixture in scripts/test-helm-templates.sh (the render MUST fail on the typo keys).

Always-required keys

Root: publicBaseUrl, auth, postgres, storage, ephemeralStore, replicaCount. Plus auth.provider; postgres.app.existingSecret; postgres.admin.existingSecret; storage.backend; ephemeralStore.backend.

Conditional invariant rules

Each rule surfaces the misconfiguration at install time instead of as a server boot-crash loop.

Template-level guards (fail at helm template/render, not in the schema)

The pre-existing two-place rotation switch was collapsed into the single scheduledTasks.serviceAccountRotation.enabled toggle and the cross-field half-set checks were moved from a bespoke fail-based template helper into the schema rules 9a/9b above — so a half-set rotation config is now rejected by values.schema.json (the uniform validation style) rather than a template fail.

6. Binary-default sentinels

Several numeric/string chart values use a sentinel meaning "let the binary pick". Leave them at the sentinel unless you have a measured reason; the binary defaults are the supported ones.

See the server & worker configuration reference for what each rendered env var does and its boot-time interlocks.

7. Scheduled tasks & worker — operator notes

All periodic tasks live under scheduledTasks.*; each carries an executionPath attribute. worker.enabled defaults on (quarantine-by-default needs a running worker to ever release an artifact — see §1); scheduledTasks.adminTasksEnabled defaults off — enable it only when you need rescanning, advisory-watch, staging-sweep, retention, or service-account rotation on a schedule (scanning itself already runs via the default-on worker, independent of this umbrella).

• executionPath: dsn-direct tasks (scrub, quarantineReleaseSweep, prefetchTick, prefetchRowRetentionSweep, wheelMetadataBackfill) run a hort-server subcommand with the runtime DSN only — no svc-token, no bootstrap Job — and are gated solely by their own enabled, never by adminTasksEnabled. scrub + quarantineReleaseSweep default on.
• executionPath: admin-task tasks (everything else) invoke `hort-cli admin task invoke <kind> with the <release>-svc-token PAT and are gated by **both** scheduledTasks.adminTasksEnabled (the master toggle, which also renders the svc-token bootstrap Job + RBAC) **and** the task's own enabled. All default **off** except replaySeenPrune and scannerRegistryPrune (both default on once the master toggle is flipped). verifyEventChain is the one hybrid: it shares the adminTasksEnabled gate but runs hort-server verify-event-chain` directly (no PAT).
• Worker prerequisites: worker.enabled=true requires the scanner-bundled worker.image. Do not set worker.workerIdOverride together with worker.replicas > 1 (the per-pod random suffix is what keeps worker identities distinct).
• Admin-task prerequisites: scheduledTasks.adminTasksEnabled=true also needs postgres.admin.existingSecret (the bootstrap Job mints the SA token under the admin DSN), an in-cluster network path from CronJob pods to the hort-server Service, and an operator-declared gitops cronjob-tasks ServiceAccount plus a global admin_task_invoke PermissionGrant — the chart never provisions either, and issue-svc-token --require-authority fails the bootstrap Job loudly if the grant is missing. See enable-admin-task-cronjobs.md.
• Rotation single toggle: scheduledTasks.serviceAccountRotation.enabled is the single source-of-truth switch — it drives both the CronJob and the worker-side wiring (env + per-namespace RBAC). There is no separate worker.rotation.enabled. When it is on, the schema requires scheduledTasks.adminTasksEnabled=true, worker.enabled=true, and a non-empty worker.rotation.publicRegistryHost (rules 9a/9b); a half-set config fails at helm install. worker.rotation.{targetNamespaces, publicRegistryHost} are the worker-side parameters of that toggle.

8. Chart-vs-binary caveats

The chart schema is intentionally a superset in a few places; these are the gaps an operator can fall into:

• **The retired auth.provider: basic is rejected at the schema, not just the binary. The basic provider was removed end-to-end (see docs/auth-catalog.md Entry 8). The schema enum is now {oidc,disabled}, so provider: basic fails helm install on the enum check; and because the strict schema sets additionalProperties: false on the auth block, the retired auth.basic.* sub-block is also** rejected (Additional property basic is not allowed) — there is no longer a schema-superset gap for basic. Use oidc, or disabled with nativeTokens.enabled: true (see server & worker configuration §interlocks).
• **storage.s3.region is rendered as AWS_REGION but is not a schema-required S3 key.** Only endpoint, bucket, existingSecret are schema-required for the S3 backend; omitting region passes helm install and then fails at server boot. Set it whenever storage.backend=s3.
• scheduledTasks.scrub.enabled defaults to true. A default install runs a daily CAS-scrub CronJob (0 3 * * *). This is intended defence-in-depth; disable it explicitly (scheduledTasks.scrub.enabled=false) only if you have an external integrity backstop.
• The -svc-token Secret is runtime-created. It will not exist until the post-install bootstrap Job has run; CronJobs that mount it are created earlier but only fire on schedule, so the ordering holds on a clean install. On a chart upgrade that first enables scheduledTasks.adminTasksEnabled, the bootstrap Job (post-upgrade hook) populates it.

See also

• Per-key values.yaml reference
• Server & worker configuration reference
• Install playbook
• Edge / TLS overlays
• Sovereign install against registry.hort.rs
• Provision the two Postgres roles
• Security hardening checklist
• Wire secrets · Declare gitops config