kubectl ist die Kommandozeilen-Oberfläche der Kubernetes-API. Es ist nicht das ganze System — Controller, Scheduler und Kubelets leisten die eigentliche Arbeit — aber hier verbringen die meisten Einsteiger die ersten hundert Stunden. Das Tool wirkt überwältigend, weil es fast alles exponiert. Die gute Nachricht: ein kleiner Satz Verben und Flags deckt den größten Teil von Lernen und Debugging ab.

Dieser Beitrag ist ein praktisches Starter-Kit: was zuerst ausführen, was die Ausgabe grob bedeutet und eine ruhige Reihenfolge, wenn etwas hakt. Kein Versuch, jedes Subkommando zu listen.

Wie kubectl mit dem Cluster spricht

Bei kubectl lädt der Client Konfiguration aus der kubeconfig (meist ~/.kube/config). Dort stehen Cluster (API-Adressen), User (Credentials) und Kontexte (Cluster + User + optional Standard-Namespace).

Wer auf dem falschen Cluster schaut, bekommt bei jedem korrekten Befehl nutzlose Antworten.

kubectl config current-context
kubectl config get-contexts
kubectl cluster-info

current-context ist die eine Zeile, die lohnt, wenn Ergebnisse keinen Sinn ergeben. get-contexts markiert den aktiven Kontext mit *. cluster-info bestätigt, dass die API erreichbar ist — nicht dass die App gesund ist, aber dass man mit etwas Realem spricht.

Kontext wechseln bei Bedarf:

kubectl config use-context kind-my-cluster

Kontextwechsel wie Flughafenwechsel behandeln. Die Abläufe sehen ähnlich aus; die Maschinen sind andere.

Namespaces: der Scope, den man vergisst

Kubernetes teilt Objekte in Namespaces. Viele Tutorials nutzen default. Echte Teams nutzen staging, production, App-Namen oder Plattform-Namespaces.

Ohne -n nutzt kubectl den Standard-Namespace des Kontexts, oder default, wenn nichts gesetzt ist.

kubectl get namespaces
kubectl get pods -n shop-staging
kubectl config set-context --current --namespace=shop-staging

Namespace am Kontext spart Tippen in einer fokussierten Session. Beim Incident-Debugging bevorzuge ich weiterhin explizites -n bei wichtigen Befehlen, damit Copy-Paste aus Runbooks nicht am falschen Ort landet.

get: der Cockpit-Überblick

kubectl get listet Ressourcen in einer kompakten Tabelle. Es beantwortet: was existiert, und wie lautet die Status-Schlagzeile?

kubectl get pods -n shop-staging
kubectl get deploy,svc -n shop-staging
kubectl get all -n shop-staging

all ist ein Convenience-Bündel (Pods, Services, Deployments, ReplicaSets, …). Es ist nicht wörtlich jeder Ressourcentyp — CronJobs, Ingresses und vieles andere brauchen explizite Typen.

Nützliche Output-Flags:

kubectl get pods -n shop-staging -o wide
kubectl get pods -n shop-staging --show-labels
kubectl get pods -n shop-staging -w
  • -o wide ergänzt Node und Pod-IP — hilfreich, wenn Pods auf einem problematischen Node landen oder beim Abgleich mit Service-Endpunkten.
  • --show-labels zeigt Labels für Selektoren — wesentlich, wenn ein Service keine Endpunkte hat.
  • -w beobachtet Änderungen — nützlich bei Rollouts.

Weitere Formate (-o yaml, -o json) kommen später. Für Einsteiger reichen Tabellen plus describe meist aus.

describe: die Geschichte hinter der Schlagzeile

kubectl describe holt Details und Events — kurze Meldungen von Kubernetes-Komponenten darüber, was passiert ist.

Zeigt get CrashLoopBackOff, Pending oder ImagePullBackOff, ist describe der nächste Schritt.

kubectl describe pod web-7d4f8c9b6-xk2jp -n shop-staging
kubectl describe deployment web -n shop-staging
kubectl describe svc api -n shop-staging

Beim Pod lohnen:

  • Conditions — geplant? ready?
  • Containers — Zustand, Restart-Count, letzter Terminierungsgrund.
  • Events unten — oft der klarste Hinweis (Pull fehlgeschlagen, Quota, Probe).

Beim Deployment Replika-Zahlen, Conditions und Events zum Rollout.

Beim Service Selector und ob Endpunkte existieren. Laufende App ohne Endpunkte ist oft Label-Mismatch.

Häufiger Anfängerfehler: nur die STATUS-Spalte von get lesen. Das ist eine Zusammenfassung. describe ist der Artikel.

logs: Anwendungsausgabe, nicht Kubernetes-Meinung

Sobald der Container mindestens einmal gestartet hat, helfen Anwendungslogs.

kubectl logs deployment/web -n shop-staging
kubectl logs pod web-7d4f8c9b6-xk2jp -n shop-staging -c web
kubectl logs deployment/web -n shop-staging --previous
  • deployment/web wählt einen Pod des Deployments (praktisch, wenn Replikat-Namen wechseln).
  • -c benennt den Container bei mehreren Containern im Pod.
  • --previous zeigt die letzte abgestürzte Instanz — wertvoll bei CrashLoopBackOff.

Live mitführen:

kubectl logs -f deployment/web -n shop-staging

Logs sagen, was der Prozess meldete. Sie ersetzen nicht describe bei Scheduling- oder Image-Pull-Fehlern — die erreichen oft nie Anwendungslogs.

apply und delete: gewünschten Zustand ändern

