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

> kubectl delete --grace-period controls termination time; --grace-period=0 --force removes a stuck pod. The risks of force-deleting and the finalizer hang.

Source: https://latchkey.dev/learn/command-reference/kubectl-delete-grace-period  
Updated: 2026-06-25

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.

## 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.

```Terminal
# 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
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

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

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt