kubectl rollout ist der Befehl, mit dem Sie steuern und nachvollziehen, wie Kubernetes Änderungen an einem Workload ausrollt. Wenn Sie ein Deployment ändern, ersetzt Kubernetes die alten Pods durch neue – und mit kubectl rollout beobachten Sie diesen Prozess, pausieren ihn, rollen ihn zurück, starten ihn neu und sehen sich seine Historie an.
In diesem Guide erfahren Sie, wie Kubernetes ein Rollout unter der Haube tatsächlich ausführt, lernen alle kubectl rollout-Subcommands mit Beispielen kennen, verstehen, warum Rollouts hängen bleiben und wie Sie sie diagnostizieren – und welche Praktiken Rollouts in der Produktion sicher machen.
Was ist kubectl rollout?
kubectl rollout ist eine Gruppe von Befehlen zur Verwaltung des Rollouts eines Workloads nach einer Änderung. Ein Rollout ist der Prozess, bei dem die Pods mit der alten Version durch Pods mit der neuen Version ersetzt werden. Der Befehl ändert nicht Ihren Workload selbst. Stattdessen können Sie damit das Rollout beobachten und steuern, das eine Änderung auslöst: prüfen, ob es abgeschlossen ist, nachsehen, was sich geändert hat, es rückgängig machen, pausieren und fortsetzen oder die Pods neu starten.
Der Befehl funktioniert mit den Workloads, die Rollouts für Sie verwalten: Deployments, StatefulSets und DaemonSets. Der Großteil dieses Guides verwendet ein Deployment, da Rollouts dort am häufigsten vorkommen.
Wie führt Kubernetes ein Rollout tatsächlich aus?
Wenn Sie das Pod-Template eines Deployments ändern, bearbeitet Kubernetes nicht die laufenden Pods. Es erstellt ein neues ReplicaSet für die neue Version und verschiebt die Pods schrittweise vom alten ReplicaSet zum neuen. Jedes ReplicaSet – und jeder Pod, der ihm gehört – trägt ein pod-template-hash-Label, einen Hash des Pod-Templates. Über dieses Label unterscheidet Kubernetes die Versionen und ordnet jeden Pod dem richtigen ReplicaSet zu. Wenn Sie später ein Rollback durchführen, skaliert Kubernetes in Wirklichkeit nur ein altes ReplicaSet wieder hoch.
Entscheidend ist zu wissen, welche Änderungen tatsächlich ein Rollout starten. Nur Änderungen am Pod-Template, dem Feld .spec.template, erzeugen ein neues ReplicaSet und eine neue Revision. Das heißt: Ein neues Image, eine geänderte Umgebungsvariable oder ein aktualisierter Resource Request lösen jeweils ein Rollout aus. Eine Änderung der Replica-Anzahl dagegen nicht, denn beim Hoch- oder Herunterskalieren wird lediglich das aktuelle ReplicaSet in der Größe angepasst, statt ein neues zu erstellen. Deshalb taucht das Skalieren eines Deployments nie in seiner Rollout-Historie auf.
Die Geschwindigkeit des Rollouts steuern zwei Felder in der Rolling-Update-Strategie. maxSurge legt fest, wie viele zusätzliche Pods während des Rollouts über der gewünschten Anzahl existieren dürfen; der Standardwert ist 25 %, aufgerundet. maxUnavailable legt fest, wie viele Pods während des Rollouts unter der gewünschten Anzahl fehlen dürfen; der Standardwert ist 25 %, abgerundet. Zusammen bestimmen sie, wie schnell Kubernetes alte Pods durch neue ersetzt. maxSurge: 1 und maxUnavailable: 0 sind eine gängige, sichere Wahl: Es wird erst ein neuer Pod hinzugefügt, bevor ein alter entfernt wird, und die volle Kapazität wird nie unterschritten.
Drei weitere Einstellungen steuern den Fortschritt des Rollouts. Ein neuer Pod zählt erst als verfügbar, wenn seine Readiness Probe erfolgreich ist. Ohne eine gute Readiness Probe behandelt Kubernetes einen Pod also als bereit, bevor er Traffic verarbeiten kann, und geht zu früh weiter. minReadySeconds lässt einen Pod, nachdem er bereit ist, noch warten, bevor er als verfügbar zählt – das fängt Pods ab, die ihre Probe bestehen und Sekunden später abstürzen. Und progressDeadlineSeconds, standardmäßig 600 (10 Minuten), bestimmt, wie lange Kubernetes auf Fortschritt beim Rollout wartet, bevor es das Deployment mit ProgressDeadlineExceeded als fehlgeschlagen markiert.
Die kubectl rollout Subcommands und welche Ressourcen sie unterstützen
kubectl rollout hat sechs Subcommands: status, history, undo, pause, resume und restart. Sie gelten nicht alle für jeden Workload. status, history, undo und restart funktionieren mit Deployments, StatefulSets und DaemonSets. pause und resume funktionieren nur mit Deployments, denn nur ein Deployment hat ein pausierbares Rollout. Die folgenden Abschnitte behandeln jeden Befehl anhand eines Deployments namens api.
kubectl rollout status
kubectl rollout status verfolgt ein Rollout und meldet, wann es abgeschlossen ist:
kubectl rollout status deployment/apiWährend der Ausführung gibt der Befehl den Fortschritt aus und beendet sich, wenn das Rollout fertig ist. Sie sehen Zeilen wie Waiting for deployment "api" rollout to finish: 2 out of 4 new replicas have been updated... und schließlich deployment "api" successfully rolled out. Jede Zeile spiegelt wider, wie das neue ReplicaSet hochskaliert und die Pods verfügbar werden.
Standardmäßig streamt der Befehl die Ausgabe und wartet. Zwei Flags ändern dieses Verhalten: --timeout verhindert endloses Warten, was in Skripten wichtig ist, und --watch=false gibt den aktuellen Status einmal aus und beendet sich, statt zu streamen:
kubectl rollout status deployment/api --timeout=5mkubectl rollout status deployment/api --watch=falseDas Nützlichste an rollout status ist sein Exit-Code. Er gibt 0 zurück, wenn das Rollout erfolgreich ist, und einen Wert ungleich null, wenn es fehlschlägt oder das Timeout erreicht wird. Das macht den Befehl wertvoll für CI/CD-Pipelines: Die Pipeline kann auf den Abschluss des Rollouts warten und fehlschlagen, wenn das Deployment nicht bereit wird – statt ein erfolgreiches kubectl apply als erfolgreiches Deployment zu werten.
kubectl rollout history
kubectl rollout history listet die vergangenen Revisionen eines Workloads auf, sodass Sie sehen, was sich geändert hat, und eine Revision für den Rollback auswählen können:
kubectl rollout history deployment/apiDie Ausgabe ist eine Tabelle mit Revisionsnummern und einer CHANGE-CAUSE-Spalte. Um das vollständige Pod-Template einer Revision zu sehen, übergeben Sie --revision:
kubectl rollout history deployment/api --revision=2Die CHANGE-CAUSE-Spalte wird nur befüllt, wenn Sie die Annotation kubernetes.io/change-cause setzen. Das alte --record-Flag, das sie früher befüllt hat, ist veraltet; der aktuelle Weg ist, die Annotation nach einer Änderung selbst zu setzen:
kubectl annotate deployment/api kubernetes.io/change-cause="update image to api:1.4.0"Ohne die Annotation zeigt die Spalte <none>, was es schwieriger macht zu erkennen, was sich in den einzelnen Revisionen geändert hat.
Wie weit zurück ein Rollback möglich ist, hängt von revisionHistoryLimit ab, standardmäßig 10. Kubernetes behält entsprechend viele alte ReplicaSets und entfernt ältere. Ist das Limit zu niedrig, existiert die Revision, zu der Sie zurückkehren möchten, möglicherweise nicht mehr.
kubectl rollout undo
kubectl rollout undo rollt einen Workload zurück. Ohne Argumente geht es zur vorherigen Revision, mit --to-revision zu einer bestimmten Revision aus der Historie:
kubectl rollout undo deployment/apikubectl rollout undo deployment/api --to-revision=2Das funktioniert, weil Kubernetes das alte ReplicaSet noch hat und es einfach wieder hochskaliert. Ein Rollback ist selbst ein Rollout – führen Sie danach also rollout status aus, um den Abschluss zu bestätigen.
Eine wichtige Einschränkung: undo stellt nur das Pod-Template wieder her. Dazu gehören das Container-Image, Umgebungsvariablen und Ressourceneinstellungen. Änderungen außerhalb des Pod-Templates werden nicht rückgängig gemacht. Hat das Release beispielsweise auch eine ConfigMap, ein Secret, ein Datenbankschema oder ein externes System geändert, macht der Rollback des Deployments diese Änderungen nicht rückgängig.
Behandeln Sie rollout undo deshalb als schnelles Recovery-Tool, nicht als Ihre normale Deployment-Strategie. Es kann eine frühere Pod-Version schnell wiederherstellen, aber nicht alles zurückrollen, was sich während eines Releases möglicherweise geändert hat.
kubectl rollout restart
kubectl rollout restart startet alle Pods eines Workloads neu, ohne das Image zu ändern:
kubectl rollout restart deployment/apiDer Befehl fügt dem Pod-Template eine kubectl.kubernetes.io/restartedAt-Annotation mit dem aktuellen Zeitstempel hinzu. Da dies das Pod-Template ändert, behandelt Kubernetes es als normales Rollout. Es erstellt ein neues ReplicaSet und ersetzt die alten Pods schrittweise gemäß maxSurge, maxUnavailable und den Readiness Probes. Mit korrekt konfigurierten Probes kann die Anwendung so ohne Ausfallzeit neu starten.
Ein häufiger Anwendungsfall ist das Übernehmen von Änderungen, die Pods nicht automatisch neu starten. Wenn Sie beispielsweise eine ConfigMap oder ein Secret aktualisieren, das die Anwendung nur beim Start liest, verwenden bestehende Pods weiterhin die alten Werte. Ein Rollout Restart ersetzt diese Pods, sodass sie mit den neuen Werten starten.
Ein Rollout Restart ist kontrollierter als das manuelle Löschen von Pods oder das Skalieren eines Deployments auf null. Manuell gelöschte Pods werden zwar ersetzt, aber ohne denselben kontrollierten Rollout-Prozess – und das Skalieren auf null stoppt alle Pods, bevor neue starten, was Ausfallzeit verursacht. Ein Rollout Restart ersetzt die Pods schrittweise und hält sich dabei an die Rollout-Einstellungen des Deployments.
kubectl rollout pause und resume
kubectl rollout pause hindert ein Deployment daran, auf Änderungen zu reagieren, und kubectl rollout resume lässt es fortfahren:
kubectl rollout pause deployment/apikubectl rollout resume deployment/apiDas ist in zwei Situationen nützlich. Die erste: mehrere Änderungen in einem einzigen Rollout bündeln. Wenn Sie zuerst pausieren, dann Image, Ressourcen und Umgebungsvariablen ändern und anschließend fortsetzen, führt Kubernetes ein einziges Rollout mit allen Änderungen durch, statt für jede Bearbeitung ein separates:
kubectl rollout pause deployment/apikubectl set image deployment/api api=api:1.5.0kubectl set resources deployment/api -c=api --limits=cpu=500m,memory=512Mikubectl rollout resume deployment/apiDie zweite: mitten im Rollout pausieren, um einen partiellen Canary zu validieren. Sie starten ein Rollout durch eine Image-Änderung, lassen ein paar neue Pods hochkommen und pausieren dann. Nun läuft ein kleiner Teil des Traffics auf der neuen Version, während der Rest auf der alten bleibt, und Sie können Metriken und Logs beobachten. Läuft alles stabil, setzen Sie fort, um das Rollout abzuschließen; wenn nicht, rollen Sie mit undo zurück. Beachten Sie: Ein pausiertes Deployment lässt sich nicht zurückrollen – setzen Sie es also fort, bevor Sie undo ausführen.
Warum bleiben Rollouts hängen und wie diagnostiziert man sie?
Ein Rollout bleibt hängen, wenn neue Pods nicht verfügbar werden, und das Deployment meldet schließlich ProgressDeadlineExceeded. Das sind die häufigsten Ursachen:
a. Zu wenig Cluster-Kapazität für die Surge-Pods: Ein Rolling Update erstellt zusätzliche Pods (maxSurge), bevor alte entfernt werden. Das Rollout braucht also freie CPU- und Speicherressourcen, um sie einzuplanen. Hat der Cluster keinen Platz, bleiben die Surge-Pods Pending, und das Rollout kommt nicht voran. Prüfen Sie den Pod im Status Pending mit kubectl get pods und kubectl describe pod, und schauen Sie, ob der Cluster Autoscaler einen Node hinzufügen kann.
b. Fehlgeschlagene Readiness Probes und CrashLoopBackOff: Wenn die neuen Pods zwar starten, aber ihre Readiness Probe nie bestehen oder in einer Schleife abstürzen und neu starten, zählen sie nie als verfügbar, und das Rollout stockt. Lesen Sie die Logs des neuen Pods mit kubectl logs und seine Events mit kubectl describe pod. Hier zeigt sich eine falsch konfigurierte Probe oder ein fehlerhaftes neues Image.
c. OOMKills durch zu knapp bemessene Memory Requests und Limits: Braucht die neue Version mehr Speicher, als ihr Limit erlaubt, beendet der Kernel jeden neuen Pod direkt beim Start. Der Pod zeigt dann OOMKilled mit Exit-Code 137, und das Rollout wird nie abgeschlossen. Die Logs des Pods sind meist leer, weil der Container gekillt wurde, statt abzustürzen – das Signal finden Sie in kubectl describe pod unter dem Last State.
d. PodDisruptionBudgets blockieren das Rollout selbst nicht: Ein PodDisruptionBudget schränkt das Rolling Update eines Deployments nicht ein. PDBs begrenzen Rolling Updates von Workloads nicht, weil das Rollout Pods direkt ersetzt und nicht über die Eviction API. Was ein PDB einschränkt, sind freiwillige Evictions: Node Drains, Scale-down durch den Cluster Autoscaler und Ähnliches. Ein PDB kann also einen Node Drain blockieren, der zeitgleich mit Ihrem Rollout läuft, und ein schlecht konfiguriertes PDB (z. B. minAvailable gleich der Replica-Anzahl) kann Drains komplett blockieren – aber es ist nicht das, was das Rollout selbst aufhält.
e. Horizontal Pod Autoscaler und Replica-Konflikte: Wenn ein HPA die Replicas eines Deployments verwaltet und Sie gleichzeitig replicas im Manifest fest hinterlegen, setzt jedes kubectl apply die Anzahl auf den Manifest-Wert zurück, bis der HPA sie wieder korrigiert. Das kann während eines Rollouts zu verwirrendem Skalierungsverhalten führen. Die Lösung: Lassen Sie replicas bei jedem Deployment, das ein HPA verwaltet, aus dem Manifest weg.
Die meisten dieser Probleme lassen sich auf die Ressourcendimensionierung zurückführen. Surge-Pods, die nicht auf den Cluster passen, und neue Pods, die per OOMKilled beendet werden, deuten beide auf falsche Ressourceneinstellungen hin. Genau hier hilft PerfectScale. Die Kubernetes-Governance-Plattform beobachtet, wie Ihre Workloads CPU und Speicher tatsächlich nutzen, und macht daraus umsetzbare, automatisierte Right-Sizing-Empfehlungen, die Sie manuell oder autonom anwenden können. Mit Requests und Limits, die der Realität entsprechen, passen Ihre Surge-Pods auf den Cluster und Ihre neuen Pods haben den Speicher, den sie brauchen – Rollouts laufen sauber durch, statt hängen zu bleiben. Teams wie Paramount Pictures und Creditas setzen auf PerfectScale, um ihre Cluster effizient zu halten. Registrieren Sie sich oder buchen Sie eine technische Session.
Best Practices für kubectl rollout in der Produktion
Ein paar einfache Praktiken, damit Rollouts in der Produktion sicher und reibungslos bleiben:
a. Requests und Limits vor dem Rollout richtig dimensionieren: Setzen Sie präzise Resource Requests und Limits, bevor Sie ein Rollout starten. Das gibt Surge-Pods genug Platz zum Einplanen und senkt das Risiko, dass neue Pods per OOMKill beendet werden.
b. Metriken und Logs prüfen, nicht nur den Rollout-Status: Ein erfolgreicher Rollout-Status bedeutet nur, dass die neuen Pods bereit wurden. Er bedeutet nicht, dass die Anwendung korrekt funktioniert. Prüfen Sie nach einem Rollout Fehlerraten, Latenz und Logs – besonders bei einem pausierten Canary.
c. progressDeadlineSeconds und --timeout explizit setzen: Setzen Sie ein sinnvolles progressDeadlineSeconds, damit Kubernetes ein hängendes Deployment als fehlgeschlagen markiert. Verwenden Sie --timeout mit rollout status, damit Ihre Pipeline nach einer definierten Zeitspanne nicht mehr wartet.
d. Jede Änderung mit einer change-cause-Annotation versehen: Setzen Sie kubernetes.io/change-cause bei jeder Änderung, damit die Rollout-Historie klar zeigt, was sich in den einzelnen Revisionen geändert hat. Das erleichtert beim Rollback die Wahl der richtigen Revision.
e. revisionHistoryLimit hoch genug halten, um sicher zurückrollen zu können: Der Standardwert von 10 reicht für die meisten Workloads. Wenn Sie aber sehr häufig deployen, stellen Sie sicher, dass er weiterhin alle Revisionen abdeckt, zu denen Sie realistischerweise zurückkehren müssten.
f. Den Blast Radius durch schrittweises Ausrollen begrenzen: Schicken Sie eine riskante Änderung nicht auf einen Schlag in jeden Namespace oder Cluster. Rollen Sie sie stufenweise aus, damit Sie Probleme früh erkennen und stoppen können, bevor sie alles betreffen.
g. Von manuellen Befehlen zu GitOps und Progressive Delivery wechseln: kubectl rollout eignet sich gut, um Rollouts zu lernen und manuell zu verwalten. In größeren Produktionsumgebungen können Tools wie Argo CD oder Flux Deployments per GitOps verwalten, während Argo Rollouts oder Flagger Canary- und Blue-Green-Deployments automatisieren.