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

+1 -1
View File
@@ -15,7 +15,7 @@ container registry, and the Gitea variant of the release-please action.
# Why
- GitHub Actions cannot reach the k3s API behind the tunnel. The local runner can.
- GitHub Actions cannot reach the Kubernetes API behind the tunnel. The local runner can.
- No new tooling: Gitea, its runner and its registry already exist.
- No GitOps agent (Flux, Argo) needed.
+46
View File
@@ -0,0 +1,46 @@
---
type: Decision
title: FreeLens as Noel's admin UI
description: FreeLens runs on Noel's laptop and reaches the API through an SSH tunnel; visitors and agents never get cluster access.
tags: [decision, kubernetes, operations, freelens]
status: stable
generated: { by: opencode-go/deepseek-v4.1-flash, at: 2026-10-24T00:00:00Z }
verified: { by: human:noel, at: 2026-10-24T00:00:00Z }
---
# Decision
Noel inspects and debugs the cluster in **FreeLens** on his own laptop. The
kubeconfig points at `https://127.0.0.1:6443`, and an SSH tunnel forwards that
port to the control plane, which listens only on localhost.
Visitors and browser agents never receive a kubeconfig. The public site keeps
using the gateway API.
# Why
- FreeLens gives pods, events, logs, probes and YAML without the project
building its own dashboard.
- The API server is not exposed to the internet: no port-forward on 6443, no
public endpoint, no certificate dance beyond SSH.
- The kubeconfig holds a client certificate. Leaving it on the laptop and
tunnelling the port keeps the cluster off the public attack surface.
- It closes the gap between "read-only gateway view" and "I need to see why a
pod is CrashLooping".
# Consequences
- Admin work (delete a stuck pod, read kubelet logs, change a quota) happens in
FreeLens or `kubectl`, never through the CV page.
- The SSH tunnel is a manual step: `ssh -L 6443:127.0.0.1:6443 server0`, then
open FreeLens. That is acceptable for a single admin.
- The bundle's rule becomes "no visitor gets Kubernetes API access", not
"nobody does". Noel is the only holder of a kubeconfig.
- FreeLens is a new tool and needs approval under the stack rule; it is
approved here because it replaces a self-built dashboard at zero server cost.
# Details
Runtime boundaries: [system](/architecture/system.md). The developer view on the
site (release 1.3.0) stays read-only through the gateway and is not a FreeLens
replacement.
+55
View File
@@ -0,0 +1,55 @@
---
type: Decision
title: Full Kubernetes instead of k3s
description: kubeadm installs upstream Kubernetes with containerd, Calico and etcd; k3s is out, at the cost of a bigger control plane.
tags: [decision, kubernetes, infra]
status: stable
generated: { by: opencode-go/deepseek-v4.1-flash, at: 2026-10-24T00:00:00Z }
verified: { by: human:noel, at: 2026-10-24T00:00:00Z }
---
# Decision
The cluster is upstream Kubernetes installed with `kubeadm`: containerd as the
runtime, etcd on the single control-plane node, Calico as the CNI. k3s is not
used. Nothing hides the control plane.
# Why
- kubeadm is the installer a hiring team recognises. The components it writes
(`kube-apiserver`, `etcd`, `kube-scheduler`, `kube-controller-manager`,
`kubelet`) are the ones the job talks about.
- k3s hides those components behind one binary and a SQLite default. The
project exists to learn the real thing, not a slimmed-down version.
- FreeLens, Terraform and kubectl treat both the same, so nothing else in the
bundle changes.
- A full control plane needs roughly 900 MB to 1.2 GB. server0 at 4 GB is
tight, so it is upgraded or replaced before release 0.3.0 — see
[open questions](/decisions/open-questions.md).
# Consequences
- The cluster ships no ingress controller, no load balancer, no metrics-server
and no storage provisioner. Caddy stays the entry; `metrics-server` (HPA) and
`local-path-provisioner` (the tracker's SQLite volume) are installed by the
Terraform module.
- NetworkPolicy comes from Calico, not from k3s' bundled controller.
- The kubelet refuses to start on a swapped host by default. `failSwapOn: false`
is set explicitly; pods still get no swap, host processes do.
- Registry credentials move from `/etc/rancher/k3s/registries.yaml` to
containerd's `hosts.toml`.
# Rejected
| Option | Why not |
|---|---|
| Keep k3s | Fast, but it hides exactly the control plane this project is meant to teach |
| microk8s | Upstream and light, but snap packaging and addons hide the install steps too |
| k0s | Fits 4 GB, but the same "one binary, no etcd" tradeoff as k3s |
| Managed cluster (k3s cloud, EKS, Hetzner) | Costs money every month and removes provisioning from the learning |
# Details
Provisioning: [Terraform](/architecture/terraform.md). Memory:
[server budget](/architecture/server-budget.md). Admin access:
[FreeLens](/decisions/freelens-admin-ui.md).
+3 -1
View File
@@ -3,7 +3,9 @@
* [Learning contract with PreZero](learning-contract.md) - 2 hours of company time per week plus evenings during a 6-month learning phase; one German one-pager per finished module; the repo goes public.
* [v1 scope](v1-scope.md) - What the first public version keeps and what moves to later phases.
* [Own Caddy reverse proxy](own-proxy.md) - The apex domain points straight at the home server; a Caddy reverse proxy provisioned by Terraform is the only entry, with automatic HTTPS.
* [Provision the server with Terraform](provision-with-terraform.md) - Packages, swap, k3s, Caddy and DNS are Terraform code; workloads inside the cluster stay with kustomize.
* [Provision the server with Terraform](provision-with-terraform.md) - Packages, swap, kubeadm, Caddy and DNS are Terraform code; workloads inside the cluster stay with kustomize.
* [Full Kubernetes instead of k3s](full-kubernetes.md) - kubeadm installs upstream Kubernetes with containerd, etcd and Calico; a bigger control plane is the price.
* [FreeLens as Noel's admin UI](freelens-admin-ui.md) - FreeLens runs on the laptop and reaches the API through an SSH tunnel; visitors never get cluster access.
* [Static Nuxt served by the gateway](static-nuxt-in-gateway.md) - Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod.
* [Own analytics tracker on SQLite](own-tracker.md) - Analytics are counted by Noel's own code in the gateway and stored as daily totals in SQLite; no third-party tracker, no Postgres.
* [CI/CD on Gitea Actions](ci-on-gitea.md) - The existing Gitea instance and runner on the home server build, scan, deploy and version the project.
+1
View File
@@ -9,6 +9,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-15T00:00:00Z }
| Question | Needed by | Default if nobody decides |
|---|---|---|
| Bigger server for the kubeadm control plane: upgrade server0 to 8 GB or rent a second machine | 0.2.0 | Upgrade server0's RAM before the kubeadm install |
| Final chapter list and the state of each chapter | 0.3.0 (placeholders), 1.0.0 (final) | Four placeholder chapters: one completed, one active, one unfinished, one failed |
| Story card text per chapter | 0.9.0 | None, Noel writes it |
| Life map visual form: timeline, graph or map | 0.9.0 | Vertical timeline |
+5 -3
View File
@@ -1,7 +1,7 @@
---
type: Decision
title: Provision the server with Terraform
description: Packages, swap, k3s, Caddy and DNS are Terraform code; workloads inside the cluster stay with kustomize.
description: Packages, swap, kubeadm, Caddy and DNS are Terraform code; workloads inside the cluster stay with kustomize.
tags: [decision, terraform, infra]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z }
@@ -10,8 +10,10 @@ verified: { by: human:noel, at: 2026-10-14T00:00:00Z }
# Decision
Terraform owns everything outside k3s: server packages, swap, the k3s
install, Caddy (including automatic HTTPS) and the DNS record. Nothing inside the cluster.
Terraform owns everything outside Kubernetes: server packages, swap,
containerd, the kubeadm control plane, Caddy (including automatic HTTPS) and the
DNS record. It bootstraps the namespace and the cluster addons once; the
workloads themselves stay with kustomize.
# Why