kubectl Befehle: die wichtigsten im Alltag

Die kubectl Befehle, die du im Alltag wirklich brauchst, passen auf eine Handvoll Verben: get und describe zum Anschauen, logs und exec zum Debuggen, port-forward zum Testen, apply und delete zum Ändern. Wer diese sieben sicher beherrscht und weiß, wie er Kontext und Namespace wechselt, erledigt damit den größten Teil seiner täglichen Arbeit mit Kubernetes. Alles andere ist Nachschlagen.

Sortiert ist hier nach Situationen statt alphabetisch, mit echten Ausgaben und den Stolperfallen, in die ich selbst gelaufen bin. Am Ende kommen das Kubernetes Dashboard und Lens dazu, für die Fälle, in denen eine Oberfläche schneller ist als das Terminal.

Ich arbeite seit Jahren täglich mit kubectl, betreibe Kubernetes-Cluster in Produktion und habe das Kubernetes-Praxisbuch bei Rheinwerk geschrieben (2024). Alle meine Beiträge zum Thema findest du gesammelt auf der Seite Kubernetes.

Wie ein kubectl Befehl aufgebaut ist

Jeder Befehl folgt demselben Muster: kubectl <Verb> <Ressource> <Name> <Optionen>. Das Verb sagt, was du tun willst (get, describe, delete), die Ressource sagt, womit (pods, deployments, services), der Name grenzt auf ein Objekt ein, und die Optionen steuern Details wie Namespace oder Ausgabeformat. Was du nicht auswendig weißt, verrät dir kubectl selbst: kubectl --help listet alle Verben, kubectl create --help zeigt Beispiele, und kubectl create namespace --help sagt dir, dass nur noch ein Name fehlt. Diese eingebaute Hilfe nutze ich bis heute häufiger als jede Suchmaschine.

kubectl spricht mit dem kube-apiserver deines Clusters. Welcher Cluster das ist und wie sich kubectl dort anmeldet, steht in der Kubeconfig unter ~/.kube/config. Bei einem lokalen Cluster mit Minikube oder kind ist die Datei schon geschrieben; wie so ein Cluster entsteht, steht in Kubernetes lokal: Cluster auf dem Rechner. Im Unternehmen bekommst du sie von den Cluster-Admins. Behandle sie wie ein Passwort: Sie enthält die Zugangsdaten für den Cluster, oft als eingebettetes Zertifikat, und wer die Datei hat, hat den Cluster.

Zwei Kleinigkeiten sparen jeden Tag Zeit: ein Alias alias k=kubectl und die Autovervollständigung, die kubectl für Bash, Zsh, Fish und PowerShell mitbringt:

echo 'source <(kubectl completion zsh)' >> ~/.zshrc

Nach einem Neustart der Shell vervollständigt die Tab-Taste auch die Namen deiner Pods. Bei generierten Namen wie nginx-748c667d99-xtljp ist das der Unterschied zwischen Tippen und Arbeiten.

Kontext und Namespace sicher wechseln

Die meisten Fehler, die ich mit kubectl gesehen habe, waren keine falschen Befehle, sondern richtige Befehle im falschen Cluster oder Namespace. Deshalb gehört das Wechseln an den Anfang.

Ein Kontext in der Kubeconfig verbindet einen Cluster, einen Benutzer und einen Standard-Namespace. kubectl config get-contexts zeigt alle Kontexte und den aktiven, kubectl config use-context <name> wechselt. Wenn du dir das -n bei jedem Befehl sparen willst, setzt du den Namespace dauerhaft für den aktuellen Kontext:

kubectl config set-context --current --namespace=my-k8s

Namespaces sind abgetrennte Bereiche im Cluster, in denen Namen eindeutig sein müssen und für die du Rechte und Quoten vergeben kannst. Ein frischer Cluster bringt vier davon mit: default, kube-system, kube-public und kube-node-lease. Den default-Namespace nutze ich nur für schnelle Tests; jede echte Anwendung bekommt bei mir ihren eigenen. Mit -A siehst du Ressourcen über alle Namespaces hinweg, wenn du nicht weißt, wo etwas läuft.

