feat(okf): run on full Kubernetes with FreeLens for admin

k3s is out. The cluster is upstream Kubernetes installed with kubeadm:
containerd, single control-plane etcd, Calico for NetworkPolicy.

- add the cluster decision and the FreeLens decision
- move Terraform from the k3s service to kubeadm, Calico, metrics-server
  and the local-path provisioner
- budget ~900 MB for the control plane and plan a bigger machine before 0.3.0
- note kubelet failSwapOn and containerd hosts.toml
- rename 0.3.0 and commit the 0.2.0 done-when to the new stack
- update the German learning plan
This commit is contained in:
Noel Sabia committed 2026-10-24 19:02:17 +02:00
1 parent 6ab76c2a36
commit e022c30527
17 files changed
+214 -64

No files matched your search

+8 -4
View File
@@ -2,7 +2,7 @@
type: Architecture
title: System architecture
description: All runtime components of the v1 site and how a request and a knockdown flow through them.
tags: [architecture, k3s, go, nuxt]
tags: [architecture, kubernetes, go, nuxt]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
@@ -16,10 +16,13 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
| [Frontend](/architecture/frontend.md) | Static files inside the gateway image | Nuxt, built with `nuxt generate`. |
| [Chapter service](/architecture/chapter-service.md) | One Deployment or Job per chapter | Behaves healthy, not-ready, crashing, or completed, set by env. |
| [Delivery](/architecture/delivery.md) | Gitea Actions on the home server | Test, scan, build, push, deploy, version. |
| FreeLens | Noel's laptop | Admin UI for the cluster over an SSH tunnel. Not part of the public site. |
Everything runs in one namespace: `cv`, capped at 384Mi memory in total, on a
2 vCPU, 4 GB server shared with Gitea. See [server budget](/architecture/server-budget.md).
2 vCPU, 4 GB server shared with Gitea. A machine with more RAM is planned
before 0.3.0, because the kubeadm control plane costs more than k3s did. See
[server budget](/architecture/server-budget.md).
# Images
@@ -46,14 +49,15 @@ cmd/chapter → image `chapter`
6. Recovery time = Ready condition `lastTransitionTime` minus the fall time.
7. The page shows the story card with the measured seconds.
No step needs write access to the Kubernetes API.
No visitor-facing step needs write access to the Kubernetes API.
# Security boundaries
- Only the gateway is reachable from outside.
- Gateway ServiceAccount: `get/list/watch` on pods, events and jobs in `cv`. Nothing else.
- `/fall` is unauthenticated inside the cluster. A NetworkPolicy (supported natively by k3s) restricts it to the gateway.
- `/fall` is unauthenticated inside the cluster. A NetworkPolicy (Calico) restricts it to the gateway.
- No visitor-supplied input reaches the cluster except a chapter name checked against an allowlist.
- Only Noel holds a kubeconfig. The API server listens on localhost; FreeLens reaches it through an SSH tunnel. See [FreeLens](/decisions/freelens-admin-ui.md).
# Accepted risk