kubectl-Wrapper-Skripte für den Alltag

1. Warum ein kubectl-Wrapper den Alltag spuerbar erleichtert

Ein kubectl-Wrapper ist im Kern eine Sammlung von Bash-Funktionen, die häufig benötigte kubectl-Aufrufe kapseln, Standardwerte setzen und riskante Aktionen zusätzlich absichern. Ohne solche Wrapper tippt jeder im Team dieselben langen Befehle wie kubectl get pods -n staging -l app=checkout -o wide mehrfach am Tag, kopiert Pod-Namen aus einer Liste heraus und wechselt Namespaces per kubectl config set-context, was auf Dauer fehleranfällig und langsam ist.

Der eigentliche Wert eines kubectl-Wrappers liegt nicht in der reinen Zeitersparnis, sondern in der Reduktion von Fehlerklassen: Wer im falschen Namespace ein Deployment skaliert oder in Produktion versehentlich einen Pod löscht, der eigentlich im Staging-Cluster gemeint war, verursacht einen Incident, der sich mit einem guten kubectl-Wrapper von vornherein vermeiden lässt. Ein Wrapper zeigt beispielsweise den aktiven Kontext farblich hervorgehoben im Prompt an oder verlangt eine explizite Bestätigung, sobald ein Befehl den Namespace production betrifft.

Die folgenden Abschnitte bauen einen praxistauglichen kubectl-Wrapper Schritt für Schritt auf: von Kontext-Switching über Fuzzy-Auswahl bei exec und logs bis zu Guards, die kritische Befehle in Produktion abfangen, bevor sie ausgeführt werden.

2. Kontext- und Namespace-Switching mit fzf automatisieren

Der häufigste Reibungspunkt im Kubernetes-Alltag ist der Wechsel zwischen Clustern und Namespaces. kubectl config use-context gefolgt vom vollständigen Kontextnamen ist umständlich, besonders wenn Kontextnamen wie arn:aws:eks:eu-central-1:123456789012:cluster/prod-eu lauten. Ein kubectl-Wrapper mit fzf als interaktivem Fuzzy-Finder macht daraus eine Zwei-Tasten-Aktion: Funktion aufrufen, aus der Liste tippen, Enter drücken.

Wichtig für diesen Teil des kubectl-Wrappers ist die visuelle Rückmeldung: Nach jedem Kontextwechsel sollte der aktive Namespace und Cluster-Name im Terminal-Prompt sichtbar sein, damit niemand versehentlich einen Befehl im falschen Cluster ausführt, weil der letzte Wechsel schon eine Stunde zurückliegt und vergessen wurde.

#!/usr/bin/env bash
# kctx-helpers.sh — source this from .bashrc for interactive context/namespace switching
set -uo pipefail

# kctx — fuzzy-select a Kubernetes context
kctx() {
  local ctx
  ctx="$(kubectl config get-contexts -o name | fzf --prompt="Context> " --height=40%)" || return 0
  kubectl config use-context "$ctx"
  echo "[OK] Switched to context: ${ctx}"
}

# kns — fuzzy-select a namespace within the current context
kns() {
  local ns
  ns="$(kubectl get namespaces -o jsonpath='{.items[*].metadata.name}' | tr ' ' '\n' | fzf --prompt="Namespace> " --height=40%)" || return 0
  kubectl config set-context --current --namespace="$ns"
  echo "[OK] Namespace set to: ${ns}"
}

# k8s_prompt — shows active context + namespace, add to PS1
k8s_prompt() {
  local ctx ns
  ctx="$(kubectl config current-context 2>/dev/null)" || { echo ""; return; }
  ns="$(kubectl config view --minify -o jsonpath='{..namespace}' 2>/dev/null)"
  echo "[k8s:${ctx}/${ns:-default}]"
}

export PS1='$(k8s_prompt) \u@\h:\w\$ '

Dieser Teil des kubectl-Wrappers wird meist einmalig in .bashrc oder .zshrc eingebunden. Der Prompt-Indikator k8s_prompt ist bewusst defensiv geschrieben: Falls kubectl nicht erreichbar ist oder kein Kontext gesetzt ist, gibt die Funktion eine leere Zeichenkette zurück, statt die Shell mit einer Fehlermeldung zu blockieren.

3. Fuzzy-Auswahl fuer kubectl exec und kubectl logs