Für den Alltag mit mehreren Clustern empfehle ich die kleinen Werkzeuge kubectx und kubens: kubectx prod wechselt den Cluster, kubens my-k8s den Namespace, beides mit Tab-Vervollständigung. Dazu eine Angewohnheit aus meinen Projekten: vor jedem delete oder apply in Produktion einmal kubectl config current-context tippen. Das kostet zwei Sekunden und hat mich mehr als einmal gerettet.

Die wichtigsten kubectl Befehle in einer Tabelle

Diese Liste deckt bei mir den Großteil aller Tage ab. Alles, was hier nicht steht, schlage ich nach.

Befehl	Was er tut	Typische Optionen
kubectl get pods	Zeigt Pods im aktuellen Namespace mit Status und Restarts	-A, -o wide, -o yaml, -w
kubectl describe pod <name>	Details, Zustand und Events eines Objekts	funktioniert für jede Ressource
kubectl logs <pod>	Gibt die Logs eines Containers aus	-f, --previous, -c, --since=10m
kubectl exec -it <pod> -- sh	Öffnet eine Shell oder führt einen Befehl im Container aus	-c <container>
kubectl port-forward pod/<pod> 8080:80	Tunnel vom Rechner zum Pod oder Service	svc/<name> statt pod/<name>
kubectl apply -f <datei>	Legt an oder aktualisiert aus einem Manifest	-f <ordner>, --dry-run=server
kubectl delete -f <datei>	Löscht, was im Manifest steht	-l app=nginx, --force mit Vorsicht
kubectl create deployment nginx --image=nginx	Erzeugt schnell ein Objekt ohne Manifest	--dry-run=client -o yaml als Vorlage
kubectl rollout status deployment/<name>	Wartet, bis ein Rollout fertig ist	rollout undo, rollout history
kubectl scale deployment/<name> --replicas=3	Ändert die Anzahl der Pods
kubectl get events --sort-by=.lastTimestamp	Chronik dessen, was im Namespace passiert ist	-A
kubectl api-resources	Listet alle Ressourcentypen und ihre Kurzformen	--namespaced=false
kubectl explain pod.spec.containers	Dokumentation eines Felds direkt im Terminal
kubectl config current-context	Zeigt, mit welchem Cluster du gerade sprichst	use-context, get-contexts

Anschauen und verstehen: kubectl get und describe

kubectl get ist der Befehl, den du am häufigsten tippst. Er zeigt dir, was im Cluster existiert und in welchem Zustand es ist. Für die System-Komponenten eines Minikube-Clusters sieht das etwa so aus:

kubectl get pods -n kube-system

NAME                               READY   STATUS    RESTARTS   AGE
coredns-787d4945fb-qcsvv           1/1     Running   0          8d
etcd-minikube                      1/1     Running   0          8d
kube-apiserver-minikube            1/1     Running   0          8d
kube-proxy-42gdl                   1/1     Running   0          8d
kube-scheduler-minikube            1/1     Running   0          8d
storage-provisioner                1/1     Running   0          8d

Die Spalten READY und RESTARTS sind die wichtigsten. 0/1 bei READY heißt, der Container läuft nicht oder ist nicht bereit; eine steigende Zahl bei RESTARTS heißt, er stürzt regelmäßig ab. Mit -o wide bekommst du zusätzlich Node und Pod-IP, mit -o yaml das komplette Objekt so, wie es im Cluster liegt, und mit -w bleibt der Befehl offen und zeigt Änderungen live an.

kubectl describe ist der nächste Schritt, sobald etwas nicht stimmt. Er fasst Konfiguration, Zustand und vor allem die Events eines Objekts zusammen. Ob ein Image nicht gezogen werden konnte, eine Node keinen Platz hatte oder eine Probe fehlschlägt, steht im unteren Teil der Ausgabe. Was die Felder eines Pods bedeuten, erkläre ich in Kubernetes Pod: was ist ein Pod?.

