docs(okf): move bundle to repo root and retire brief
The brief is fully captured in the bundle; it stays in git history. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
957a386b58
commit
64fef83314
22 files changed
+37
-153
No files matched your search
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -1,133 +0,0 @@
|
|||||||
# 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.
|
|
||||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -0,0 +1,24 @@
|
|||||||
|
---
|
||||||
|
type: Decision
|
||||||
|
title: Knowledge bundle lives at the repository root
|
||||||
|
description: The repository root is the OKF bundle root; any other markdown file there needs frontmatter to stay conformant.
|
||||||
|
tags: [decision, okf]
|
||||||
|
status: stable
|
||||||
|
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
||||||
|
verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
|
||||||
|
---
|
||||||
|
|
||||||
|
# Decision
|
||||||
|
|
||||||
|
The OKF v0.2 bundle root is the repository root.
|
||||||
|
|
||||||
|
# Consequence
|
||||||
|
|
||||||
|
OKF requires frontmatter with a `type` in every non-reserved `.md` file in the
|
||||||
|
bundle. Any other markdown at the root breaks conformance unless it carries
|
||||||
|
frontmatter, for example:
|
||||||
|
|
||||||
|
- `README.md`: give it frontmatter (`type: Readme`) or skip it; `index.md` already does its job.
|
||||||
|
- `CHANGELOG.md` from release-please: release-please writes it without
|
||||||
|
frontmatter. Options: point release-please's `changelog-path` at a non-`.md`
|
||||||
|
file, or accept that one file is non-conformant.
|
||||||
File renamed without changes.
@@ -4,7 +4,7 @@
|
|||||||
* [Accept home-server downtime in v1](accept-downtime-v1.md) - v1 serves everything from the home server; if it is down, the whole site is down.
|
* [Accept home-server downtime in v1](accept-downtime-v1.md) - v1 serves everything from the home server; if it is down, the whole site is down.
|
||||||
* [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.
|
* [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.
|
||||||
* [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.
|
* [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.
|
||||||
* [Knowledge bundle lives in knowledge/](bundle-in-subdirectory.md) - The OKF bundle sits in a subdirectory, not at the repository root.
|
* [Knowledge bundle lives at the repository root](bundle-at-root.md) - The repository root is the OKF bundle root; any other markdown file there needs frontmatter to stay conformant.
|
||||||
|
|
||||||
# Open
|
# Open
|
||||||
|
|
||||||
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -1,18 +0,0 @@
|
|||||||
---
|
|
||||||
type: Decision
|
|
||||||
title: Knowledge bundle lives in knowledge/
|
|
||||||
description: The OKF bundle sits in a subdirectory, not at the repository root.
|
|
||||||
tags: [decision, okf]
|
|
||||||
status: stable
|
|
||||||
generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
|
|
||||||
---
|
|
||||||
|
|
||||||
# Decision
|
|
||||||
|
|
||||||
The OKF v0.2 bundle lives in `knowledge/`.
|
|
||||||
|
|
||||||
# Why
|
|
||||||
|
|
||||||
OKF requires frontmatter in every non-reserved `.md` file in the bundle. The
|
|
||||||
repo root will hold files like `README.md` and release-please's `CHANGELOG.md`
|
|
||||||
that have none, which would make a root-level bundle non-conformant.
|
|
||||||
@@ -1,5 +1,6 @@
|
|||||||
# Update Log
|
# Update Log
|
||||||
|
|
||||||
## 2026-10-11
|
## 2026-10-11
|
||||||
|
* **Update**: Moved the bundle from `knowledge/` to the repository root and replaced the planning brief with this bundle. See [bundle at root](/decisions/bundle-at-root.md).
|
||||||
* **Creation**: Wrote the [overview](/overview.md), [architecture](/architecture/), [decisions](/decisions/), [chapter states](/chapters/state-mapping.md) and [roadmap](/roadmap.md) from the planning conversation.
|
* **Creation**: Wrote the [overview](/overview.md), [architecture](/architecture/), [decisions](/decisions/), [chapter states](/chapters/state-mapping.md) and [roadmap](/roadmap.md) from the planning conversation.
|
||||||
* **Initialization**: Created the bundle [index](/index.md).
|
* **Initialization**: Created the bundle [index](/index.md).
|
||||||
@@ -61,3 +61,13 @@ page shows the real recovery time next to the story of how Noel recovered.
|
|||||||
Go, k3s, Snyk, Gitea Actions, release-please, Cloudflare Tunnel, and k6.
|
Go, k3s, Snyk, Gitea Actions, release-please, Cloudflare Tunnel, and k6.
|
||||||
- **Nobody gets Kubernetes API access.** Visitors and agents only talk to the gateway.
|
- **Nobody gets Kubernetes API access.** Visitors and agents only talk to the gateway.
|
||||||
- **Failures are lessons, never bugs.**
|
- **Failures are lessons, never bugs.**
|
||||||
|
|
||||||
|
# Risks
|
||||||
|
|
||||||
|
| Risk | Mitigation |
|
||||||
|
|---|---|
|
||||||
|
| HR confusion | The first screen 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 | Accepted for v1, see [decision](/decisions/accept-downtime-v1.md). |
|
||||||
|
| Abuse | Cooldowns, global rate limit, no raw cluster access, no visitor-defined k6 scripts. |
|
||||||
|
| "Unhealthy" read as incompetence | Failures are labeled as lessons. |
|
||||||
@@ -115,7 +115,7 @@ when its "done when" check passes on the real cluster, not locally.
|
|||||||
|
|
||||||
- Final chapter list, one manifest per chapter, story text, final PDF CV.
|
- Final chapter list, one manifest per chapter, story text, final PDF CV.
|
||||||
- Point the apex domain at the tunnel.
|
- Point the apex domain at the tunnel.
|
||||||
- One `knowledge/chapters/<name>.md` concept per chapter.
|
- One `chapters/<name>.md` concept per chapter.
|
||||||
- **Done when:** someone from HR finds the PDF within 10 seconds, and the live map shows every real chapter.
|
- **Done when:** someone from HR finds the PDF within 10 seconds, and the live map shows every real chapter.
|
||||||
|
|
||||||
---
|
---
|
||||||
Reference in new issue
Block a user