Files
OKF_CV_Website/brief.md
T
2026-10-11 14:21:20 +02:00

7.1 KiB
Raw Blame History

Interactive CV on k3s: Planning Brief

Handoff document for further planning. Owner: Noel Sabia.

1. Goal

A creative, interactive CV on the apex of Noel's main domain. It must work for two audiences:

  • Non-technical HR: understandable without any coding knowledge.
  • Programmers: real infrastructure, inspectable, technically credible.

Core life lesson: falling down and standing up again. It is shown live on a k3s cluster running on Noel's home server.

2. Fixed constraints (already decided)

Area Decision
Frontend Nuxt
Backend Multiple Go microservices
Orchestration k3s on home server (Ryzen 5, 24 GB RAM)
Security Snyk
Delivery CI/CD pipeline, release-please for versioning
Exposure Cloudflare Tunnel
Design Drafted with Stitch prompts. Terminal/IT feel, usable by non-IT visitors.
Brand Navy #1A3D64 and white. Logo has a "broken pieces" look, which fits the fall/recover theme.
AI access MCP-ready, so agents can read states and trigger a fall. Only include it if it is doable in under 2 hours without AI. Keep it minimal.
Tooling rule Any tooling beyond this stack needs Noel's approval before it enters the spec. k6 is approved by Noel.

3. Core concept

  • Each life chapter runs as its own microservice or workload in k3s.
  • Some chapters stay unhealthy on purpose.
  • Visitors interactively knock chapters down and watch Kubernetes bring them back up.
  • k6 load testing is integrated on the side.

Kubernetes state to life meaning

K8s primitive / state Meaning Example use
Job → Completed Finished chapter School, 42 piscine
Deployment → Running + Ready Active, stable chapter PreZero, Example
Running, NotReady (readiness fails on purpose) Exists, unfinished Ongoing studies, thesis
CrashLoopBackOff (permanent) Attempt that failed and stayed failed Abandoned projects, dead ends
restartCount Setbacks survived "fell 3×, stood up 3×"
Replicas / HPA scale-up Load carried, growth under pressure Team lead, two businesses in parallel
Rolling update / new revision Pivot or reinvention Career switch, new role

Key structural choice: finished chapters run as Jobs (they complete), and current chapters run as Deployments (they must stay alive).

4. Audience layers (one data source, different rendering)

Layer Audience Content
0: First screen HR, 10-second skim Name, role, contact, static PDF CV download. Never gated behind interaction.
1: Life map Non-technical Timeline or graph of chapters. States in plain words ("recovering", "unfinished", "failed, lesson learned"). A "Push this chapter" button.
2: Terminal Developers kubectl-style view: events, probes, restart history, YAML per chapter, live k6 results

5. Architecture

Visitor ─► Cloudflare Tunnel ─► Nuxt
                                 │  SSE/WebSocket (state)
                                 ▼
                        Go gateway (only public API)
                         ├─ watch: read-only informer on namespace `cv`
                         ├─ actions: allowlisted, rate-limited
                         └─ MCP endpoint (same actions, same limits)
                                 │
            ┌────────────────────┼────────────────────┐
     chapter-svc (Go)     chapter-svc (Go)      k6 Job (on demand)
     /healthz /ready /fall
  • One Go chapter-service template. Its health behavior is set by env config: healthy, not-ready or crash.
  • Knockdown via /fall on the service itself. The process exits or fails its liveness probe, and the kubelet restarts it. This needs no delete permission on the cluster.
  • Gateway ServiceAccount: scoped to namespace cv, read-only get/list/watch on pods, events and jobs.

6. Non-negotiable rules

  • No visitor or agent gets Kubernetes API access. Everything goes through the gateway.
  • Per-chapter cooldown and a global rate limit, so one visitor cannot hold everything down.
  • Shared cluster state is a feature. Show messages like "someone just knocked down Example".
  • Offline fallback: the gateway persists the last known state, and Nuxt renders a static snapshot with a "live cluster offline" banner. HR never sees an error page.
  • Permanently unhealthy services get resource limits and a long backoff, so they don't waste CPU.

7. Narrative layer

  • Every fall triggers a story card: what went wrong in that chapter and what got Noel back up.
  • The time to recover is real measured seconds, shown next to the story.
  • Permanently failed chapters show a "lesson" card instead of a recovery.
  • Failures must be labeled explicitly as lessons, never as bugs.

8. k6 integration

Use Implementation Visitor sees
Real engineering k6 in CI against staging. Performance thresholds gate release-please releases. Badge: "p95 < X ms, last run"
Interactive pressure test Predefined script run as a k8s Job with the grafana/k6 image. Capped VUs and duration, one run at a time across the whole site. HPA scales replicas up and down live, with a latency graph
Dev layer Raw k6 summary streamed to the terminal view Full metrics
  • HPA uses metrics-server, which ships with k3s by default. No extra tooling.
  • No k6 operator; a plain Job is enough. The operator would be extra tooling and needs approval.
  • Never allow visitor-defined k6 scripts or parameters. That would turn the site into a DoS tool against the home server.

9. Build order

  1. Go chapter-service template with /healthz, /ready and /fall, configured by env.
  2. Manifests for all chapters (Jobs plus Deployments), with states set through config.
  3. Go gateway: informer, SSE, allowlisted actions, rate limits, snapshot persistence.
  4. Nuxt Layer 0, plus Layer 1 life map and story cards.
  5. Layer 2 terminal view.
  6. k6: first as a CI gate, then as the bounded interactive Job, then the HPA demo.
  7. MCP endpoint on the gateway, reusing the action allowlist.

10. Risks

Risk Mitigation
HR confusion Layer 0 is conventional and complete on its own. The interactive part is optional.
Spectacle without substance Every state change links to a story card
Home server downtime Snapshot fallback, plus Layer 0 served statically
Abuse Cooldowns, global k6 lock, no raw cluster exposure
"Unhealthy" read as incompetence Failures labeled as lessons

11. Open decisions

  • Final chapter list and the state assigned to each chapter (completed, active, unfinished, permanently failed).
  • Story card content per chapter: the setback and the recovery.
  • Life map visual form: timeline, graph or map.
  • Where state snapshots persist: file, ConfigMap or a database. Any new database needs approval.
  • Staging environment for k6 in CI: a separate namespace or a separate cluster.
  • Scope of the MCP endpoint: read-only, or read plus /fall.
  • Whether Layer 0 is served by Nuxt or as a fully static page outside the cluster for maximum uptime.