Welche Ressourcentypen es gibt, zeigt kubectl api-resources, inklusive Kurzformen (po, deploy, svc) und der Angabe, ob eine Ressource an einen Namespace gebunden ist. Ein Pod ist es, ein Persistent Volume oder eine Node nicht; deshalb brauchst du bei den einen das -n und bei den anderen nicht.

kubectl logs: was der Container erzählt

Logs sind in Kubernetes das, was der Container auf die Standardausgabe schreibt. kubectl logs <pod> gibt sie aus, -f folgt ihnen live wie tail -f. Läuft mehr als ein Container im Pod, wählst du ihn mit -c <name>, oder du nimmst --all-containers=true.

Die Option, die ich Einsteigern am häufigsten zeige, ist --previous. Wenn ein Container abgestürzt ist, hat Kubernetes ihn wahrscheinlich schon neu gestartet, und kubectl logs zeigt dir dann nur die Logs des neuen, noch leeren Containers. Der Grund für den Absturz steht in der vorherigen Instanz:

kubectl logs nginx-748c667d99-9448b --previous

Mit -l app=nginx bekommst du die Logs aller Pods mit diesem Label auf einmal, praktisch bei einem Deployment mit mehreren Replicas. --since=10m und --tail=100 begrenzen die Ausgabe. Für die Suche über viele Pods und längere Zeiträume ist kubectl das falsche Werkzeug; dafür laufen in meinen Clustern Loki und Grafana. Aber für die Frage „warum ist dieser Pod gerade gestorben" ist kubectl logs --previous das Erste, was ich tippe.

kubectl exec und port-forward: in den Container und zum Pod

Manchmal reicht Lesen nicht und du musst in den Container hinein: prüfen, ob eine Konfigurationsdatei angekommen ist, ob DNS funktioniert, welche Umgebungsvariablen gesetzt sind. kubectl exec führt einen Befehl im Container aus. Ohne Shell:

kubectl exec nginx-748c667d99-9448b -- ls /etc/nginx

Mit interaktiver Shell, aus der du mit exit wieder herauskommst:

kubectl exec -it nginx-748c667d99-9448b -- /bin/sh

Die zwei Bindestriche trennen die kubectl-Optionen vom Befehl im Container. Nicht jedes Image hat eine Bash an Bord; /bin/sh funktioniert fast immer. Schlanke Images ohne jede Shell sind der Grund, warum es seit einigen Releases kubectl debug gibt: Der Befehl hängt einen zusätzlichen Container mit Werkzeugen an den laufenden Pod, ohne das Image zu ändern.

kubectl port-forward öffnet einen Tunnel von deinem Rechner zu einem Pod oder Service, ohne dass du einen Ingress oder eine öffentliche Adresse brauchst:

kubectl port-forward svc/nginx 8080:80

Danach erreichst du den Dienst im Browser unter localhost:8080. Ich leite lieber auf den Service als auf einen einzelnen Pod weiter, weil der Service auch nach einem Neustart des Pods noch da ist. Solange der Tunnel steht, ist das Terminal blockiert. Für die Entwicklung ist das ideal, in Produktion nutze ich es nur zum Debuggen und nur, wenn die Cluster-Regeln das erlauben.

Erzeugen, ändern, löschen: apply, create und delete

Für das Anlegen von Ressourcen gibt es zwei Wege. Der imperative Weg sagt Kubernetes, was es tun soll: kubectl create deployment nginx --image=nginx -n my-k8s erzeugt ein Deployment mit einem Nginx-Pod, gut zum Ausprobieren. Der deklarative Weg beschreibt in einer YAML-Datei, wie der Zustand aussehen soll, und kubectl apply -f deployment.yaml sorgt dafür, dass der Cluster diesem Zustand entspricht: Existiert das Objekt noch nicht, wird es angelegt; existiert es, wird es angepasst.

In meinen Projekten läuft praktisch alles über apply, weil die Manifeste damit in Git liegen und jede Änderung nachvollziehbar bleibt. Ein Trick, der beide Welten verbindet: kubectl create mit --dry-run=client -o yaml schreibt dir das Manifest, ohne etwas anzulegen:

