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:
1 parent
6ab76c2a36
commit
e022c30527
17 files changed
+214
-64
No files matched your search
@@ -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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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
@@ -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.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in new issue
Block a user