Zum Inhalt springen
Trainingslager IT-Trainingslager

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 cd ins Projekt Variablen aus .envrc und 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 help statt 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, trap und shellcheck. entr, watch und hyperfine schließen die Feedback-Schleife.
  • Alles läuft in ~/term-lab/projekt und mit einer Lab-kubeconfig mit erfundenen Kontexten. Deine echte ~/.kube/config bleibt 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' >> .gitignore

Erwartet:

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 projekt

Erwartet:

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: .envrc kommt ins Repo, .env.local mit Secrets nie. Besser noch: Secrets zur Laufzeit holen, etwa export 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.toml

Erwartet (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 Datei mise use ändert. Steht dort deine globale ~/.config/mise/config.toml, erzwingst du die Projektdatei mit mise 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-80

Erwartet (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 lint

Erwartet:

  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.log

Erwartet (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 der mise.toml dasselbe – 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-contexts

Erwartet:

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 -c

Erwartet:

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}'; echo

Erwartet:

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 kubectx und kubens einen Fuzzy-Picker (Tag 7). kubectx merkt 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 kgp

Erwartet:

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-lab

Erwartet:

✔ 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: einmal kubectl completion zsh > ~/term-lab/zsh/completions/_kubectl und das Verzeichnis vor compinit in fpath aufnehmen.

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/null

Erwartet (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/null

Erwartet (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
EOF

Ohne 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; done

hyperfine 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 $D

Erwartet (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) ]]; then
kubectx 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/null

Erwartet (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).
  • .envrc im Team einchecken, Secrets daraus nur über Vault/OpenBao, 1Password oder SOPS holen. direnv allow nach jedem Pull bewusst bestätigen.
  • mise.toml (oder .tool-versions) ist die eine Quelle für Versionen – lokal und in CI (jdx/mise-action).
  • shellcheck als Pre-Commit-Hook und CI-Schritt. Skripte ohne set -euo pipefail gehen nicht durchs Review.