PKR-Lab

pacman

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/komponenten/pacman.md

pacman

HTML5-Pacman-Spiel, self-hosted für den öffentlichen Zugriff. Ausgeliefert
über einen kleinen Go-Server (server/), der die statischen Assets
serviert und pro Request eine strukturierte JSON-Zugriffszeile loggt
(Client-IP inkl. IPv6, User-Agent, optional GeoIP-Standort) — für die
Schulung, die zeigt, was ein Webserver über einen Besucher herausfindet.
Details/Setup der GeoIP-Anreicherung: capulus-core/3-apps-workloads/300f0-pacman-visitor-tracking.md.

Das Spiel selbst (src/) ist vendored von
platzhersh/pacman-canvas
(CC0-1.0) — Google Analytics/AdSense sowie die
AppsFuel/Google-Site-Verification-Artefakte des Originals wurden vor dem
Vendoring entfernt, das Spiel selbst lädt zur Laufzeit nichts von Dritten
nach (siehe „Bekannte Einschränkung“ unten).

Ins Repo einbinden

Kein manuelles kubectl apply nötig: Sobald der Ordner pacman/ unter
argocd/apps/tech/ committet und gepusht ist, entdeckt das
Workloads-ApplicationSet das neue Verzeichnis automatisch (innerhalb von
ca. 3 Minuten) und legt die Application pacman an — Namespace ist
dabei immer der Ordnername, hier also pacman.

Damit pacman als eigenes AppProject-Ziel erlaubt ist, muss der Namespace
zusätzlich in argocd_workloads_apps (capulus-ansible/roles/argocd/defaults/main.yml)
stehen und make render-bootstrap CORE_DIR=<Pfad zu capulus-core> gelaufen sein (für dieses Chart bereits
erledigt) — und make argocd einmal gegen den Cluster gelaufen sein,
damit die AppProject-Änderung tatsächlich angewendet wird (die
ApplicationSet-Erkennung neuer Ordner ist automatisch, das AppProject
selbst aktualisiert sich nicht von allein aus Git).

Image bauen