Der zweitgrößte Zeitfresser im Alltag ist das Heraussuchen des korrekten Pod-Namens für kubectl exec oder kubectl logs, besonders bei Deployments mit mehreren Replikas und generierten Suffixen wie checkout-7d9f8b6c5-x2p4k. Ein kubectl-Wrapper für diese beiden Befehle nimmt stattdessen ein Label oder einen Teilstring als Filter entgegen, zeigt die passenden Pods in fzf an und öffnet direkt die Shell oder den Log-Stream im ausgewählten Pod.

Bei Deployments mit mehreren Containern pro Pod, etwa mit einem Sidecar für Logging oder Service Mesh, muss der kubectl-Wrapper zusätzlich den Container-Namen abfragen, sonst schlägt exec fehl oder landet im falschen Container. Die folgende Funktion behandelt beide Fälle.

#!/usr/bin/env bash
# kexec-klogs.sh — fuzzy pod selection for exec and logs
set -uo pipefail

_select_pod() {
  local filter="${1:-}"
  kubectl get pods --no-headers -o custom-columns=":metadata.name" \
    | grep -i -- "$filter" \
    | fzf --prompt="Pod> " --height=40%
}

# kexec <filter> — fuzzy-select a pod, then open an interactive shell
kexec() {
  local pod container
  pod="$(_select_pod "${1:-}")" || return 0
  [[ -z "$pod" ]] && { echo "[INFO] No pod selected"; return 0; }

  local containers
  containers="$(kubectl get pod "$pod" -o jsonpath='{.spec.containers[*].name}')"
  if [[ "$containers" == *" "* ]]; then
    container="$(tr ' ' '\n' <<< "$containers" | fzf --prompt="Container> ")"
  else
    container="$containers"
  fi

  echo "[INFO] Executing into ${pod}/${container}"
  kubectl exec -it "$pod" -c "$container" -- /bin/sh
}

# klogs <filter> [-- extra kubectl logs args] — fuzzy-select a pod, then follow logs
klogs() {
  local pod
  pod="$(_select_pod "${1:-}")" || return 0
  [[ -z "$pod" ]] && { echo "[INFO] No pod selected"; return 0; }
  shift || true
  kubectl logs -f "$pod" "$@"
}

4. Rollout-Status und Deployment-Diagnose per Funktion

Nach jedem Deployment stellt sich dieselbe Frage: Läuft der Rollout durch, oder hängt ein Pod im CrashLoopBackOff? Statt manuell zwischen kubectl rollout status, kubectl get pods und kubectl describe pod zu wechseln, bündelt ein kubectl-Wrapper diese drei Schritte in einer einzigen Diagnosefunktion, die bei Problemen automatisch die relevanten Events und die letzten Log-Zeilen des fehlerhaften Containers anzeigt.

Diese Diagnosefunktion ist besonders wertvoll während eines Incidents, wenn Zeit zählt: Statt fünf Befehle nacheinander abzutippen, liefert der kubectl-Wrapper auf einen Blick, ob das Problem am Image, an Ressourcen-Limits oder an einem fehlgeschlagenen Health-Check liegt.

#!/usr/bin/env bash
# krollout.sh — combined rollout status and failure diagnosis
set -uo pipefail

krollout() {
  local deployment="${1:?Usage: krollout <deployment>}"
  local ns
  ns="$(kubectl config view --minify -o jsonpath='{..namespace}')"

  echo "[INFO] Watching rollout of ${deployment} in namespace ${ns:-default}"
  if kubectl rollout status "deployment/${deployment}" --timeout=90s; then
    echo "[OK] Rollout completed successfully"
    return 0
  fi

  echo "[WARN] Rollout did not complete — collecting diagnostics"
  local bad_pod
  bad_pod="$(kubectl get pods -l "app=${deployment}" \
    --field-selector=status.phase!=Running -o jsonpath='{.items[0].metadata.name}' 2>/dev/null)"

  if [[ -n "$bad_pod" ]]; then
    echo "--- Events for ${bad_pod} ---"
    kubectl describe pod "$bad_pod" | grep -A 20 "Events:"
    echo "--- Last 30 log lines for ${bad_pod} ---"
    kubectl logs --tail=30 "$bad_pod" || echo "[WARN] Could not fetch logs"
  else
    echo "[WARN] No unhealthy pod found via label selector app=${deployment}"
  fi
  return 1
}

5. Produktions-Guards: Bestaetigung vor kritischen Befehlen

