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
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 hangCommon 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.
Using this in CI
A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods
# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info
# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes