Sign In

Curriculum 9: Deleting Resources

Grace Periods

10 min · 15 XP

Grace Periods and Forced Deletion

When Kubernetes deletes a Pod, it does not kill the container instantly. It gives the application time to shut down gracefully. Understanding grace periods helps you balance between clean shutdowns and fast cleanup.

How Graceful Termination Works

When a Pod is deleted, Kubernetes follows this sequence:

  1. The Pod is marked as "Terminating"
  2. The kubelet sends a SIGTERM signal to the container's main process
  3. The application has a grace period (default 30 seconds) to finish what it is doing
  4. If the process is still running after the grace period, the kubelet sends SIGKILL to force-stop it
  5. The Pod is removed from the API server
# Delete with the default 30-second grace period
kubectl delete pod my-app

terminationGracePeriodSeconds

You can configure the grace period in the Pod spec:

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - name: app
    image: my-app:1.0

Set this based on how long your application needs to:

  • Finish processing in-flight requests
  • Close database connections
  • Flush logs and metrics
  • Complete any cleanup tasks

Overriding the Grace Period

You can override the configured grace period at delete time:

# Give the pod 60 seconds to shut down
kubectl delete pod my-app --grace-period=60

# Give it only 10 seconds
kubectl delete pod my-app --grace-period=10

Force Deletion

Sometimes a Pod gets stuck in the Terminating state. This can happen when a node is unreachable or the kubelet is not responding. Force deletion removes the Pod from the API server immediately:

kubectl delete pod my-app --grace-period=0 --force

Both flags are required for force deletion. The --force flag alone is not enough.

Warning: Force deletion removes the Pod from the API server, but the container may still be running on the node. This can cause issues if the application writes to shared storage or holds locks. Only use force deletion when you are sure the Pod is truly stuck.

When to Use Force Deletion

  • The node hosting the Pod is permanently down
  • The Pod has been stuck in Terminating for a long time
  • You are cleaning up after a node failure

When to avoid force deletion:

  • The Pod is on a healthy node and just taking time to shut down
  • The application is flushing critical data
  • The Pod holds a lock on a shared resource

Key Takeaways

  • Kubernetes sends SIGTERM first, then SIGKILL after the grace period
  • The default grace period is 30 seconds, configurable via terminationGracePeriodSeconds
  • Override at delete time with --grace-period=<seconds>
  • Force deletion with --grace-period=0 --force removes stuck Pods immediately
  • Force deletion does not guarantee the container process has actually stopped