Der wichtigste Sicherheitsaspekt eines kubectl-Wrappers ist der Schutz vor destruktiven Befehlen im Produktions-Namespace. kubectl delete, kubectl scale --replicas=0 und kubectl rollout restart sind in der Praxis die drei Befehle, die bei versehentlicher Ausführung im falschen Kontext den größten Schaden anrichten. Ein kubectl-Wrapper prüft vor der Ausführung, ob der aktuelle Kontext einen Produktions-Namen enthält, und verlangt in diesem Fall eine explizite Bestätigung durch Eintippen des Namespace-Namens, ähnlich wie es viele Cloud-Konsolen bei destruktiven Aktionen tun.

Diese Guard-Funktion ersetzt kubectl nicht vollständig, sondern legt sich als dünne Schicht davor. Wichtig ist, dass sie transparent bleibt: Der Operator sieht weiterhin den exakten kubectl-Befehl, der ausgeführt wird, bekommt aber eine zusätzliche Reibungsfläche, bevor ein produktionskritischer Befehl tatsächlich abgesetzt wird.

#!/usr/bin/env bash
# kguard.sh — require explicit confirmation for destructive commands in prod
set -uo pipefail

readonly PROD_PATTERN="prod"

kguard() {
  local ns
  ns="$(kubectl config view --minify -o jsonpath='{..namespace}')"

  if [[ "$ns" == *"$PROD_PATTERN"* ]]; then
    echo "[WARNING] You are about to run in PRODUCTION namespace: ${ns}"
    echo "Command: kubectl $*"
    read -r -p "Type the namespace name to confirm (${ns}): " confirm
    if [[ "$confirm" != "$ns" ]]; then
      echo "[ABORTED] Namespace confirmation did not match"
      return 1
    fi
  fi

  kubectl "$@"
}

# Usage examples:
# kguard delete pod checkout-7d9f8b6c5-x2p4k
# kguard scale deployment/checkout --replicas=0
# kguard rollout restart deployment/checkout

6. Aufraeumen: Wrapper fuer abgeschlossene Jobs und Evicted Pods

Cluster, in denen regelmäßig Batch-Jobs oder CronJobs laufen, sammeln über Wochen abgeschlossene Job-Pods und evicted Pods an, die zwar keine Ressourcen mehr verbrauchen, aber die Ausgabe von kubectl get pods unübersichtlich machen und im schlimmsten Fall die Object-Count-Quota im Namespace ausschöpfen. Ein kubectl-Wrapper für Cleanup fasst die Löschung dieser Alt-Objekte in einer Funktion zusammen, die vor dem Löschen zunächst eine Vorschau zeigt.

Diese Aufräumfunktion sollte niemals ungefragt in Produktion laufen, deshalb kombiniert sie sich gut mit dem Guard aus dem vorigen Abschnitt: Erst die Liste der Kandidaten anzeigen, dann mit einer expliziten Bestätigung tatsächlich löschen.

#!/usr/bin/env bash
# kcleanup.sh — preview and remove completed jobs / evicted pods
set -euo pipefail

kcleanup() {
  echo "--- Completed Job pods ---"
  local completed
  completed="$(kubectl get pods --field-selector=status.phase=Succeeded -o name)"
  echo "${completed:-<none>}"

  echo "--- Evicted pods ---"
  local evicted
  evicted="$(kubectl get pods -o json | jq -r '.items[] | select(.status.reason=="Evicted") | .metadata.name')"
  echo "${evicted:-<none>}"

  [[ -z "$completed" && -z "$evicted" ]] && { echo "[OK] Nothing to clean up"; return 0; }

  read -r -p "Delete all listed pods above? [yes/NO] " confirm
  [[ "$confirm" == "yes" ]] || { echo "[INFO] Aborted"; return 0; }

  [[ -n "$completed" ]] && kubectl delete $completed
  while read -r pod; do
    [[ -n "$pod" ]] && kubectl delete pod "$pod"
  done <<< "$evicted"

  echo "[OK] Cleanup complete"
}

7. Multi-Cluster-Workflows und Kubeconfig-Merging

Teams mit mehreren Clustern, etwa getrennt nach Umgebung oder Region, verwalten häufig mehrere separate Kubeconfig-Dateien. Ein kubectl-Wrapper kann diese Dateien beim Shell-Start automatisch zu einer einzigen KUBECONFIG-Umgebungsvariable zusammenführen, sodass kctx aus Abschnitt zwei alle verfügbaren Cluster in einer Liste zeigt, statt manuell zwischen Kubeconfig-Dateien zu wechseln.

Für Multi-Cluster-Operationen, etwa das gleichzeitige Prüfen des Rollout-Status in Staging und Produktion, kann ein kubectl-Wrapper auch eine Schleife über mehrere Kontexte bauen und dieselbe Abfrage nacheinander gegen jeden Cluster ausführen, mit klar getrennter Ausgabe pro Kontext.