kubectl create deployment nginx --image=nginx --dry-run=client -o yaml > deployment.yaml

kubectl replace ersetzt ein Objekt komplett und braucht dafür das vollständige Manifest; ich brauche ihn fast nie, weil apply denselben Zweck schonender erfüllt. Wenn du ein Objekt mit create angelegt hast und später mit apply änderst, warnt kubectl vor der fehlenden last-applied-configuration. Die Warnung ist harmlos, sauberer ist es aber, von Anfang an apply zu nutzen.

kubectl delete löscht, was du ihm nennst: ein Objekt per Name, alles aus einer Datei mit -f, oder mehrere Objekte über ein Label mit -l app=nginx. Ein Pod, der zu einem Deployment gehört, kommt nach dem Löschen sofort wieder, denn das Deployment hält die Anzahl konstant. Die Option --force erzwingt das Löschen eines Pods, der nicht mehr reagiert. Ich setze sie nur ein, wenn ich weiß, warum der Pod hängt, denn sie überspringt das saubere Herunterfahren.

Workflow: ein Pod startet nicht

So gehe ich vor, wenn ein Pod nicht auf Running kommt. Erst kubectl get pods, um den Status zu sehen: Pending, ImagePullBackOff, CrashLoopBackOff oder Error erzählen schon einen Teil der Geschichte. Dann kubectl describe pod <name> und die Events unten lesen: Bei Pending steht dort meist, dass keine Node genug Ressourcen hat; bei ImagePullBackOff, dass das Image oder die Zugangsdaten für die Registry nicht stimmen.

Steht der Pod auf CrashLoopBackOff, startet der Container zwar, stürzt aber immer wieder ab. Dann ist kubectl logs <name> --previous der wichtigste Befehl, denn dort steht die letzte Fehlermeldung der Anwendung. Erst danach lohnt sich kubectl exec, um im Container zu prüfen, ob Konfiguration und Abhängigkeiten da sind. Die ganze Fehlersuche für diesen Fall, inklusive der Rolle von Probes und Ressourcen-Limits, steht in CrashLoopBackOff: Pods richtig debuggen.

Kubernetes Dashboard und Lens: wann eine Oberfläche hilft

Das Kubernetes Dashboard ist die offizielle Weboberfläche des Projekts. Es spricht dieselbe API wie kubectl und zeigt dir pro Namespace Deployments, Pods und Services, dazu Logs, eine Shell in den Container und einen YAML-Editor. Mit Minikube startest du es mit minikube dashboard; in anderen Clustern muss es installiert werden, die Anleitung steht in der Dokumentation zum Kubernetes Dashboard. Für einen ersten Überblick ist es gut, mit mehreren Clustern eher mühsam, weil jeder Cluster eine eigene Webseite und einen eigenen Zugang braucht.

Lens ist ein Desktop-Programm, das die Cluster aus deiner Kubeconfig liest und alle in einer Oberfläche zeigt. Was mich überzeugt hat: Logs und Terminal öffnen sich am unteren Rand, während du weiter durch die Ressourcen navigierst; Port-Forwards laufen im Hintergrund; läuft Prometheus im Cluster, zeigt Lens dessen Metriken an; und Helm-Charts lassen sich direkt aus der Oberfläche installieren. Ein eingebautes Terminal für kubectl gibt es auch.

Zwei ehrliche Einschränkungen. Lens ist heute ein kommerzielles Produkt; prüfe vor dem Einsatz im Unternehmen, welche Lizenzbedingungen für dich gelten. Als offene Alternative gibt es Freelens, einen Fork von OpenLens, das seinerseits aus dem offenen Kern von Lens Desktop hervorgegangen ist. OpenLens selbst wird nicht mehr gepflegt, Freelens führt die offene Linie unter MIT-Lizenz weiter. Und für das Terminal selbst lohnt sich ein Blick auf k9s, eine schnelle Oberfläche direkt in der Konsole.

	kubectl	Kubernetes Dashboard	Lens
