DevOps Tutorials, Guides & Best Practices

kubectl rollout restart is the quickest way to trigger a controlled rolling restart for a Deployment, DaemonSet, or StatefulSet. This guide focuses on safe usage (blast radius), how to verify progress, and the most common failure modes during on-call.

TL;DR

• kubectl rollout restart triggers a rolling restart by updating the pod template annotation on a workload (Deployment/DaemonSet/StatefulSet).
• Always scope it (name + namespace) to avoid restarting everything by accident.
• Verify with kubectl rollout status and be ready to kubectl rollout undo (Deployments).

Safety first: avoid blast radius

Related reading on RepoNotes: kubectl commands cheat sheet, Kubernetes Pod vs Container, and what kubelet does.

kubectl rollout restart is a useful command, but it has a sharp edge: if you run kubectl rollout restart deploy without a deployment name (or selector), you can trigger a rolling restart for every Deployment in a namespace.

Safer patterns (do this)

If you need a broader refresher on kubectl basics, check our kubectl commands cheat sheet.

1. Restart a specific resource

   kubectl rollout restart deploy/myapp -n myapp

2. If you need a “group restart”, use a label selector and verify what matches first

   kubectl get deploy -n myapp -l app=myapp
   kubectl rollout restart deploy -n myapp -l app=myapp

3. Always verify the rollout after the restart

   kubectl rollout status deploy/myapp -n myapp

Default namespace trap (anti-pattern)

If you keep many unrelated services in default, the command below can restart everything in that namespace. (In general, as your cluster grows, it helps to be intentional about scoping — see also Kubernetes node selectors for another common scoping tool.)

kubectl rollout restart deploy -n default

What kubectl rollout restart actually does (under the hood)

This does not “restart Pods directly”. It updates the workload’s Pod template (Deployment/DaemonSet/StatefulSet) by adding/updating an annotation with a timestamp. If you need a quick refresher on terminology, see Kubernetes Pod vs Container.

• annotation: kubectl.kubernetes.io/restartedAt
• path: .spec.template.metadata.annotations

Because the PodTemplateSpec changes, Kubernetes treats it as a new template version. For a Deployment this means the pod-template-hash changes, a new ReplicaSet is created, and a normal rolling update happens. If you want more background on who actually drives these transitions, see what the Kubelet does and how the Kubernetes control plane works.

How to check what changed

kubectl get deploy myapp -n myapp -o jsonpath='{.spec.template.metadata.annotations}'
echo

Deployment: restart + verify + rollback

Restart

kubectl rollout restart deploy/myapp -n myapp

Verify rollout

kubectl rollout status deploy/myapp -n myapp
kubectl get pods -n myapp -l app=myapp

If the rollout gets stuck

kubectl get events -n myapp --sort-by=.metadata.creationTimestamp | tail -n 50
kubectl describe pod -n myapp <pod-name>

Rollback (undo)

kubectl rollout undo deploy/myapp -n myapp
kubectl rollout status deploy/myapp -n myapp

Note: kubectl rollout undo is most commonly used with Deployments. DaemonSets and StatefulSets also support rollbacks in many clusters, but behavior depends on your Kubernetes version and update strategy (and it won’t “undo” persisted data like PVC contents).

DaemonSet: restart + verify

A DaemonSet typically means “one Pod per node” (or per a subset of nodes via selectors/taints). A rolling restart can take time, which is expected — the duration depends on node count and update strategy.

Restart

kubectl rollout restart ds/mydaemon -n myapp

Verify

kubectl rollout status ds/mydaemon -n myapp
kubectl get pods -n myapp -l app=mydaemon -o wide

StatefulSet: restart (and why you might not see “all Pods” restart)

StatefulSets restart more conservatively, and not always the way people expect if they come from Deployments. If only some Pods seem to restart, it’s usually due to policy/strategy/constraints — not because kubectl is “broken”.

Restart

kubectl rollout restart sts/mysts -n myapp

Verify

kubectl rollout status sts/mysts -n myapp
kubectl get pods -n myapp -l app=mysts

Troubleshooting

1) Rolling restart caused downtime (Deployment)

In a well-configured setup, a rolling restart should not cause downtime. If it does, Kubernetes usually has nothing safe to route traffic to while old Pods are being terminated:

• Only 1 replica  any restart implies a brief outage.
• Missing/incorrect readiness or startup probes  traffic can hit non-ready Pods.
• Too aggressive RollingUpdate strategy (e.g., maxUnavailable allows too many Pods down at once).
• PDB (PodDisruptionBudget) missing or not aligned with expectations (for multi-replica services).

Gotcha: Kubernetes won’t accept maxSurge: 0 and maxUnavailable: 0 at the same time. But you can still end up with an effectively-stuck rollout when using percentages with a very small replica count (both values round down to 0). For small Deployments, prefer explicit integers (e.g., maxUnavailable: 1) and verify behavior on a staging namespace first.

Quick post-restart checks:

kubectl rollout status deploy/myapp -n myapp
kubectl get pods -n myapp -l app=myapp
kubectl get events -n myapp --sort-by=.metadata.creationTimestamp | tail -n 50

2) “Restart didnt restart all Pods” (especially StatefulSet)

Most common causes:

• PDB is blocking (it won’t allow too many disruptions at once).
• StatefulSet update strategy is OnDelete (rollouts behave differently than you expect).
• rollingUpdate.partition is set (common for canary-style StatefulSet rollouts): Pods with an ordinal < partition will not be updated.
• The StatefulSet is not “up-to-date” in status, or it’s waiting for the previous Pod to become Ready.
• Resource constraints on nodes: the new Pod can’t schedule (Pending), so the old one is not replaced.

Debug commands:

kubectl get pdb -n myapp
kubectl get sts mysts -n myapp -o yaml
kubectl get events -n myapp --sort-by=.metadata.creationTimestamp | tail -n 50
kubectl describe pod -n myapp <pod-name>

Cheat sheet

# Restart
kubectl rollout restart deploy/myapp -n myapp
kubectl rollout restart ds/mydaemon -n myapp
kubectl rollout restart sts/mysts -n myapp

# Verify
kubectl rollout status deploy/myapp -n myapp
kubectl rollout status ds/mydaemon -n myapp
kubectl rollout status sts/mysts -n myapp

# Debug
kubectl get events -n myapp --sort-by=.metadata.creationTimestamp | tail -n 50
kubectl describe pod -n myapp <pod-name>

# Rollback (Deployment)
kubectl rollout undo deploy/myapp -n myapp