docs(k8s): ADR-0033 + the Talos deployment runbook (refs #25 )

ADR-0033 records why one values-driven chart rather than 30 subcharts, the four platform-forced deviations from compose, and the alternatives (kompose, bitnami subcharts, ingress-nginx, Helm hooks for ordering, a laptop-side registry). The runbook is the walkthrough as actually performed on a single-node Talos v1.14 VM under virt-manager, including the parts that bite: virt-manager ejecting the install ISO on first shutdown, Talos 1.14 moving the install disk into its own config document, the control-plane taint, and why the portals must be reached over localhost (crypto.subtle needs a secure context for PKCE).
feat(k8s): Helm chart for the whole stack on a single-node cluster (refs #25 )
2026-09-04 17:51:21 +02:00 · 2026-09-04 17:51:21 +02:00 · 2026-09-04 17:51:21 +02:00 · 2026-09-04 17:51:21 +02:00 · 2026-09-04 17:51:21 +02:00 · 2026-09-04 17:50:50 +02:00
5 changed files with 2 additions and 68 deletions
@@ -64,9 +64,6 @@ frontend:
 ## lint: verify formatting (no changes)
 lint:
 	dotnet format $(SLN) --verify-no-changes
-	# Only pages in mkdocs.yml's nav are published, and mkdocs keeps a build green
-	# when one is missing — so the nav is checked here rather than not at all.
-	python3 infra/check-docs-nav.py

 ## build: release build
 build:
@@ -3,8 +3,8 @@
 - **Status:** Accepted
 - **Date:** 2026-09-04
 - **Deciders:** Respellion engineering
- **Slice:** #25 (S-24) — raised directly as a deployment-target request and matched to
-  that issue afterwards; see the "Process note" at the end
+- **Slice:** _(none yet — raised directly as a deployment-target request; see
+  "Process note" at the end)_

 ## Context

@@ -14,8 +14,6 @@ should teach.
  In Dutch; the strategic framing lives in `Respellion/innovation-lab`.
 - **[Working in Gitea](gitea-workflow.md)** — issues, milestones, branches, PRs.
 - **[CI runbook](runbooks/ci.md)** — the pipeline and the `make ci` local gate.
- **[Kubernetes on Talos](runbooks/kubernetes-talos.md)** — the second deployment target:
-  one Helm chart, a single-node cluster, and the parts that bite (ADR-0033).

 ## Quickstart

@@ -1,30 +0,0 @@
-#!/usr/bin/env python3
-"""Fail when a page under docs/ is missing from mkdocs.yml's nav.
-
-docs/ is the source of truth (CLAUDE.md §12), but only the pages listed in the nav
-are published — and mkdocs' own `omitted_files: warn` keeps a build green while
-silently dropping them, which is how every ADR after 0010 and every runbook but
-ci.md fell off the site.
-
-ponytail: a substring test, not a YAML parse — a page's path either appears in
-mkdocs.yml or it doesn't, and that needs no dependency.
-"""
-
-import sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-nav = (ROOT / "mkdocs.yml").read_text()
-
-missing = sorted(
-    str(page.relative_to(ROOT / "docs"))
-    for page in (ROOT / "docs").rglob("*.md")
-    if str(page.relative_to(ROOT / "docs")) not in nav
-)
-
-if missing:
-    print(f"{len(missing)} page(s) under docs/ are not in mkdocs.yml's nav:")
-    print("\n".join(f"  {m}" for m in missing))
-    sys.exit(1)
-
-print("docs nav complete: every page under docs/ is published")
@@ -32,30 +32,6 @@ nav:
      - "ADR-0008: Read projection store": architecture/adr-0008-read-projection-store.md
      - "ADR-0009: External-task job worker": architecture/adr-0009-external-task-job-worker.md
      - "ADR-0010: BFF OIDC validation": architecture/adr-0010-bff-oidc.md
-      - "ADR-0011: Approval status flow": architecture/adr-0011-approval-status-flow.md
-      - "ADR-0012: Citizen reference correlation": architecture/adr-0012-citizen-reference-correlation.md
-      - "ADR-0013: Behandel-portal wiring": architecture/adr-0013-behandel-portal-wiring.md
-      - "ADR-0014: Withdrawal cancels the process": architecture/adr-0014-withdrawal-cancels-the-process.md
-      - "ADR-0015: Beoordeling escalation": architecture/adr-0015-beoordeling-escalation.md
-      - "ADR-0016: Diploma eligibility DMN": architecture/adr-0016-diploma-eligibility-dmn.md
-      - "ADR-0017: Document-wait timeout": architecture/adr-0017-document-wait-timeout-cancellation.md
-      - "ADR-0018: Diploma upload via the ACL": architecture/adr-0018-diploma-upload-via-acl-documenten.md
-      - "ADR-0019: Zaak cancellation on timeout": architecture/adr-0019-zaak-cancellation-on-timeout.md
-      - "ADR-0020: Local stack self-seeds": architecture/adr-0020-local-stack-self-seeds.md
-      - "ADR-0021: Zaaktype by identificatie": architecture/adr-0021-acl-resolves-zaaktype-by-identificatie.md
-      - "ADR-0022: Quartz scheduler": architecture/adr-0022-quartz-scheduler.md
-      - "ADR-0023: Observability stack": architecture/adr-0023-observability-stack.md
-      - "ADR-0024: Prometheus AspNetCore exporter": architecture/adr-0024-prometheus-aspnetcore-exporter.md
-      - "ADR-0025: BFF reads catalogus via the ACL": architecture/adr-0025-bff-reads-catalogus-via-acl.md
-      - "ADR-0026: Mutable default-fill store": architecture/adr-0026-mutable-default-fill-store.md
-      - "ADR-0027: RegisterRecord objecttype": architecture/adr-0027-registerrecord-objecttype-schema.md
-      - "ADR-0028: Objecten holds the register": architecture/adr-0028-objecten-holds-the-register.md
-      - "ADR-0029: Objecten publishes to NRC": architecture/adr-0029-objecten-publishes-to-nrc.md
-      - "ADR-0030: Projection sourced from the register": architecture/adr-0030-projection-sourced-from-the-register.md
-      - "ADR-0031: MFA on the medewerker realm": architecture/adr-0031-mfa-on-the-medewerker-realm.md
-      - "ADR-0032: Werkbak live refresh": architecture/adr-0032-werkbak-live-refresh.md
-      - "ADR-0033: Kubernetes via one Helm chart": architecture/adr-0033-kubernetes-via-one-helm-chart.md
-      - "ADR-0034: Caddy serves the portals": architecture/adr-0034-caddy-serves-the-portals.md
  - FDS-architectuur:
      - Overzicht: architecture/fds/README.md
      - Componentview (L3): architecture/fds/c4-component-view.md
@@ -70,15 +46,8 @@ nav:
  - Working in Gitea: gitea-workflow.md
  - Frontend decisions: frontend-decisions.md
  - Demo script: demo-script.md
-  - Synthetic data: synthetic-data.md
  - Runbooks:
      - CI: runbooks/ci.md
-      - OpenZaak: runbooks/openzaak.md
-      - Open Notificaties (NRC): runbooks/opennotificaties.md
-      - Keycloak: runbooks/keycloak.md
-      - Flowable: runbooks/flowable.md
-      - Kubernetes on Talos: runbooks/kubernetes-talos.md
-      - Gitea Actions gotchas: runbooks/gitea-actions-gotchas.md

 markdown_extensions:
  - admonition
Author	SHA1	Message	Date
not	e6aaed7c8c	docs(k8s): ADR-0033 + the Talos deployment runbook (refs #25 ) CI / build (pull_request) Successful in 1m9s Details CI / lint (pull_request) Successful in 1m27s Details CI / unit (pull_request) Successful in 1m37s Details CI / frontend (pull_request) Successful in 3m16s Details CI / mutation (pull_request) Successful in 6m20s Details CI / verify-stack (pull_request) Successful in 9m58s Details ADR-0033 records why one values-driven chart rather than 30 subcharts, the four platform-forced deviations from compose, and the alternatives (kompose, bitnami subcharts, ingress-nginx, Helm hooks for ordering, a laptop-side registry). The runbook is the walkthrough as actually performed on a single-node Talos v1.14 VM under virt-manager, including the parts that bite: virt-manager ejecting the install ISO on first shutdown, Talos 1.14 moving the install disk into its own config document, the control-plane taint, and why the portals must be reached over localhost (crypto.subtle needs a secure context for PKCE).	2026-09-04 17:51:21 +02:00
not	7a5840149c	feat(k8s): Helm chart for the whole stack on a single-node cluster (refs #25 ) One chart whose values.yaml is a near-literal transcription of infra/docker-compose.yml, rendered by three generic templates (Deployment, Job, Service) over a `workloads` map — so the two stacks can be diffed by eye instead of by archaeology, and adding a service is a values edit. Platform-forced deviations, each commented where it appears: - `args`, never `command`: compose replaces the image CMD, Kubernetes replaces the ENTRYPOINT. The chart fails to render on `command`, because the symptom (postgres refusing to run as root, Keycloak exec-ing `start-dev`) is nothing like the cause. - The four Django services apply their own setup_configuration in the web pod rather than in a separate init Job: both scripts migrate, and without compose's depends_on they race the same database. - OpenZaak and Objecten are addressed by service FQDN, because Django rejects a single-label host in a URL — the reason compose passes container IPs around. - NodePorts, no ingress; databases are emptyDir until persistence.storageClass is set, so the stack comes up on a cluster with no CSI driver. The upstream config inputs stay in the repo and become ConfigMaps via infra/helm/seed-configmaps.sh — the Kubernetes sibling of infra/seed-config.sh — so the compose stack and the chart cannot fork. infra/helm/registry.yaml runs an in-cluster registry because Talos cannot side-load an image and a laptop-side one needs a root-level firewall change.	2026-09-04 17:51:21 +02:00
not	916d671d49	test(k8s): gate the Helm chart with a render + schema check (refs #25 ) `make k8s-lint` runs `helm lint` plus a full `helm template`, so a values typo or a malformed resource is caught without a cluster — the only automated check the chart can have while CI has no Kubernetes to deploy into. Red: there is no chart to lint yet.	2026-09-04 17:51:21 +02:00
not	2d40c84e2c	docs(portals): ADR-0034 — Caddy serves the portals (refs #166 ) Records the decision, the directive-order footgun that shapes the Caddyfiles, and the measured cost (the images grew 75.7 MB → 90.6 MB). Also updates the three frontend-decisions entries and the two other docs that named nginx.	2026-09-04 17:51:21 +02:00
not	4edcf00267	feat(portals): serve each portal with Caddy instead of nginx (refs #166 ) nginx resolves a variable `proxy_pass` upstream itself, using only the `resolver` directive and never the search domains in /etc/resolv.conf. That cost two workarounds in one script: rewriting the resolver address for rootless podman (Docker's 127.0.0.11 is wrong there), and injecting a full FQDN so the bare `bff` name could resolve on Kubernetes at all. Caddy dials its upstream per request through the system resolver, which reads nameserver and search domains, so `reverse_proxy bff:8080` resolves on every engine with no per-engine configuration — and it still starts before the BFF exists and picks up its restarts. Both workarounds are deleted with the script. Routing uses mutually-exclusive `handle` blocks, not a bare `try_files`: Caddy sorts rewrites before reverse_proxy, so a top-level SPA fallback would rewrite every API path to /index.html before the proxy saw it.	2026-09-04 17:51:21 +02:00
not	51d99855d1	test(portals): assert each portal proxies only its own endpoint group (refs #166 ) The four portal proxy configs are near-identical, so a copy-paste slip is cheap to introduce and expensive to find: proxying another portal's endpoint group hands a browser an endpoint its token is not for, and the failure surfaces as a 401 three services away. Asserts each portal proxies exactly its own groups to the BFF and keeps the SPA fallback for Angular's client-side routes. Red: the Caddyfiles it reads do not exist yet.	2026-09-04 17:50:50 +02:00