Läuft wo	Terminal	Browser, im Cluster installiert	Desktop-Programm
Mehrere Cluster	über Kontexte	je Cluster eine Instanz	alle aus der Kubeconfig
Logs und Shell	logs, exec	ja, im Browser	ja, im Fenster unten
Port-Forward	blockiert das Terminal	nein	im Hintergrund
Skripte und Automatisierung	ja	nein	nein
Kosten	frei	frei	je nach Lizenz

Meine Praxis: kubectl für alles, was ich wiederholen oder in Skripte packen will, und für jede Arbeit in Produktion, weil ich dort jeden Befehl bewusst tippen möchte. Lens oder das Dashboard, wenn ich einen fremden Cluster zum ersten Mal sehe. Die Oberfläche ersetzt die Befehle nicht, sie zeigt dieselben Daten nur anders an.

Häufige Fragen

Wie wechsle ich den Namespace dauerhaft?

Mit kubectl config set-context --current --namespace=<name> schreibst du den Namespace in den aktiven Kontext deiner Kubeconfig. Danach gilt er für jeden Befehl ohne -n. Kürzer geht es mit kubens <name>, das dasselbe tut, aber mit Tab-Vervollständigung über alle vorhandenen Namespaces.

Wie sehe ich die Logs eines abgestürzten Containers?

Mit kubectl logs <pod> --previous. Nach einem Absturz startet Kubernetes den Container neu, und ohne die Option siehst du nur die Logs der neuen Instanz. --previous zeigt die Ausgabe der letzten beendeten Instanz, in der die eigentliche Fehlermeldung steht.

Was ist der Unterschied zwischen kubectl apply und create?

create legt ein Objekt an und schlägt fehl, wenn es schon existiert. apply legt an oder aktualisiert, je nachdem, was im Cluster vorhanden ist, und merkt sich die zuletzt angewendete Konfiguration. Für Manifeste, die in Git liegen und sich ändern, ist apply der richtige Weg; create ist praktisch zum schnellen Ausprobieren.

Wie komme ich in einen laufenden Container?

Mit kubectl exec -it <pod> -- /bin/sh öffnest du eine Shell im Container. Hat der Pod mehrere Container, wählst du mit -c <name> den richtigen. Fehlt dem Image jede Shell, hilft kubectl debug, das einen zusätzlichen Container mit Werkzeugen an den Pod hängt.

Wie lösche ich einen Pod, der in Terminating hängt?

Zuerst mit kubectl describe pod <name> schauen, warum er hängt; oft wartet ein Finalizer oder ein Volume. Wenn die Ursache klar ist, erzwingt kubectl delete pod <name> --force --grace-period=0 das Löschen. Das übergeht das saubere Herunterfahren, deshalb nur, wenn du weißt, was der Pod gerade nicht mehr tun kann.

Wie du weitermachst

Wenn du die Befehle noch nicht an einem eigenen Cluster ausprobiert hast, ist das der nächste Schritt: Ein lokaler Cluster ist in wenigen Minuten aufgesetzt, die Anleitung steht in Kubernetes lokal: Cluster auf dem Rechner. Lege dort einen Namespace an, rolle mit kubectl create deployment einen Nginx aus und arbeite dich mit get, describe, logs, exec und port-forward einmal durch alle Ebenen. Was du dabei über den Aufbau eines Pods lernst, steht in Kubernetes Pod: was ist ein Pod?.

Die vollständige Referenz aller Verben und Optionen pflegt das Projekt in der kubectl-Dokumentation auf kubernetes.io. Für den Alltag reicht die Tabelle oben; alles Weitere findest du, wenn du es brauchst.

Ausführlich mit allen Beispielen, von der Installation je Betriebssystem über den Aufbau der Kubeconfig bis zur Führung durch Dashboard und Lens, steht das in Kapitel 2 meines Buchs „Kubernetes: Das Praxisbuch für Entwickler und DevOps-Teams" (Rheinwerk). Alle Informationen zum Buch findest du auf meiner Kubernetes-Seite.