#!/usr/bin/env bash
# kmulti.sh — merge kubeconfigs and run a command across multiple contexts
set -euo pipefail

# Merge all kubeconfig files in ~/.kube/configs/ into one KUBECONFIG
merge_kubeconfigs() {
  local configs
  configs="$(find ~/.kube/configs -type f -name '*.yaml' -printf '%p:' | sed 's/:$//')"
  export KUBECONFIG="$configs"
  kubectl config view --flatten > ~/.kube/config.merged
  export KUBECONFIG=~/.kube/config.merged
  echo "[OK] Merged $(kubectl config get-contexts -o name | wc -l) contexts"
}

# kall <kubectl-args...> — run the same kubectl command against every context
kall() {
  local ctx
  while read -r ctx; do
    echo "=== ${ctx} ==="
    kubectl --context="$ctx" "$@" || echo "[WARN] Command failed for ${ctx}"
  done < <(kubectl config get-contexts -o name)
}

# Usage: kall get pods -n kube-system

8. Fehlerbehandlung und typische Fallstricke bei kubectl-Wrappern

Ein häufiger Fehler in selbstgebauten kubectl-Wrapper-Funktionen ist das Fehlen von Rückgabewerten bei fehlgeschlagenen kubectl-Aufrufen: Wenn eine Funktion nur die Ausgabe von kubectl weiterreicht, ohne den Exit-Code zu prüfen, meldet ein aufrufendes Skript fälschlich Erfolg. Jeder kubectl-Wrapper, der in Automatisierung eingesetzt wird, sollte explizit set -euo pipefail nutzen und Exit-Codes aus kubectl weiterreichen, nicht nur die Textausgabe.

Ein zweiter Fallstrick betrifft fzf-basierte Funktionen ohne interaktives Terminal, etwa wenn dieselbe Funktion versehentlich in einem CI-Job aufgerufen wird. fzf blockiert dann unbegrenzt auf Eingabe. Ein robuster kubectl-Wrapper prüft mit [[ -t 0 ]], ob stdin ein Terminal ist, und bricht in nicht-interaktiven Kontexten mit einer klaren Fehlermeldung ab, statt die Pipeline hängen zu lassen.

Ein dritter, subtilerer Fehler: Guard-Funktionen, die nur auf den String prod im Namespace-Namen prüfen, übersehen Cluster, bei denen die Produktionsumgebung anders benannt ist, etwa live oder eu-central-1-main. Ein kubectl-Wrapper mit Produktionsschutz sollte die Liste kritischer Namespace-Muster konfigurierbar machen, statt sie hart zu kodieren.

9. Rohes kubectl im Vergleich zu Wrapper-Funktionen

Die folgende Tabelle zeigt, wie sich alltägliche kubectl-Aufgaben mit und ohne kubectl-Wrapper unterscheiden.

In der Summe zeigt die Tabelle: Ein kubectl-Wrapper ersetzt kubectl nicht, sondern legt sich als dünne, sichere Schicht darüber, die genau dort eingreift, wo Tippgeschwindigkeit und Fehleranfälligkeit im Alltag am stärksten aufeinandertreffen.

10. Zusammenfassung

Ein guter kubectl-Wrapper löst zwei Probleme gleichzeitig: Er verkürzt wiederkehrende Befehle wie Kontext-Wechsel, Pod-Auswahl für exec und logs sowie Rollout-Diagnose auf wenige Tastendrücke, und er baut Sicherheitsnetze für die riskantesten Aktionen im Produktions-Namespace ein. Fuzzy-Finder wie fzf ersetzen manuelles Copy-Paste von Pod-Namen, ein Guard mit Namespace-Bestätigung verhindert versehentliche Löschungen, und eine kombinierte Diagnosefunktion liefert während eines Incidents in Sekunden das, wofür sonst drei bis fünf einzelne Befehle nötig wären.

Der zusätzliche Aufwand für einen sauberen kubectl-Wrapper zahlt sich vor allem in Teams aus, in denen mehrere Personen dieselben Cluster bedienen: Einheitliche Funktionen sorgen dafür, dass jeder dieselben Sicherheitsnetze nutzt, unabhängig davon, wie erfahren die einzelne Person mit Kubernetes ist. Wer diese Funktionen in ein gemeinsames Dotfiles-Repository auslagert, verteilt Verbesserungen automatisch an das ganze Team.

11. FAQ: kubectl-Wrapper-Skripte für den Alltag