133 lines
7.1 KiB
Markdown
133 lines
7.1 KiB
Markdown
# 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. |