What is terminationGracePeriodSeconds in Kubernetes?

In Kubernetes, terminationGracePeriodSeconds defines how much time (in seconds) a Pod gets to shut down gracefully before it is forcefully killed.

When Kubernetes decides to stop a Pod (for example during scaling down, deployment update, or manual deletion), it does not immediately kill the container. Instead, it gives the application some time to finish its work properly.

By default, this time is 30 seconds, but you can increase or decrease it depending on your application needs.

This is important because your application may need time to:

• Finish active requests
• Close DB connections
• Save data
• Release resources

Without this, your application may lose data or cause errors.

How it works internally (step-by-step flow)

When a Pod is terminated, Kubernetes follows a graceful shutdown sequence:

1. Pod is marked as Terminating
2. If defined → preStop hook runs
3. Kubernetes sends SIGTERM signal to the container
4. It waits for terminationGracePeriodSeconds
5. If still running → Kubernetes sends SIGKILL (force kill)

👉 Important understanding:

• SIGTERM = polite request to stop
• SIGKILL = force kill (no cleanup)

Simple real-world example

Imagine your app is a web server (like NGINX or API server):

• Users are connected
• Requests are processing

Now Kubernetes wants to stop the pod.

If terminationGracePeriodSeconds = 30, then:

• Kubernetes tells your app:
  👉 “Finish your work and shut down in 30 seconds”
• During this time:
  • No new requests should be accepted
  • Existing requests complete
• If still running after 30 seconds → Kubernetes kills it forcefully

YAML Example: Pod will get 60 seconds before force termination.

apiVersion: v1
kind: Pod
metadata:
  name: my-app
spec:
  terminationGracePeriodSeconds: 60   # Give 60 seconds to shutdown
  containers:
    - name: app-container
      image: nginx

YAML Example (Deployment)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      terminationGracePeriodSeconds: 45
      containers:
        - name: web
          image: nginx

Commands to use and test

✅ 1. Apply YAML

kubectl apply -f pod.yaml

2. Check pod

kubectl get pods

3. Delete pod (trigger termination)

kubectl delete pod my-app

4. Watch termination behavior

kubectl describe pod my-app
-- logs
kubectl logs -f my-app

5. Override grace period during delete

kubectl delete pod my-app --grace-period=10

When should you increase this value?

You should increase terminationGracePeriodSeconds when your application:

• Handles long-running requests
• Writes data to DB/files
• Needs cleanup logic
• Uses message queues (Kafka, RabbitMQ)

👉 Example:

• Banking app → 60–120 seconds
• API server → 30–60 seconds
• Batch job → even higher

Final Summary

• terminationGracePeriodSeconds = graceful shutdown time
• Default = 30 seconds
• Uses:
  • Prevent data loss
  • Complete running requests
• Flow: preStop → SIGTERM → wait → SIGKILL