kubectl apply -f erstellt oder aktualisiert Objekte aus YAML oder Verzeichnissen. Das ist der übliche Einstieg für Manifest- und GitOps-Workflows.

kubectl apply -f k8s/web/ -n shop-staging
kubectl apply -f deployment.yaml -n shop-staging
kubectl delete -f deployment.yaml -n shop-staging
kubectl delete pod web-7d4f8c9b6-xk2jp -n shop-staging

Apply sendet gewünschten Zustand an die API. Controller gleichen ab. Delete entfernt Objekte; Pods eines ReplicaSets werden oft neu erstellt, außer man löscht den Controller oder skaliert auf null.

Pod löschen zum „Neustart“ funktioniert manchmal, ist aber eine grobe Gewohnheit. Besser Rollouts:

kubectl rollout restart deployment/web -n shop-staging
kubectl rollout status deployment/web -n shop-staging
kubectl rollout history deployment/web -n shop-staging

rollout status blockiert bis Erfolg oder Timeout — gut nach apply in Skripten oder beim Lernen.

explain: Dokumentation im Terminal

YAML-Feldnamen raten ist langsam. kubectl explain geht durch das API-Schema.

kubectl explain pod
kubectl explain pod.spec
kubectl explain pod.spec.containers
kubectl explain deployment.spec.strategy
kubectl explain service.spec.ports

Mit --recursive ein tieferer Baum auf einmal:

kubectl explain deployment.spec.template.spec --recursive

So bleibt man bei dem, was die API akzeptiert. Kubernetes-Versionen ändern Felder; explain spiegelt den verbundenen Cluster.

dry-run: üben ohne Folgen

Client-side dry-run baut das Objekt lokal ohne Server (älterer Stil, noch in Docs).

Server-side dry-run lässt die API Admission prüfen ohne Persistenz — näher an „wird das akzeptiert?“

kubectl apply -f deployment.yaml --dry-run=server -n shop-staging
kubectl create deployment demo --image=nginx --dry-run=server -o yaml

YAML aus imperativen Befehlen erzeugen ist ein legitimer Lernpfad:

kubectl create deployment web --image=ghcr.io/example/web:1.0.0 \
  --dry-run=client -o yaml > deployment.yaml

Dann Datei bearbeiten, Labels, Probes und Resources ergänzen und für die echte Änderung zu apply wechseln.

Labels, Selektoren und Field Selectors

Labels verbinden Deployments mit Pods und Services mit Pods.

kubectl get pods -n shop-staging -l app=web
kubectl get pods -n shop-staging --field-selector status.phase=Pending

Zielt ein Service auf app=web, Pods haben aber app=web-app, ist get endpoints leer. Labels sind Verdrahtung, keine Dekoration.

Eine ruhige Debugging-Reihenfolge

Bei Problemen kommt Geschwindigkeit oft aus der Reihenfolge, nicht aus mehr zufälligen Befehlen.

1. Kontext und Namespace bestätigen.

kubectl config current-context
kubectl get ns
kubectl get deploy,pod,svc -n shop-staging

2. Controller identifizieren. Deployment? StatefulSet? Job?

3. Workload-Schlagzeile lesen.

kubectl get deploy web -n shop-staging
kubectl rollout status deployment/web -n shop-staging

4. Pods inspizieren.

kubectl get pods -n shop-staging -l app=web -o wide
kubectl describe pod <name> -n shop-staging

5. Netzwerk erst prüfen, wenn Pods Ready sind.

kubectl get svc api -n shop-staging
kubectl get endpoints api -n shop-staging

6. Logs zuletzt unter den kubectl-Basics — nachdem klar ist, dass der Container startete.

kubectl logs deployment/web -n shop-staging --tail=100

Direkt zu Logs bei ImagePullBackOff verschwendet Zeit. describe bei Pending überspringen verpasst Events zu Quota oder Scheduling.

Impersonation und Auth-Fehler (kurz)

Schlagen Befehle mit forbidden oder unauthorized fehl, liegt es an Credentials oder RBAC — nicht am Deployment-Manifest.

kubectl auth can-i get pods -n shop-staging
kubectl auth can-i create deployments -n shop-staging

Das behebt keine Rechte, klärt aber, ob Policy statt Anwendungscode blockiert.

Kleine Gewohnheiten, die sich summieren

  • Explizite Namespaces in Runbooks und Incidents.
  • -o wide, wenn Node-Platzierung zählt.
  • --show-labels, wenn Services und Deployments nicht zusammenpassen.
  • explain statt dreijährigem YAML aus Foren.
  • --dry-run=server vor unbekannten Manifesten in Produktion.
  • rollout restart statt Pods löschen, wenn ein Deployment gehört.

Was als Nächstes (ohne Hetze)

Später lohnen: kubectl port-forward für lokalen Zugriff, kubectl exec für Shells (wenn gerechtfertigt), kubectl top für Ressourcennutzung (Metrics Server nötig), kubectl api-resources für unterstützte Typen, kubectl get events nach Zeit für Namespace-Zeitstrahlen.

Nichts ersetzt die Kernschleife: get → describe → logs, mit zuerst bestätigtem Kontext und Namespace.

Abschluss

kubectl ist nicht Kubernetes — es ist ein Client. Trotzdem macht Beherrschung weniger Verben die API greifbar. Einsteiger, die stetig vorankommen, haben selten jedes Flag auswendig gelernt. Sie prüfen, wo sie verbunden sind, lesen Events vor blindem Neustart und behandeln Labels als Teil der Debug-Geschichte. Diese Reihenfolge früh aufbauen; der Rest der Oberfläche lässt sich gezielt ergänzen statt aus Versehen.