7.1 KiB
7.1 KiB
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-readyorcrash. - Knockdown via
/fallon 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-onlyget/list/watchon 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
- Go chapter-service template with
/healthz,/readyand/fall, configured by env. - Manifests for all chapters (Jobs plus Deployments), with states set through config.
- Go gateway: informer, SSE, allowlisted actions, rate limits, snapshot persistence.
- Nuxt Layer 0, plus Layer 1 life map and story cards.
- Layer 2 terminal view.
- k6: first as a CI gate, then as the bounded interactive Job, then the HPA demo.
- 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.