From e022c30527d4270c9bf7ca328c90703af278799a Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sat, 24 Oct 2026 19:02:17 +0200 Subject: [PATCH] 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 --- architecture/chapter-service.md | 2 +- architecture/delivery.md | 5 ++- architecture/index.md | 4 +- architecture/server-budget.md | 51 ++++++++++++++++--------- architecture/system.md | 12 ++++-- architecture/terraform.md | 35 ++++++++++++----- chapters/state-mapping.md | 2 +- decisions/ci-on-gitea.md | 2 +- decisions/freelens-admin-ui.md | 46 ++++++++++++++++++++++ decisions/full-kubernetes.md | 55 +++++++++++++++++++++++++++ decisions/index.md | 4 +- decisions/open-questions.md | 1 + decisions/provision-with-terraform.md | 8 ++-- lern-und-entwicklungsplan.md | 8 ++-- log.md | 7 ++++ overview.md | 18 +++++---- roadmap.md | 18 ++++----- 17 files changed, 214 insertions(+), 64 deletions(-) create mode 100644 decisions/freelens-admin-ui.md create mode 100644 decisions/full-kubernetes.md diff --git a/architecture/chapter-service.md b/architecture/chapter-service.md index 5cc9c81..bf7fa66 100644 --- a/architecture/chapter-service.md +++ b/architecture/chapter-service.md @@ -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 } --- diff --git a/architecture/delivery.md b/architecture/delivery.md index 032d3e6..b86345b 100644 --- a/architecture/delivery.md +++ b/architecture/delivery.md @@ -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//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 diff --git a/architecture/index.md b/architecture/index.md index 795e02f..e3f717d 100644 --- a/architecture/index.md +++ b/architecture/index.md @@ -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. diff --git a/architecture/server-budget.md b/architecture/server-budget.md index d7138cc..270570f 100644 --- a/architecture/server-budget.md +++ b/architecture/server-budget.md @@ -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 diff --git a/architecture/system.md b/architecture/system.md index ce6e92e..6cd35f1 100644 --- a/architecture/system.md +++ b/architecture/system.md @@ -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 diff --git a/architecture/terraform.md b/architecture/terraform.md index acc0cf2..f920098 100644 --- a/architecture/terraform.md +++ b/architecture/terraform.md @@ -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. diff --git a/chapters/state-mapping.md b/chapters/state-mapping.md index 5b34425..f9eea10 100644 --- a/chapters/state-mapping.md +++ b/chapters/state-mapping.md @@ -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 } --- diff --git a/decisions/ci-on-gitea.md b/decisions/ci-on-gitea.md index 5cf0a5f..fbea143 100644 --- a/decisions/ci-on-gitea.md +++ b/decisions/ci-on-gitea.md @@ -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. diff --git a/decisions/freelens-admin-ui.md b/decisions/freelens-admin-ui.md new file mode 100644 index 0000000..230df30 --- /dev/null +++ b/decisions/freelens-admin-ui.md @@ -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. diff --git a/decisions/full-kubernetes.md b/decisions/full-kubernetes.md new file mode 100644 index 0000000..edcea6a --- /dev/null +++ b/decisions/full-kubernetes.md @@ -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). diff --git a/decisions/index.md b/decisions/index.md index 8ead492..c741ef0 100644 --- a/decisions/index.md +++ b/decisions/index.md @@ -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. diff --git a/decisions/open-questions.md b/decisions/open-questions.md index 8d125a4..7c6c916 100644 --- a/decisions/open-questions.md +++ b/decisions/open-questions.md @@ -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 | diff --git a/decisions/provision-with-terraform.md b/decisions/provision-with-terraform.md index ebcb78c..079779e 100644 --- a/decisions/provision-with-terraform.md +++ b/decisions/provision-with-terraform.md @@ -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 diff --git a/lern-und-entwicklungsplan.md b/lern-und-entwicklungsplan.md index 0371f13..c30616e 100644 --- a/lern-und-entwicklungsplan.md +++ b/lern-und-entwicklungsplan.md @@ -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 | diff --git a/log.md b/log.md index fc522d6..7861b8f 100644 --- a/log.md +++ b/log.md @@ -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. diff --git a/overview.md b/overview.md index 10e0588..faba780 100644 --- a/overview.md +++ b/overview.md @@ -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 diff --git a/roadmap.md b/roadmap.md index 9a395e7..0b58fbc 100644 --- a/roadmap.md +++ b/roadmap.md @@ -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