kubectl delete --grace-period: Usage, Options & Common CI Errors

Tune how long termination waits - or force-remove a stuck pod.

kubectl delete --grace-period sets how long Kubernetes waits for a graceful shutdown, and --grace-period=0 --force removes a pod immediately. These flags are how you clear a stuck Terminating pod in CI - with real caveats.

What it does

By default delete honours the pod's terminationGracePeriodSeconds. --grace-period=N overrides it; --grace-period=0 --force tells the API server to drop the object from its records immediately without waiting for the kubelet to confirm the container stopped. --force without grace-period=0 is rejected for pods.

Common usage

Terminal

kubectl delete pod my-pod --grace-period=30
kubectl delete pod stuck --grace-period=0 --force
kubectl delete pod stuck --grace-period=0 --force --wait=false
kubectl get pod stuck -o jsonpath='{.metadata.finalizers}'   # check the hang

Common errors in CI

Force-deleting a pod is not free: --grace-period=0 --force removes the API object even if the container is still running on the node, so for a StatefulSet this can violate at-most-one guarantees and corrupt data - reserve it for stateless test fixtures, not databases. A delete that still hangs after grace-period=0 is a finalizer holding the object, not a slow shutdown; check metadata.finalizers and resolve the controller rather than force-patching finalizers blindly. "warning: Immediate deletion does not wait for confirmation that the running resource has been terminated" is expected with force, not an error.

Related guides

kubectl Cheat Sheet: Commands for Everyday KubernetesA kubectl cheat sheet - get, describe, logs, apply, rollout, debug, and context commands for daily Kubernetes… kubectl delete -l: Usage, Options & Common CI Errorskubectl delete -l removes every resource matching a label. Scoped teardown in CI, the dangerous broad-selecto… kubectl wait --for=condition: Usage, Options & Common CI Errorskubectl wait --for=condition blocks until a resource reaches a condition. Gating CI on Ready/Available, the t… kubectl replace --force: Usage, Options & Common CI Errorskubectl replace --force deletes and recreates a resource to change immutable fields. When to reach for it ove…