Tag 14: Projekte und Plattform-Ergonomie
Ziel: Jedes Projekt bringt seine Umgebung, Sprachversionen und Befehle mit, und ein Prod-Cluster ist im Terminal nicht zu übersehen. · Dauer: ca. 120 min · Voraussetzung: Tag 13
Briefing
- direnv lädt beim
cdins Projekt Variablen aus.envrcund entlädt sie beim Verlassen. mise liefert pro Projekt die passenden Go-, Python- und Node-Versionen. - make oder just sind das
Inhaltsverzeichnis eines Projekts:
make helpstatt Wiki-Suche. - Kubernetes: kubeconfig pro Projekt,
kubectx/kubens, Aliase mit Completion, ein Wächter für Prod und ein roter Prompt. - Skripte laufen mit
set -euo pipefail,trapundshellcheck.entr,watchundhyperfineschließen die Feedback-Schleife. - Alles läuft in
~/term-lab/projektund mit einer Lab-kubeconfig mit erfundenen Kontexten. Deine echte~/.kube/configbleibt unberührt.
cd ~/term-lab/projekt
├─ direnv ─► APP_ENV, PORT, KUBECONFIG=../kube/config, PATH+=scripts
├─ mise ─► go 1.25, python 3.13, node 22
└─ make ─► run · test · vet · lint · report
Drill 1: direnv – Umgebung pro Verzeichnis
Der Hook kommt in die Lab-Konfiguration, danach die Shell neu starten.
echo 'eval "$(direnv hook zsh)"' > ~/term-lab/config/zsh/direnv.zsh
exec zsh
cd ~/term-lab/projekt
cat > .envrc <<'EOF'
# Projekt-Umgebung – wird beim Betreten geladen, beim Verlassen entladen
export APP_ENV=dev
export PORT=8080
export KUBECONFIG="$(expand_path ../kube/config)"
export K9S_CONFIG_DIR="$(expand_path ../kube/k9s)"
PATH_add scripts
dotenv_if_exists .env.local
EOF
echo 'DB_PASSWORD=lab-db-pw-1234 # Lab-Wert' > .env.local
echo '.env.local' >> .gitignoreErwartet:
direnv: error ~/term-lab/projekt/.envrc is blocked. Run `direnv allow` to approve
its content
Warum? direnv führt nur Dateien aus, die du freigegeben hast. Jede
Änderung an .envrc sperrt sie erneut – ein fremdes
git pull kann dir so nichts unterschieben.
direnv allow
echo "$APP_ENV $PORT $DB_PASSWORD"; echo $KUBECONFIG
cd .. && echo "draußen: ${APP_ENV:-leer}"; cd projektErwartet:
direnv: loading ~/term-lab/projekt/.envrc
direnv: export +APP_ENV +DB_PASSWORD +K9S_CONFIG_DIR +KUBECONFIG +PORT ~PATH
dev 8080 lab-db-pw-1234
/Users/<du>/term-lab/kube/config
direnv: unloading
draußen: leer
direnv: loading ~/term-lab/projekt/.envrc
Sicherheit:
.envrckommt ins Repo,.env.localmit Secrets nie. Besser noch: Secrets zur Laufzeit holen, etwaexport TOKEN=$(op read op://Lab/api/token)in der.envrc.
Fortschritt speichern? Kostenlos registrieren
Drill 2: mise – Sprachversionen pro Projekt
mise use schreibt eine mise.toml ins
Projekt und lädt die Werkzeuge herunter (zusammen rund 150 MB nach
~/.local/share/mise). Im Lab lenkst du das mit
export MISE_DATA_DIR=$LAB/mise vorher um, dann bleibt dein
echtes mise-Verzeichnis unberührt. -n zeigt vorher, was
passieren würde.
echo 'eval "$(mise activate zsh)"' > ~/term-lab/config/zsh/mise.zsh
exec zsh
cd ~/term-lab/projekt
mise use -n [email protected] [email protected] node@22
mise use [email protected] [email protected] node@22
cat mise.tomlErwartet (gekürzt, Patch-Versionen können abweichen):
mise [email protected] ⇢ would install
mise [email protected] ⇢ would install
mise [email protected] ⇢ would install
mise would update ~/term-lab/projekt/mise.toml (add: [email protected], [email protected], …)
mise ✓ [email protected] 10.7s node-v22.23.3-darwin-arm64.tar.gz
mise ✓ [email protected] 17.5s go1.25.14.darwin-arm64.tar.gz
mise ~/term-lab/projekt/mise.toml tools: [email protected], [email protected], [email protected]
[tools]
go = "1.25"
node = "22"
python = "3.13"
mise current
whence -p go python3 node | sed "s#$HOME#~#"Erwartet:
go 1.25.14
node 22.23.3
python 3.13.16
~/.local/share/mise/installs/go/1.25.14/bin/go
~/.local/share/mise/installs/python/3.13/bin/python3
~/.local/share/mise/installs/node/22/bin/node
Achtung: Prüfe in der
would update-Zeile, welche Dateimise useändert. Steht dort deine globale~/.config/mise/config.toml, erzwingst du die Projektdatei mitmise use --path mise.toml ….
Warum mise statt brew install go? Brew
kennt eine Version für alle Projekte. Mit mise hat jedes Repo seine
eigene, festgehalten in mise.toml und mit eingecheckt – das
CI liest dieselbe Datei.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Sichere Skripte – set -euo pipefail, trap, shellcheck
Erst das Gegenbeispiel. Sieben Zeilen, vier echte Gefahren:
cd ~/term-lab/projekt
cat > ~/term-lab/unsicher.sh <<'EOF'
#!/bin/bash
cd $1
for f in $(ls *.log); do
grep ERROR $f | wc -l
done
rm -rf $BUILD_DIR/*
EOF
shellcheck ~/term-lab/unsicher.sh | grep '\^.*SC' | cut -c1-80Erwartet (gekürzt):
^---^ SC2164 (warning): Use 'cd ... || exit' or 'cd ... || return' in case cd fa
^-- SC2086 (info): Double quote to prevent globbing and word splitting.
^---------^ SC2045 (error): Iterating over ls output is fragile. Use gl
^-----------^ SC2126 (style): Consider using 'grep -c' instead of 'grep|wc -l'
^----------^ SC2115 (warning): Use "${var:?}" to ensure this never expand
Warum ist SC2115 die wichtigste Zeile? Ist BUILD_DIR
leer, steht da rm -rf /*. Das passiert, wenn
cd scheitert und niemand es merkt.
Drei Optionen fangen genau diese Fehler ab:
bash -c 'set -u; echo "Ziel: $BUILD_DIR"; echo weiter'; echo "rc=$?"
bash -c 'grep x /nix/da | sort; echo "rc=$?"'
bash -c 'set -o pipefail; grep x /nix/da | sort; echo "rc=$?"'Erwartet:
bash: Zeile 1: BUILD_DIR ist nicht gesetzt.
rc=127
grep: /nix/da: No such file or directory
rc=0
grep: /nix/da: No such file or directory
rc=2
-e bricht beim ersten Fehler ab, -u bei
unbekannten Variablen, pipefail macht den Fehler in der
Mitte einer Pipe sichtbar. Jetzt die Vorlage für alle eigenen
Skripte:
cat > scripts/fehler.sh <<'EOF'
#!/usr/bin/env bash
# fehler.sh – ERROR-Zeilen pro Komponente zählen
# Nutzung: scripts/fehler.sh [logdatei]
set -euo pipefail
IFS=$'\n\t'
readonly LOG="${1:-logs/app.log}"
tmp="$(mktemp -t fehler.XXXXXX)"
cleanup() { rm -f -- "$tmp"; }
trap cleanup EXIT
trap 'echo "✘ Fehler in Zeile $LINENO: $BASH_COMMAND" >&2' ERR
[[ -r "$LOG" ]] || { echo "✘ Datei nicht lesbar: $LOG" >&2; exit 2; }
grep -F ' ERROR ' -- "$LOG" > "$tmp" || true # 0 Treffer ist kein Fehler
awk '{print $2}' "$tmp" | sort | uniq -c | sort -rn
echo "Summe: $(wc -l < "$tmp" | tr -d ' ')"
EOF
chmod +x scripts/fehler.sh
shellcheck scripts/fehler.sh && echo "✔ shellcheck"
fehler.sh; fehler.sh nix.log; echo "rc=$?"Erwartet:
✔ shellcheck
50 checkout
Summe: 50
✘ Datei nicht lesbar: nix.log
rc=2
Warum klappt fehler.sh ohne Pfad?
PATH_add scripts aus der .envrc. Der
EXIT-Trap räumt die Temp-Datei auch bei Abbruch und
Ctrl-C weg.
Fortschritt speichern? Kostenlos registrieren
Drill 4: make und just – das Inhaltsverzeichnis des Projekts
Ein help-Ziel liest die ##-Kommentare aus
dem Makefile selbst. Make braucht Tabs vor den Befehlen
– kopiere die Datei deshalb aus dem Begleitmaterial.
cp $BUCH/projekt-tools/Makefile ~/term-lab/projekt/
make
make report
make test vet lintErwartet:
help Diese Hilfe
run Shop lokal starten (PORT aus .envrc)
test Go-Tests
vet Go statisch prüfen
lint Shell-Skripte prüfen
report Log-Level zählen
python3 scripts/report.py logs/app.log
INFO 350
WARN 50
ERROR 50
DEBUG 50
go test ./...
? example.com/shop/cmd/shop [no test files]
? example.com/shop/internal/cart [no test files]
go vet ./...
shellcheck scripts/*.sh
just ist ein reiner Befehlsläufer ohne
make-Altlasten: keine Tabs, Parameter mit Standardwerten,
just --list eingebaut. Die Datei
$BUCH/projekt-tools/justfile enthält dieselben Ziele.
cp $BUCH/projekt-tools/justfile ~/term-lab/projekt/
just --list
just report logs/app.logErwartet (gekürzt, kann je nach Version abweichen):
Available recipes:
check-manifests ctx="kind-lab" # Manifeste gegen einen Kontext prüfen …
default # Standard: Rezepte auflisten
lint # Shell-Skripte prüfen
report file="logs/app.log" # Log-Level zählen, optional andere Datei
run # Shop lokal starten
test # Go-Tests
INFO 350
…
Tipp: Make, wenn das Team es schon hat oder echte Datei-Abhängigkeiten zählen. just, wenn es nur um benannte Befehle geht. mise kann mit
[tasks]in dermise.tomldasselbe – ein Werkzeug weniger.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Lab-kubeconfig, kubectx und kubens
Die .envrc zeigt schon auf
~/term-lab/kube/config. Das Skript legt dort drei erfundene
Kontexte an – ohne echten Cluster und ohne deine echte kubeconfig. Jeder
Aufruf darin trägt kubectl config --kubeconfig "$KC" … –
das ist die Versicherung.
$BUCH/projekt-tools/kubeconfig-lab.sh ~/term-lab/kube/config
cd ~/term-lab/projekt # direnv setzt KUBECONFIG
kubectl config get-contextsErwartet:
Switched to context "kind-lab".
CURRENT NAME CLUSTER AUTHINFO NAMESPACE
* kind-lab kind-lab kind-lab-user default
kunde-dev kunde-dev kunde-dev-user default
kunde-prod kunde-prod kunde-prod-user default
Jetzt wechseln. kubectx arbeitet rein lokal in der
kubeconfig, - springt zurück wie cd -.
kubectx
kubectx kunde-dev
kubectx -
kubectx -cErwartet:
kind-lab
kunde-dev
kunde-prod
✔ Switched to context "kunde-dev".
✔ Switched to context "kind-lab".
kind-lab
kubens fragt die Namespaces beim API-Server ab – ohne
Cluster scheitert es. Der Namespace lässt sich aber auch offline am
Kontext setzen:
kubens shop
kubectl config set-context --current --namespace=shop
kubectl config view --minify -o jsonpath='{..namespace}'; echoErwartet:
error: failed to query if namespace exists (is cluster accessible?): …
dial tcp 127.0.0.1:6443: connect: connection refused
Context "kind-lab" modified.
shop
Tipp: Ohne Argument und mit installiertem fzf öffnen
kubectxundkubenseinen Fuzzy-Picker (Tag 7).kubectxmerkt sich den vorigen Kontext in~/.kube/kubectx– die einzige Datei, die es außerhalb der kubeconfig schreibt.
Fortschritt speichern? Kostenlos registrieren
Drill 6: kubectl-Aliase, Completion und ein Prod-Wächter
$BUCH/projekt-tools/k8s.zsh bringt Aliase, Completion
für k und eine Funktion kubectl, die
schreibende Befehle auf *prod* nur nach Rückfrage
durchlässt. Completion braucht compinit aus Tag 2.
cp $BUCH/projekt-tools/k8s.zsh ~/term-lab/config/zsh/
exec zsh
echo "Completion für k: $_comps[k]"
alias k kgpErwartet:
Completion für k: _kubectl
k=kubectl
kgp='kubectl get pods'
Der Wächter im Kern:
kubectl() {
local ctx verb="${1:-}"
ctx=$(command kubectl config current-context 2>/dev/null)
if [[ $ctx == *prod* && $verb == (apply|create|delete|edit|patch|replace\
|scale|rollout|drain|cordon|label|annotate|set) ]]; then
print -P "%F{red}%BACHTUNG:%b kubectl $verb auf Kontext '$ctx'%f"
read -q "?Wirklich ausführen? [y/N] " || { echo; return 1; }
echo
fi
command kubectl "$@"
}Probiere ihn aus – n tippen:
kubectx kunde-prod
k delete pod web-1; echo "rc=$?"
k get pods --request-timeout=2s
kubectx kind-labErwartet:
✔ Switched to context "kunde-prod".
ACHTUNG: kubectl delete auf Kontext 'kunde-prod'
Wirklich ausführen? [y/N] n
rc=1
Unable to connect to the server: dial tcp: lookup prod.k8s.kunde.example: no such host
✔ Switched to context "kind-lab".
Warum command kubectl? Ohne command ruft
die Funktion sich selbst auf. Lesende Befehle wie get
laufen ohne Rückfrage durch.
| Alias | Befehl | Merkhilfe |
|---|---|---|
k |
kubectl |
alles beginnt mit k |
kgp / kgpa |
get pods / -A |
get pods all |
kd / kl |
describe / logs -f |
describe, logs |
kx / kn |
kubectx / kubens |
context, namespace |
Tipp:
source <(kubectl completion zsh)kostet bei jedem Shell-Start rund 25 ms (Drill 9 misst nach). Schneller: einmalkubectl completion zsh > ~/term-lab/zsh/completions/_kubectlund das Verzeichnis vorcompinitinfpathaufnehmen.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Prod in Rot – der Prompt
starship hat ein kubernetes-Modul, das standardmäßig aus
ist. Muster pro Kontext färben Prod rot und kürzen lange Namen. Die
Konfig hängst du an die Lab-starship.toml an
(STARSHIP_CONFIG aus Tag 0) – vorher prüfen, dass dort noch
kein [kubernetes]-Block steht.
grep -q '^\[kubernetes\]' ~/term-lab/config/starship.toml || \
cat >> ~/term-lab/config/starship.toml <<'EOF'
[kubernetes]
disabled = false
format = '[$symbol$context( \($namespace\))]($style) '
style = 'yellow'
[[kubernetes.contexts]]
context_pattern = '.*prod.*'
style = 'bold white bg:red'
context_alias = 'PROD'
[[kubernetes.contexts]]
context_pattern = 'kind-(?P<name>.+)'
style = 'green'
context_alias = 'kind:$name'
EOF
starship module kubernetes; echo
kubectx kunde-prod >/dev/null; starship module kubernetes; echo; kubectx - >/dev/nullErwartet (gekürzt, kann je nach Version abweichen; Farben hier nicht sichtbar):
☸ kind:lab (shop)
☸ PROD (default)
Ohne starship übernimmt k8s_prompt aus
k8s.zsh den rechten Prompt (RPROMPT): gelb für
alles, rot und fett für *prod*. Es liest nur die
kubeconfig, ohne API-Aufruf.
print -P "$(k8s_prompt)"
kubectx kunde-prod >/dev/null; print -P "$(k8s_prompt)"; kubectx - >/dev/nullErwartet (oben gelb, unten rot):
⎈ kind-lab:shop
⎈ kunde-prod:default
Achtung: Ein Prompt zeigt den Kontext beim Zeichnen. Wechselt ein anderes Terminal den Kontext in derselben kubeconfig, stimmt die Anzeige bis zur nächsten Zeile nicht. Darum: eine kubeconfig pro Projekt per direnv statt einer globalen.
Fortschritt speichern? Kostenlos registrieren
Drill 8: k9s – sicher starten
k9s liest dieselbe kubeconfig. K9S_CONFIG_DIR aus der
.envrc hält auch seine Konfiguration im Lab –
k9s info zeigt die Pfade.
Prod nur lesend öffnen – per Flag oder dauerhaft pro Kontext:
k9s --context kunde-prod --readonly
mkdir -p ~/term-lab/kube/k9s/clusters/kunde-prod/kunde-prod
cat > ~/term-lab/kube/k9s/clusters/kunde-prod/kunde-prod/config.yaml <<'EOF'
k9s:
cluster: kunde-prod
readOnly: true
EOFOhne erreichbaren Cluster zeigt k9s nur einen Verbindungsfehler –
beenden mit :q. Das Format der Kontext-Konfig kann je nach
k9s-Version abweichen, k9s info nennt den gültigen
Ordner.
| Taste in k9s | Wirkung | Merkhilfe |
|---|---|---|
: + pods, deploy,
ctx |
Ressource/Kontext wählen | wie vim-Befehl |
/ |
filtern | wie less |
l / d / s |
Logs / describe / Shell | logs, describe, shell |
Ctrl-d |
löschen (mit Rückfrage) | in readOnly gesperrt |
Fortschritt speichern? Kostenlos registrieren
Drill 9: Feedback-Schleifen – entr, watch, hyperfine
entr führt einen Befehl aus, sobald sich eine der
übergebenen Dateien ändert. -c leert vorher den
Bildschirm.
fd -e go | entr -c go test ./...
fd -e sh . scripts | entr -c shellcheck /_Warum /_? Platzhalter für die zuletzt geänderte Datei.
Beenden mit q oder Ctrl-c.
watch wiederholt einen Befehl im Intervall. Ohne
watch geht es mit einer Schleife:
watch -n 2 'kubectl get pods'
while sleep 2; do clear; date; kubectl config current-context; donehyperfine misst, statt zu raten. Was kostet die
Completion aus Drill 6 beim Shell-Start?
D=~/term-lab/zcompdump-test
hyperfine -N --warmup 3 \
"zsh -fc 'autoload -Uz compinit; compinit -d $D'" \
"zsh -fc 'autoload -Uz compinit; compinit -d $D; source <(kubectl completion zsh)'"
rm -f $DErwartet (gekürzt, Zeiten hängen von deinem Mac ab):
Benchmark 1: zsh -fc 'autoload -Uz compinit; compinit -d …' (15 runs)
Wall Time 22.7 ms ± 0.6 ms 21.8 ms … 23.7 ms
Benchmark 2: zsh -fc 'autoload -Uz compinit; compinit -d …; source <(kubectl …
Wall Time 48.8 ms ± 3.9 ms 44.9 ms … 59.1 ms +115.5% (2.2x slower)
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
#!/usr/bin/env bash
cd ~/term-lab/projekt && eval "$(direnv export bash 2>/dev/null)"
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
direnv status --json | jq -e '.state.foundRC.allowed == 0' >/dev/null \
&& ok ".envrc freigegeben" || nok ".envrc freigegeben"
git check-ignore -q .env.local \
&& ok ".env.local ignoriert" || nok ".env.local ignoriert"
grep -q '^go = ' mise.toml && ok "mise: Go gepinnt" || nok "mise: Go gepinnt"
[[ $KUBECONFIG == "$HOME/term-lab/kube/config" ]] \
&& ok "Lab-kubeconfig aktiv" || nok "Lab-kubeconfig aktiv"
[[ $(kubectl config get-contexts -o name | wc -l) -ge 3 ]] \
&& ok "mind. 3 Lab-Kontexte" || nok "mind. 3 Lab-Kontexte"
[[ $(kubectl config current-context) != *prod* ]] \
&& ok "nicht auf prod" || nok "nicht auf prod"
shellcheck scripts/*.sh && ok "Skripte shellcheck-sauber" || nok "shellcheck"
make -s help | grep -q report && ok "make help" || nok "make help"Erwartet:
✔ .envrc freigegeben
✔ .env.local ignoriert
✔ mise: Go gepinnt
✔ Lab-kubeconfig aktiv
✔ 3 Lab-Kontexte
✔ nicht auf prod
✔ Skripte shellcheck-sauber
✔ make help
Challenge
Erweitere den Prod-Wächter: Auch kubectl exec soll auf
*prod* nachfragen. Für Skripte, die bewusst auf Prod
laufen, schaltet KUBECTL_PROD_OK=1 die Rückfrage ab.
Hinweis: Eine leere Variable prüfst du in zsh mit
-z ${VAR:-} – das bleibt auch mit set -u
sicher.
Lösung
In ~/term-lab/config/zsh/k8s.zsh die Bedingung ersetzen,
dann exec zsh:
if [[ $ctx == *prod* && -z ${KUBECTL_PROD_OK:-} \
&& $verb == (apply|create|delete|edit|exec|patch|replace\
|scale|rollout|drain|cordon|label|annotate|set) ]]; thenkubectx kunde-prod >/dev/null
k exec web-1 -- id; echo "rc=$?"
KUBECTL_PROD_OK=1 k delete pod web-1 --request-timeout=2s
kubectx kind-lab >/dev/nullErwartet (beim ersten Befehl n tippen):
ACHTUNG: kubectl exec auf Kontext 'kunde-prod'
Wirklich ausführen? [y/N] n
rc=1
Unable to connect to the server: dial tcp: lookup prod.k8s.kunde.example: no such host
Aufräumen nach dem Tag: rm -f ~/term-lab/unsicher.sh.
Die Lab-kubeconfig und mise.toml brauchst du an Tag 15
noch.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Eine kubeconfig pro Kunde/Projekt (per direnv), nie alle Cluster in
~/.kube/config. Prod-Zugänge mit kurzlebigen Tokens (OIDC,kubelogin), nicht mit statischen Tokens. - Der Shell-Wächter ist Komfort, keine Sicherheit: Echte Grenzen ziehen RBAC (Prod nur lesend für Menschen), Admission Policies und GitOps (Änderungen nur per Merge Request).
.envrcim Team einchecken, Secrets daraus nur über Vault/OpenBao, 1Password oder SOPS holen.direnv allownach jedem Pull bewusst bestätigen.mise.toml(oder.tool-versions) ist die eine Quelle für Versionen – lokal und in CI (jdx/mise-action).shellcheckals Pre-Commit-Hook und CI-Schritt. Skripte ohneset -euo pipefailgehen nicht durchs Review.