ced4568andClaude Sonnet 5
a15897c78f
- docs/LAB_ARCHITECTURE.md — the full ephemeral-per-student design: two-VM production topology (Platform VM / Lab Host VM, correction A), lifecycle, data model, networking/egress model (correction B), resource model, routing/auth model, security boundaries, failure/recovery behavior, migration path from the current single container, and the lab-host abstraction (correction D). Status updated to reflect Phase 1 is now implemented, pointing at the two docs below for specifics. - docs/PHASE1_PLATFORM_FOUNDATION.md — the Phase 1 build plan: exact Postgres schema, service boundaries, API routes, lifecycle state machine, Docker/ firewall commands, security assumptions, file layout, and a 12-test plan. Updated with "Implementation notes" at the points where testing surfaced real deviations from the original design: the per-network (not static) egress-proxy address resolution, the COALESCE reaper fix, and the provisioning-failure cleanup fix. - docs/ENGINEERING_SOP.md — new §8 mapping the platform/provisioner/ and platform/egress-proxy/ components, what's built vs. not (no Gateway, no frontend wiring — internal API only), and where identity still lives (unchanged: Lab image's own SQLite). Roadmap item 5 (per-student isolation) updated from "not started" to "Phase 1 done, not yet cleared for minors." - README.md — Multi-Student Deployment section rewritten: the old per-student- volume persistence model is superseded by the Platform's registry (progress already lives outside the disposable container as of the prior curriculum/ roster work); points at docs/LAB_ARCHITECTURE.md and platform/provisioner/ for the real architecture instead of describing three delivery modes that were never actually built out. Co-Authored-By: Claude Sonnet 5 <[email protected]>
199 lines
7.3 KiB
Markdown
199 lines
7.3 KiB
Markdown
<div align="center">
|
|
|
|
<img src="frontend/public/logo.svg" alt="KubeKosh" height="96" />
|
|
|
|
# KubeKosh — RootNode Academy Edition
|
|
|
|
**A browser-based Kubernetes lab for hands-on learners.**
|
|
Real K3s. Real `kubectl`. Instant validation. No cloud account, no local cluster.
|
|
|
|
[](LICENSE)
|
|
[](#)
|
|
[](https://k3s.io)
|
|
[](https://docs.docker.com/get-docker/)
|
|
[](https://github.com/ced4568)
|
|
|
|
</div>
|
|
|
|
---
|
|
|
|
> **Attribution.** This is a branded, modified fork of the excellent
|
|
> [`zeborg/kubekosh`](https://github.com/zeborg/kubekosh), licensed under Apache 2.0.
|
|
> RootNode Academy adds custom scenarios, branding, and multi-student deployment tooling on
|
|
> top of the upstream project. Original copyright and license notices are preserved in
|
|
> [`LICENSE`](LICENSE). Modified files are marked per Apache 2.0 §4. Full credit to
|
|
> the original author for the core platform.
|
|
|
|
---
|
|
|
|
## What It Is
|
|
|
|
KubeKosh runs a real single-node [K3s](https://k3s.io) cluster inside one Docker
|
|
container and pairs it with a browser terminal and automated scenario validation.
|
|
A learner opens a tab, gets a live cluster, runs real `kubectl`, and clicks **Validate**
|
|
to check their work against actual cluster state.
|
|
|
|
In the RootNode Academy curriculum this is the **capstone rung** — the Kubernetes & DevOps
|
|
track that sits on top of the Linux / Git / Docker foundations. It is aimed at the
|
|
advanced learner (roughly 14+), not the absolute beginner.
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
**Prerequisite:** [Docker](https://docs.docker.com/get-docker/)
|
|
|
|
```bash
|
|
docker run -itd --name kubekosh --privileged -p 7554:80 ced4568/kubekosh:latest
|
|
```
|
|
|
|
Open **http://localhost:7554** and wait ~30s for the *Cluster Ready* indicator to turn green.
|
|
|
|
> `--privileged` is required — K3s needs kernel namespaces and cgroups.
|
|
> **Do not expose this container directly to the public internet.** It is a teaching
|
|
> sandbox. Multi-student exposure is handled by the deployment layer below, not by
|
|
> publishing the raw container.
|
|
|
|
### Persist Progress
|
|
|
|
```bash
|
|
docker run -itd --name kubekosh --privileged -p 7554:80 \
|
|
-v <host_dir>:/data ced4568/kubekosh:latest
|
|
```
|
|
|
|
Progress is stored in SQLite at `/data/progress.db`. Mount a host directory to `/data`
|
|
to keep progress across restarts — one volume per student.
|
|
|
|
### Build From Source
|
|
|
|
```bash
|
|
docker build -t kubekosh .
|
|
# multi-platform
|
|
docker buildx build --platform linux/amd64,linux/arm64 -t kubekosh .
|
|
```
|
|
|
|
---
|
|
|
|
## What's Inside
|
|
|
|
| Bundle | Focus | Exam Mode |
|
|
| ------ | ----- | --------- |
|
|
| 🌱 Kubernetes Basics | Core concepts | 60 min |
|
|
| 🧑✈️ Kubernetes Administrator | CKA | 120 min |
|
|
| 🛠️ Kubernetes Developer | CKAD | 120 min |
|
|
| 🛡️ Kubernetes Security | CKS | 120 min |
|
|
|
|
**Scenario types**
|
|
|
|
- **Task** — hands-on challenge in the live terminal; **Validate** auto-checks cluster state.
|
|
- **MCQ** — multiple choice with a detailed explanation on submission.
|
|
|
|
Custom RootNode Academy scenarios live alongside upstream ones in `scenarios/data/` and are
|
|
grouped into bundles in `scenarios/bundles/`. See [`scenarios/SCHEMA.md`](scenarios/SCHEMA.md).
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
subgraph Container["Single Docker Image (--privileged)"]
|
|
NGINX["nginx :80 — reverse proxy"]
|
|
FE["Frontend<br/>React + Vite + xterm.js"]
|
|
BE["Backend<br/>Node / Express + node-pty (WebSocket PTY)"]
|
|
K3S["K3s<br/>single-node in-container cluster"]
|
|
DB[("SQLite<br/>/data/progress.db")]
|
|
|
|
NGINX --> FE
|
|
NGINX --> BE
|
|
BE -->|kubectl / PTY| K3S
|
|
BE --> DB
|
|
end
|
|
|
|
Student["Learner browser"] -->|:7554| NGINX
|
|
```
|
|
|
|
| Component | Technology |
|
|
| --------- | ---------- |
|
|
| Frontend | React + Vite, `xterm.js` |
|
|
| Backend | Node.js / Express, `node-pty` WebSocket PTY |
|
|
| Cluster | K3s (single-node, in-container) |
|
|
| Proxy | nginx on port `80`, mapped to host `7554` |
|
|
| Storage | SQLite (`better-sqlite3`) at `/data/progress.db` |
|
|
|
|
Everything runs inside one image managed by `scripts/entrypoint.sh`.
|
|
|
|
---
|
|
|
|
## Multi-Student Deployment (RootNode Academy addition)
|
|
|
|
The upstream project assumes one learner, one container — this image is still exactly that,
|
|
unmodified. RootNode Academy multiplies it into a real platform via a separate provisioning
|
|
layer rather than changing the image itself: see `docs/LAB_ARCHITECTURE.md` for the
|
|
architecture and `platform/provisioner/` for the Phase 1 implementation (Postgres-backed
|
|
environment registry, per-student Docker networking, firewall-enforced egress, idle reaper —
|
|
see `platform/provisioner/README.md` for how to run it).
|
|
|
|
**Never publish the raw privileged container** — front it with isolation. The one-container
|
|
`docker run --privileged -p 7554:80 ...` command above stays supported for local development
|
|
and scenario authoring; it is not how this gets deployed to real students.
|
|
|
|
Key properties of the Phase 1 platform (not this image):
|
|
|
|
- One container **per student**, its own Docker network, its own firewall chain — never a
|
|
shared cluster between learners.
|
|
- Progress/identity live outside the disposable container (currently this image's own SQLite,
|
|
moving to the Platform's PostgreSQL in a later phase) — destroying a student's environment
|
|
never loses their academic record.
|
|
- CPU/memory/PID/storage limits are enforced per container, config-driven.
|
|
- Egress is restricted to an allowlisted proxy at the firewall layer, not left open.
|
|
- Idle/abandoned environments are automatically cleaned up.
|
|
|
|
Production topology and what's built vs. not yet: `docs/LAB_ARCHITECTURE.md` and
|
|
`docs/PHASE1_PLATFORM_FOUNDATION.md`.
|
|
|
|
---
|
|
|
|
## Repository Layout
|
|
|
|
```
|
|
scenarios/
|
|
├── data/ # one JSON file per scenario -> <scenario-id>.json
|
|
├── bundles/ # one JSON file per bundle -> <bundle-id>.json
|
|
└── SCHEMA.md # full schema reference
|
|
|
|
backend/ server.js # Express API + WebSocket PTY
|
|
frontend/ src/ # React + Vite SPA
|
|
scripts/ entrypoint.sh # container startup (k3s -> API -> nginx)
|
|
nginx.conf # reverse-proxy config
|
|
```
|
|
|
|
---
|
|
|
|
## Authoring Scenarios
|
|
|
|
Each scenario is one JSON file in `scenarios/data/`; each bundle is one JSON file in
|
|
`scenarios/bundles/`. See [`scenarios/SCHEMA.md`](scenarios/SCHEMA.md) for the full schema.
|
|
|
|
**Task checklist**
|
|
- `validation.commands` — idempotent `kubectl` only
|
|
- `setup_commands` / `teardown_commands` — `kubectl` or native Ubuntu only
|
|
|
|
**MCQ checklist**
|
|
- `correct_option` must match an `options[].id`
|
|
- always include an `explanation`
|
|
|
|
Hot-reload while authoring (no rebuild):
|
|
|
|
```bash
|
|
docker run --rm -itd --privileged -p 7554:80 --name kubekosh \
|
|
-v $PWD/scenarios:/app/scenarios ced4568/kubekosh:latest
|
|
curl -X POST http://localhost:7554/api/cache/reload
|
|
```
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Apache 2.0 — see [`LICENSE`](LICENSE). Original work © the `zeborg/kubekosh` authors.
|
|
Modifications © RootNode Academy / Chase Dumphord (ced4568). |