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
@@ -2,7 +2,7 @@
type: Service
title: Chapter service
description: One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
tags: [architecture, go, k3s]
tags: [architecture, go, kubernetes]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
+3 -2
View File
@@ -24,8 +24,9 @@ push to main ─► Gitea Actions (runner on the home server)
- **Commits:** Conventional Commits. `feat:` bumps minor, `fix:` bumps patch,
`docs:` and `chore:` do not release.
- **Image tags:** the git SHA, so every deploy is traceable.
- **Registry pull:** k3s needs an `imagePullSecret` for the Gitea registry,
or `/etc/rancher/k3s/registries.yaml` if the registry is plain HTTP.
- **Registry pull:** the cluster needs an `imagePullSecret` for the Gitea
registry, or `/etc/containerd/certs.d/<registry>/hosts.toml` if the registry
is plain HTTP.
- **Runner permissions:** a kubeconfig for a ServiceAccount that can only
manage resources in `cv`.
- **Jobs are immutable:** changing a completed chapter's Job spec needs a
+2 -2
View File
@@ -4,7 +4,7 @@
* [Chapter service](chapter-service.md) - One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
* [Gateway](gateway.md) - The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
* [Frontend](frontend.md) - Nuxt site generated to static files and served by the gateway, with three audience layers fed by one SSE stream.
* [Server and memory budget](server-budget.md) - The CV shares a 2 vCPU, 4 GB server with Gitea and a small webapp, so every workload gets a hard memory cap.
* [Server and memory budget](server-budget.md) - The CV shares a small home server with Gitea, so every workload gets a hard memory cap; the kubeadm control plane is the biggest new cost.
* [Delivery](delivery.md) - Gitea Actions on the home server scan, build, push to the Gitea registry, deploy with kubectl, and version with release-please.
* [Terraform provisioning](terraform.md) - Terraform rebuilds the server, swap, k3s, Caddy and DNS from nothing; nothing inside the cluster.
* [Terraform provisioning](terraform.md) - Terraform rebuilds the server, containerd, the kubeadm control plane, Caddy and DNS from nothing; nothing inside the cluster.
* [In-browser language model](language-model.md) - A tiny language model trained by Noel that runs entirely in the visitor's browser and shows its internals live.
+32 -19
View File
@@ -1,30 +1,36 @@
---
type: Reference
title: Server and memory budget
description: The CV shares a 2 vCPU, 4 GB server with Gitea and a small webapp, so every workload gets a hard memory cap.
tags: [architecture, k3s, resources]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
description: The CV shares a small home server with Gitea, so every workload gets a hard memory cap; a kubeadm control plane needs more room than k3s did.
tags: [architecture, kubernetes, resources]
status: revised
generated: { by: opencode-go/deepseek-v4.1-flash, at: 2026-10-24T00:00:00Z }
sources:
- id: free-m
resource: "`free -m` on server0, before k3s, with Gitea, runner and webapp running"
resource: "`free -m` on server0, before the cluster, with Gitea, runner and webapp running"
author: human:noel
last_modified: 2026-10-11T12:15:30Z
---
# Server
`server0`: 2 vCPU, 3805 MB RAM, no swap yet. Shared with Gitea, its Actions
`server0`: 2 vCPU, 3805 MB RAM, 2 GB swap. Shared with Gitea, its Actions
runner, and a small webapp with one user.
A control plane with etcd costs about twice what k3s' single binary cost. The
plan is a stronger machine (8 GB or more, or a second server that carries
Gitea) before release 0.3.0. The numbers below are the floor that must fit
until then; the `cv` quota can rise once the bigger machine exists.
# Budget
| What | Memory | Basis |
|---|---|---|
| OS, Gitea, runner (idle), webapp | 1143 MB | Measured[^free-m] |
| k3s, trimmed | ~500 MB | Estimate, measure after install |
| etcd, kube-apiserver, scheduler, controller-manager, kubelet | ~900 MB | Estimate, measure after install |
| Calico, Caddy, metrics-server | ~150 MB | Estimate |
| Namespace `cv`, hard quota | 384 MB | ResourceQuota |
| Left for CI builds and page cache | ~1.7 GB | |
| Left for CI builds and page cache | ~1.2 GB (4 GB) / ~5 GB (8 GB) | |
| Swap | 2 GB | Safety net for build spikes |
[^free-m]: `free -m` on server0
@@ -57,20 +63,25 @@ spec:
defaultRequest: { memory: 8Mi, cpu: 5m }
```
# k3s config
# Kubelet config
`/etc/rancher/k3s/config.yaml`:
kubeadm writes `/var/lib/kubelet/config.yaml` from the
`KubeletConfiguration` in its config file. The values that matter:
```yaml
disable: [traefik, servicelb] # Caddy (Terraform) replaces both
kubelet-arg:
- "system-reserved=memory=1300Mi" # measured 1143 MB plus margin
- "eviction-hard=memory.available<200Mi"
failSwapOn: false # node has swap; pods still never swap
systemReserved: { memory: 1300Mi } # measured 1143 MB plus margin
evictionHard: { memory.available: 200Mi }
```
Keep `metrics-server` and `local-storage`: the HPA demo needs the first,
the tracker's SQLite volume the second. Single-node k3s uses SQLite, not etcd; do not
pass `--cluster-init`.
Full Kubernetes installs no addons. Two are required and are applied by the
Terraform module after `kubeadm init`: `metrics-server` for the HPA demo in
1.9.0, and a `local-path` provisioner for the tracker's SQLite volume.
Caddy replaces the ingress controller. Calico provides NetworkPolicy.
Do not use `--pod-network-cidr` values that collide with the home LAN; Calico
defaults to `192.168.0.0/16`, which on a typical `192.168.x.x` home network is
a conflict. Pick `10.244.0.0/16`.
# Swap
@@ -80,8 +91,10 @@ sudo mkswap /swapfile && sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
```
k3s starts with swap enabled. Pods do not swap; host processes such as
Gitea and builds can.
kubeadm and the kubelet refuse to start on a swapped host unless
`failSwapOn: false` is set. With that flag the node runs, pods still get no
swap, and host processes such as Gitea and builds can use it. Enabling swap
for pods needs the `NodeSwap` feature gate and is not worth it here.
# CI builds
+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
+25 -10
View File
@@ -1,36 +1,42 @@
# Server provisioning
Terraform owns everything outside the cluster: packages, swap, k3s itself,
the reverse proxy, and DNS records. Rebuilding the server from nothing is two
commands.
Terraform owns everything outside the cluster: packages, swap, containerd,
the kubeadm control plane, the reverse proxy, and DNS records. Rebuilding the
server from nothing is two commands.
## Scope
| Layer | Managed by | Examples |
|---|---|---|
| Server, packages, swap, k3s install | Terraform (SSH provisioner, cloud-init or shell) | `fallocate`, `mkswap`, k3s service with trimmed config |
| Server, packages, swap, runtime, kubeadm install | Terraform (SSH provisioner, cloud-init or shell) | `fallocate`, `mkswap`, containerd, `kubeadm init`, Calico |
| Cluster addons | Terraform (`kubectl` provisioner on the kubeadm output) | metrics-server, local-path provisioner |
| DNS records | Terraform provider for the DNS zone | A/AAAA record for the apex domain |
| Reverse proxy | Terraform-managed Caddy, Caddyfile templated | reverse_proxy block to the gateway |
| Workloads inside k3s | kustomize, applied by CI or hand | Namespace `cv`, Deployments, Jobs, Services, quota |
| Workloads inside the cluster | kustomize, applied by CI or hand | Namespace `cv`, Deployments, Jobs, Services, quota |
Terraform does not manage anything inside the cluster. Kubernetes already
describes its own state; Terraform and kubectl would fight over it.
describes its own state; Terraform and kubectl would fight over it. The one
exception is bootstrap: the namespace, the quota and the addons are created
once, after `kubeadm init`, and never reconciled again.
## Files
```
terraform/
main.tf server: packages, swap, k3s, Caddy
main.tf server: packages, swap, containerd, kubeadm, addons, Caddy
dns.tf A record for the apex domain
variables.tf server IP, SSH key, domain
outputs.tf server IP, proxy URL
outputs.tf server IP, kubeconfig path, proxy URL
```
Plan output for one run:
```
+ swapfile 2 GB
+ k3s service (traefik, servicelb disabled)
+ containerd 2.x, kubeadm, kubelet, kubectl
+ control plane on 127.0.0.1:6443 (etcd, apiserver, scheduler, controller-manager)
+ Calico (NetworkPolicy)
+ metrics-server and local-path provisioner
+ Caddy reverse_proxy block -> http://127.0.0.1:8080 (gateway NodePort)
+ certificate for noelsabia.dev
```
@@ -40,6 +46,8 @@ Plan output for one run:
- The server became disposable: `terraform destroy && terraform apply` plus
`kubectl apply -k deploy/` returns the whole system. That is the fastest
possible disaster recovery and the clearest possible demo.
- kubeadm is the upstream installer. The same steps on a bigger machine or a
cloud VM behave identically, which is what the [cluster decision](/decisions/full-kubernetes.md) asks for.
- Proxmox and cloud names change; code does not. The same Terraform targets the
home server now and a VM later.
- Home IP changes: the DNS provider has an A record the server can update.
@@ -49,5 +57,12 @@ Plan output for one run:
- **Terraform is new tooling** for Noel and needs approval under the stack
rule. Worth it: infrastructure as code is a core work skill.
- State file: local, not in Git. Nothing secret in the config itself.
- **Control plane memory:** allow about 900 MB to 1.2 GB for etcd, apiserver,
scheduler, controller-manager and kubelet. On a 4 GB server this is tight;
the machine is enlarged or replaced before 0.3.0. See [server budget](/architecture/server-budget.md).
- **No bundled addons:** full Kubernetes ships no ingress, load balancer,
metrics-server or storage provisioner. Caddy, metrics-server and the
local-path provisioner are explicit steps.
- State file: local, not in Git. Nothing secret in the config itself; the
kubeconfig it produces stays on Noel's machine.
- Changing a completed chapter or a Job is a delete plus apply, documented.
+1 -1
View File
@@ -2,7 +2,7 @@
type: Reference
title: Chapter states
description: How each Kubernetes primitive and state maps to a meaning in Noel's life story.
tags: [chapters, k3s, narrative]
tags: [chapters, kubernetes, narrative]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
+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
+4 -4
View File
@@ -33,8 +33,8 @@ verbessern — nicht in einer Sandkastenumgebung, sondern im echten Betrieb.
Meine CV-Website serviert zunächst den professionellen Regelbetrieb — Name,
Kontakt, PDF, in 10 Sekunden verstanden. Darunter läuft jedes Lebenskapitel
als echter Service auf meinem k3s-Cluster ("schlankes Kubernetes"): Besucher
können ein Kapitel umwerfen und zusehen, wie es in gemessenen Sekunden
als echter Service auf meinem Kubernetes-Cluster (kubeadm, containerd, Calico):
Besucher können ein Kapitel umwerfen und zusehen, wie es in gemessenen Sekunden
wieder hochkommt. Failures sind bewusste Inhalte ("Lektion gelernt"), kein
Bug. Das Projekt zeigt damit exakt, was im Job zählt: Systeme bauen,
die ausfallen und wieder aufstehen.
@@ -47,7 +47,7 @@ Lieferschritte, die wir dafür täglich brauchen:
| Fähigkeit | Direkte Anwendung im Team |
|---|---|
| Infrastruktur als Code (Terraform) | Server-Umgebungen reproduzierbar und versionierbar aufbauen |
| Container & Kubernetes (Docker, k3s) | Webapps portabel, skaliert und mit Limits betreiben |
| Container & Kubernetes (Docker, kubeadm, kubectl) | Webapps portabel, skaliert und mit Limits betreiben |
| Automatisierte Pipelines (CI/CD, Snyk) | Testen, scannen und ausliefern ohne manuelle Schritte |
| Eigener Reverse-Proxy (Caddy) | Verstehen, was zwischen Browser und Container passiert |
| Beobachterbarkeit (SSE, Logs) | Live-Systeme sichtbar machen, Probleme früh erkennen |
@@ -65,7 +65,7 @@ sind Fokustag-Estimates, keine Deadlines; insgesamt rund 20–25 Fokustage.
|---|---|---|
| 1 | Restartbarer Chapter-Service | Software bauen, die den Neustart als Feature nutzt |
| 2 | Server als Terraform-Code | Kompletten Server zerstörbar & neu aufbaubar machen |
| 3 | Kapitel auf k3s | Workloads mit Limits, Labels und Services betreiben |
| 3 | Kapitel auf Kubernetes | Workloads mit Limits, Labels und Services betreiben, den Cluster in FreeLens beobachten |
| 4 | Eigener Caddy-Proxy, DNS, TLS | Den gesamten Request-Pfad selbst besitzen |
| 5 | CI/CD-Pipeline | Ein `git push` reicht bis zum laufenden Cluster |
| 6 | Live-Status (SSE) | Echte Systemzustände sicher an Besucher streamen |
+7
View File
@@ -1,5 +1,12 @@
# Update Log
## 2026-10-24
* **Direction change**: k3s is out. Upstream Kubernetes via **kubeadm** (containerd, etcd, Calico) replaces it. See [decision](/decisions/full-kubernetes.md). The control plane costs about twice the memory, so server0 is upgraded to 8 GB or replaced before 0.3.0 — tracked in [open questions](/decisions/open-questions.md).
* **Decision**: [FreeLens](/decisions/freelens-admin-ui.md) is Noel's admin UI, connected to `127.0.0.1:6443` through an SSH tunnel. The rule becomes "no visitor gets API access" instead of "nobody".
* **Update**: [Server budget](/architecture/server-budget.md), [Terraform](/architecture/terraform.md), [system](/architecture/system.md) and [delivery](/architecture/delivery.md) now describe kubeadm, Calico, metrics-server, the local-path provisioner, kubelet `failSwapOn` and containerd `hosts.toml` instead of k3s.
* **Update**: [Roadmap](/roadmap.md) renames 0.3.0 to "Chapters on Kubernetes" and folds the control plane, addons and FreeLens into the 0.2.0 done-when.
* **Update**: Der [Lernplan](/lern-und-entwicklungsplan.md) nennt Kubernetes statt k3s und FreeLens als Beobachtungswerkzeug.
## 2026-10-15
* **Creation**: Added the [Lern- und Entwicklungsplan](/lern-und-entwicklungsplan.md) (German, for the boss at PreZero) and the [Modul-Zusammenfassung template](/modul-zusammenfassung.md) — one German one-pager per finished module.
* **Decision**: Recorded the [learning contract](/decisions/learning-contract.md): 2 h company time per week plus evenings, 6-month learning phase, one-pager per module, Gitea repo goes public.
+11 -7
View File
@@ -1,8 +1,8 @@
---
type: Overview
title: Interactive CV on k3s
title: Interactive CV on Kubernetes
description: A CV whose life chapters run as real Kubernetes workloads that visitors can knock down and watch recover.
tags: [overview, cv, k3s]
tags: [overview, cv, kubernetes]
status: stable
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
---
@@ -10,8 +10,9 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
# In one sentence
Noel's CV on the apex domain, where every life chapter is a workload on a
home k3s cluster: visitors push a chapter over and watch it stand up again.
The theme is **falling down and standing up again**.
home Kubernetes cluster (kubeadm, containerd, Calico): visitors push a chapter
over and watch it stand up again. The theme is **falling down and standing up
again**.
# Two audiences, one page
@@ -58,9 +59,12 @@ page shows the real recovery time next to the story of how Noel recovered.
- **Learning project, ship small.** Each release is a few days of work.
- **No tooling beyond the stack without Noel's approval.** The stack is Nuxt,
Go, k3s, Terraform, Docker, Snyk, Gitea Actions, release-please, Caddy and k6.
- **Small server.** 2 vCPU, 4 GB, shared with Gitea. The whole CV is capped at 384Mi. See [server budget](/architecture/server-budget.md).
- **Nobody gets Kubernetes API access.** Visitors and agents only talk to the gateway.
Go, Kubernetes via kubeadm, Terraform, Docker, Snyk, Gitea Actions,
release-please, Caddy, k6 and FreeLens.
- **Small server, being enlarged.** 2 vCPU, 4 GB today, shared with Gitea; a
machine with more RAM is planned before 0.3.0 because the full control plane
costs about twice what k3s did. The whole CV is capped at 384Mi. See [server budget](/architecture/server-budget.md).
- **No visitor gets Kubernetes API access.** Visitors and agents only talk to the gateway; only Noel holds a kubeconfig, used from FreeLens over an SSH tunnel.
- **Failures are lessons, never bugs.**
# Risks
+9 -9
View File
@@ -19,7 +19,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z }
|---|---|---|
| 0.1.0 | Chapter service | 1-2 |
| 0.2.0 | Terraform server | 2-3 |
| 0.3.0 | Chapters on k3s | 2 |
| 0.3.0 | Chapters on Kubernetes | 2 |
| 0.4.0 | Reverse proxy and DNS | 1-2 |
| 0.5.0 | Pipeline | 2 |
| 0.6.0 | Live states | 2-3 |
@@ -44,8 +44,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z }
Each release is cut by release-please from `feat:` commits. A release is done
when its "done when" check passes on the real cluster, not locally.
Everything runs on a 2 vCPU, 4 GB server shared with Gitea. Every release
stays inside the [memory budget](/architecture/server-budget.md).
Everything runs on a small home server shared with Gitea; a bigger machine (8 GB or a second server) arrives before 0.3.0 because the kubeadm control plane needs more room than k3s did. Every release stays inside the [memory budget](/architecture/server-budget.md).
---
@@ -62,13 +61,14 @@ stays inside the [memory budget](/architecture/server-budget.md).
## 0.2.0 Terraform server
- Terraform module that rebuilds server0 from nothing: packages, 2 GB swap file, k3s installed with traefik and servicelb disabled, kubelet reservations, and the `imagePullSecret` for the Gitea registry. See [terraform provisioning](/architecture/terraform.md).
- Terraform also creates namespace `cv` with the ResourceQuota (384Mi) and LimitRange, and the DNS A record for the apex domain.
- Terraform module that rebuilds server0 from nothing: packages, 2 GB swap file, containerd, `kubeadm init` with a single control plane, Calico, kubelet reservations, and the `imagePullSecret` for the Gitea registry. See [terraform provisioning](/architecture/terraform.md).
- Terraform also installs `metrics-server` and the local-path provisioner, creates namespace `cv` with the ResourceQuota (384Mi) and LimitRange, and creates the DNS A record for the apex domain.
- FreeLens on Noel's laptop points at `127.0.0.1:6443` through an SSH tunnel. See [FreeLens](/decisions/freelens-admin-ui.md).
- State file stays local; `plan` output is reviewed before every apply.
- **Done when:** `terraform destroy` then `terraform apply` on a blank server0 leaves k3s running, swap active, namespace `cv` with its quota on a fresh server. No hand steps.
- **Learn:** Terraform (providers, provisioners, plan/apply, state), cloud-init/SSH provisioning, why infra as code beats hand setup.
- **Done when:** `terraform destroy` then `terraform apply` on a blank server0 leaves a Ready control plane with Calico, metrics-server and namespace `cv` with its quota, FreeLens shows the node and the namespace over the tunnel, and swap is active. No hand steps. Requires the bigger machine from [open questions](/decisions/open-questions.md).
- **Learn:** Terraform (providers, provisioners, plan/apply, state), cloud-init/SSH provisioning, kubeadm and containerd, why infra as code beats hand setup.
## 0.3.0 Chapters on k3s
## 0.3.0 Chapters on Kubernetes
- Four placeholder chapters applied with `kubectl apply -k deploy/`: one Job (`complete`), one each of `healthy`, `not-ready`, `crash`.
- Services with `publishNotReadyAddresses: true`, resource limits, pod label `cv.noelsabia.dev/chapter`.
@@ -187,7 +187,7 @@ stays inside the [memory budget](/architecture/server-budget.md).
## 1.9.0 HPA demo
- HPA on one chapter using metrics-server (ships with k3s), max 3 replicas, live replica count and latency graph during a k6 run.
- HPA on one chapter using metrics-server (installed by the 0.2.0 module), max 3 replicas, live replica count and latency graph during a k6 run.
- **Done when:** replicas go up during a run and back down after.
## 1.10.0 LM: bigger base model