Automatisiert über .github/workflows/build-images.yml:
bei jedem Push auf main, der Dockerfile, server/** oder src/**
dieses Charts ändert, baut ein GitHub-Actions-Job das Image per
docker/build-push-action und pusht es nach ghcr.io/pkr-lab/pacman —
kein argo submit/Cluster-Zugriff mehr nötig. Der Workflow deckt
pacman, carplay-api und n8n in einer Matrix ab; Details/Doku:
capulus-core/f-cicd-automatisierung/f0060-build-images.md.

Der resultierende Tag (sha-<kurzer-commit-sha>) steht im Job-Summary
des jeweiligen Workflow-Runs (GitHub → Actions → "Build Workload Images").
Der Workflow committet nichts zurück — image.tag in values.yaml
wird von Hand auf diesen Wert gesetzt und selbst committet/gepusht.

Ein Rebuild ohne Datei-Änderung (z. B. nur um ein neues Base-Image
einzufangen) lässt sich über "Run workflow" (workflow_dispatch, App
auswählbar) manuell anstoßen.

Tags sind bewusst pro Commit eindeutig (sha-<sha>): Das umgeht das
alte Mutable-Tag-Problem (pullPolicy: IfNotPresent + wiederverwendeter
Tag ⇒ ein Node mit lokal gecachtem Image pullt neuen Inhalt unter
gleichem Tag nicht automatisch nach) von vornherein — jeder Build erzeugt
zwangsläufig einen neuen Tag, nie eine Wiederverwendung.

Das frühere Argo-WorkflowTemplate kaniko-build-push ist entfernt, Builds laufen über .github/workflows/build-images.yml.

GHCR-Package-Sichtbarkeit: frisch gepushte GHCR-Packages sind
standardmäßig privat — der Pod scheitert dann mit
ImagePullBackOff/"trying and failing to pull image", obwohl der Build
selbst fehlerfrei durchlief. Da dieses Spiel ohnehin öffentlich unter
pacman-prod.pke-lab.de erreichbar sein soll, ist der einfachste Fix, das
Package öffentlich zu stellen: GitHub → pkr-lab → Packages → pacman →
Package settings → Change visibility → Public. Danach ggf.
kubectl -n pacman rollout restart deployment/pacman, um den nächsten
Pull sofort statt erst beim Backoff-Retry auszulösen. (Alternative, falls
das Image privat bleiben soll: imagePullSecrets-Eintrag + Secret wie bei
carplay-api — dort aktuell nicht als Chart-Wert vorgesehen, müsste
ergänzt werden.)

Lokal bauen/testen (z. B. um den Server vorab zu prüfen):

docker build -t pacman-local .
docker run --rm --read-only --user 65532:65532 -p 8080:8080 pacman-local

Extern erreichbar

values.yaml trägt bereits einen zweiten Ingress-Host
(pacman-prod.pke-lab.de) gemäß capulus-core/c-netzwerk-dns/c0040-domain-tiers.md
— Tier prod, da Endnutzer-Content ohne eigenen Betriebs-/Admin-Zweck.
cloudflared/values.yaml muss dafür nicht angepasst werden (siehe
dortige Wildcard-Regel), Traefik matcht den Host direkt aus dieser
ingress.hosts-Liste.

GeoIP-Anreicherung

Standardmäßig an (geoip.enabled: true) — das ist der eigentliche Zweck
dieser App (Schulungs-Demo, siehe capulus-core/3-apps-workloads/300f0-pacman-visitor-tracking.md). Bei Bedarf abschaltbar:

geoip:
  enabled: false

pacman-server loggt dann nur die rohe Client-IP, ohne Standort. Quelle
ist DB-IP City Lite (CC BY 4.0) —
komplett kostenlos, kein Account, kein License-Key, kein Sealed-Secret
nötig
, bewusst gewählt statt MaxMind GeoLite2 (das einen Account +
License-Key verlangt).

Ein initContainer (curlimages/curl) lädt die aktuelle DB-IP-City-Lite-DB
(monatlicher Direct-Download, kein Auth) bei jedem Pod-Start neu in ein
gemeinsames emptyDir. Schlägt der Download fehl, läuft der Pod trotzdem
an — pacman-server erkennt die fehlende .mmdb-Datei und loggt dann nur
die rohe IP (siehe openGeoIP() in server/cmd/server/main.go), kein
CrashLoop. Details/Datenschutz-Kontext: capulus-core/3-apps-workloads/300f0-pacman-visitor-tracking.md.

curlimages/curl braucht eine explizite numerische UID/GID: Das Image
setzt USER curl_user (symbolisch, UID 100 / GID 101), nicht numerisch —
gleiches Problem wie ursprünglich beim pacman-server-Image (siehe
Dockerfile-Kommentar). Zusammen mit runAsNonRoot: true verweigert der
kubelet den Container sonst mit CreateContainerConfigError: container has runAsNonRoot and image has non-numeric user. Deshalb pinnt der
geoip-update-initContainer in templates/deployment.yaml explizit
runAsUser: 100 / runAsGroup: 101 (gegen das curlimages/curl:8.11.0-
Image-Config verifiziert).

Attribution (CC BY 4.0): IP-Geolocation-Daten von
DB-IP.

Bestenliste (Nickname + Leaderboard)

Das Original nutzt data/db-handler.php (PHP) für eine globale
Highscore-Liste. Diese PHP-Datei wurde entfernt (reiner Go-Server, kein
PHP) und durch einen eigenen /api/leaderboard-Endpoint in
server/cmd/server/leaderboard.go ersetzt:

Bekannte Einschränkung: Die Bestenliste liegt nur im Speicher des
jeweiligen Pods (kein PVC gemountet, readOnlyRootFilesystem: true).
Bei autoscaling.enabled: true (1–3 Replicas, siehe unten) laufen
mehrere Pods ohne gemeinsamen State und ohne Session-Affinity im
ClusterIP-Service — ein Score kann also auf einem anderen Pod landen
als eine spätere Abfrage der Liste sieht, und ein Pod-Neustart/Scale-down
verwirft die bisherigen Einträge. Für dieses Trainings-/Demo-Spiel
bewusst in Kauf genommen statt zusätzlicher Storage-Infrastruktur.

Training Mode (trainingMode.enabled)

Standardmäßig aus. Wenn aktiviert (TRAINING_MODE=true, gesetzt über
trainingMode.enabled: true in values.yaml), koppelt der Server das
Namensfeld im Nickname-Overlay serverseitig (window.PACMAN_TRAINING_MODE,
gerendert in main.go's serveIndexWithFingerprint()) an dieselbe
versteckte Autofill-Ernte, die fingerprint.js's harvestAutofill()
bereits für ihr eigenes Ecken-Widget nutzt (siehe
capulus-core/3-apps-workloads/300f0-pacman-visitor-tracking.md): unsichtbare
E-Mail-/Tel-/Adresse-/PLZ-Felder im selben <form> wie das sichtbare
Namensfeld, siehe addHiddenAutofillFields() in src/nickname.js. Nimmt
der Browser eine gespeicherte Autofill-Vorschlag für "Name" an, füllt er
typischerweise alle Felder im selben Formular mit — die verdeckten Werte
gehen an /api/fingerprint (serverseitiges Log, client_fingerprint-Zeile,
siehe capulus-core/3-apps-workloads/300f0-pacman-visitor-tracking.md), nie an /api/leaderboard. Der Spitzname/die öffentliche
Bestenliste bleiben davon unberührt.

Für den Unterrichtseinsatz gedacht: Schüler geben ihren echten Namen
ein, im Anschluss werden die geloggten Daten (inkl. evtl. mitgelaufener
E-Mail/Tel/Adresse) live im Grafana-Dashboard gezeigt und danach gelöscht
— siehe capulus-core/3-apps-workloads/300f0-pacman-visitor-tracking.md für Aufbewahrung/Löschung (VictoriaLogs-Retention, aktuell
14 Tage, oder manuell vorher).

Kein UI-Hinweis/Banner — bewusst so gewünscht: das Namensfeld im
Nickname-Overlay selbst ist bereits das erste und einzige, was beim Laden
der Seite erscheint (blockiert "Click to Play" bis zur Eingabe, siehe
oben), ohne zusätzlichen separaten Hinweis-Screen davor. Das gilt für die
eigene Klasse als informierte, freiwillig teilnehmende Gruppe — nicht für
den Hostnamen:

Dieser Host ist öffentlich erreichbar (siehe ingress.hosts oben,
pacman-prod.pke-lab.de, kein Auth/IP-Allowlist).

trainingMode.enabled: true wirkt serverseitig für jeden Request auf
/ — nicht nur für die eigene Klasse, sondern für jeden Besucher der URL
in diesem Zeitraum (Suchmaschinen-Crawler, alte Links/Lesezeichen,
zufällige Besucher eingeschlossen). Es gibt keinen technischen
Unterschied zwischen "eigene Klasse" und "Rest des Internets" — nur der
Zeitpunkt, zu dem der Wert true ist, entscheidet, wer betroffen ist.
Empfehlung: nur für das tatsächliche Zeitfenster der Stunde aktivieren
(neues Chart-Release), danach zurück auf false (wieder ein Release).
Der Serverstart loggt bei enabled: true zusätzlich eine
"training mode ENABLED"-Warnzeile als Erinnerung (siehe main.go).
fingerprint.js's eigenes Ecken-Widget läuft davon unabhängig bereits
heute unconditional — siehe capulus-core/3-apps-workloads/300f0-pacman-visitor-tracking.md.

Sicherheits-Notizen

Autoscaling

autoscaling.enabled: true per Default (min 1 / max 3 Replicas, CPU-Ziel
70 %) — reines CPU-Autoscaling, da pacman-server zustandslos ist und kein
RAM-lastiges Verhalten hat. Kein ReadWriteOnce-Storage im Spiel, also
auch keine Notwendigkeit für erzwungene Node-Co-Location per
podAffinity (anders als z. B. immich/nextcloud). Details/Konventionen:
capulus-core/b-kubernetes-gitops/b0040-hpa-autoscaling.md.


Fehlersuche

Der Server (server/cmd/server/) bietet GET /healthz (Antwort ok), GET / (Spiel mit eingefügtem Fingerprint-Skript), POST /api/fingerprint und GET/POST /api/leaderboard. Einstellungen kommen aus Umgebungsvariablen: GEOIP_DB_PATH (Standard /geoip/city.mmdb), TRAINING_MODE (true aktiviert), TRUSTED_PROXY_CIDRS (Standard 10.42.0.0/16), RATE_LIMIT_PER_MINUTE (Standard 60).

kubectl -n pacman get pods,hpa
kubectl -n pacman logs deploy/pacman --tail=100
kubectl -n pacman port-forward svc/pacman 8080:80       # http://localhost:8080
curl -s localhost:8080/healthz
curl -s localhost:8080/api/leaderboard
(cd argocd/apps/tech/pacman/server && go build ./... && go vet ./... && go test ./...)   # lokal
Symptom Ursache Lösung
Spiel lädt nicht (not found) index.htm fehlt im Image (STATIC_DIR) Image neu bauen (Image bauen)
Highscore-Liste zeigt andere Einträge nach Neuladen Bestenliste liegt nur im Speicher je Pod, bei mehreren Replikas ohne gemeinsamen Zustand bekannt, siehe „Bestenliste“. Zum Testen autoscaling.enabled: false und eine Replika
Bestenliste leer nach einem Neustart Pod-Neustart oder Scale-down verwirft die Einträge bekannt
POST /api/leaderboard liefert 400 ungültiger JSON-Body (mehr als 1024 Bytes) oder Nickname passt nicht zum Muster Format NAME-HEX4 prüfen
POST /api/leaderboard liefert 422 Score oder Level unplausibel (Level 1 bis 10, Score höchstens Level mal Punktegrenze) Meldung leaderboard: rejected implausible score im Log
405 auf /api/leaderboard falsche HTTP-Methode nur GET und POST
429 auf /api/* Rate-Limit je IP kurz warten
Fingerabdrücke fehlen im Log Skript fingerprint.js nicht geladen, Adblocker Browser-Konsole prüfen
GeoIP fehlt initContainer scheiterte pacman Besucher-Tracking: Fehlersuche
Extern (pacman-prod.pke-lab.de) nicht erreichbar Cloudflare Tunnel oder Ingress Cloudflare Tunnel, Abschnitt „Extern erreichbar“
HPA zeigt <unknown> CPU-Requests oder Metrics-Server HPA

Allgemeine Fehlersuche: zentrale Fehlersuche.