Understanding Kubernetes Pod Lifecycle: Phases, Creation, and Termination

Pod Lifecycle Overview

A Pod’s lifecycle spans from creation to termination, during which it can perform several operations:

Creating the main container (required).

Optional actions such as init containers, post‑start hooks, liveness probes, readiness probes, and pre‑stop hooks.

Whether these actions run depends on the Pod specification.

Pod Phases

Regardless of how a Pod is created, it will be in one of the following phases:

Pending : The API server has stored the Pod object, but it has not been scheduled or is still pulling images.

Succeeded : All containers have terminated successfully and will not be restarted.

Failed : All containers have terminated, but at least one exited with a non‑zero status.

Unknown : The API server cannot obtain the Pod’s status, usually due to communication issues with the node.

Pod Creation Process

The typical steps for creating a Pod are:

User submits a Pod spec to the API server via kubectl or another client.

The API server stores the Pod object in etcd.

etcd confirms the write and notifies the API server.

The API server returns the confirmation to the client.

The scheduler sees the new Pod and binds it to a node.

The scheduler returns the bind result to the API server.

The API server records the bind information in etcd.

etcd acknowledges the write.

The API server informs the scheduler that the bind info is stored.

Kubelet, watching the API server, learns that the Pod is scheduled to its node.

Kubelet invokes the node’s container runtime (Docker) to start containers.

Docker reports the container start status back to kubelet.

Kubelet updates the Pod status in the API server.

The API server writes the updated Pod status to etcd.

etcd confirms the write.

The API server notifies the kubelet of the update.

Key Behaviors in the Pod Lifecycle

Init Containers run before the main container, must complete successfully, and are executed sequentially. If the Pod’s spec.restartPolicy is set to Never, a failing init container will not be restarted.

cat init-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: nginx-pod-test
spec:
  containers:
  - name: nginx
    image: nginx:latest
  initContainers:
  - name: init-container
    image: busybox:latest
    command: ['sh', '-c', 'sleep 10']

Check Pod status:

# Observe Pod initializing
kubectl get pods -o wide | grep nginx-pod-test

# Pod is running
kubectl get pods -o wide | grep nginx-pod-test

# Detailed description
kubectl describe pod nginx-pod-test

Lifecycle Hook Functions

Lifecycle hooks let containers run custom code at key moments. Kubernetes supports two hooks:

postStart : Runs immediately after container creation (not guaranteed before ENTRYPOINT).

preStop : Runs synchronously before container termination, blocking the stop until it finishes.

Hooks can be implemented via Exec (run a command inside the container) or HTTP (send a request to a URL). Example manifest:

cat hook-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: lifecycle-demo
spec:
  containers:
  - name: lifecycle-container
    image: nginx:latest
    lifecycle:
      postStart:
        exec:
          command: ["/bin/sh", "-c", "echo 'lifecycle hooks handler' > /usr/share/nginx/html/test.html"]

Apply and view status:

# Create Pod
kubectl apply -f hook-pod.yaml

# Check status
kubectl get pods -o wide | grep lifecycle-demo

# Access result of postStart command
curl http://10.244.3.60/test.html

Pod Termination Process

When a user deletes a Pod, Kubernetes performs a graceful termination:

The user issues a delete command.

The Pod enters a grace period (default 30 s) and is marked “dead”.

The Pod status becomes “Terminating”.

Kubelet starts the shutdown sequence as soon as it sees the “Terminating” state.

The endpoint controller removes the Pod from Service endpoints.

If a preStop hook is defined, it runs synchronously; if it exceeds the grace period, a short extra grace period is granted.

The main container process receives a SIGTERM.

After the grace period, any remaining processes receive SIGKILL.

Kubelet tells the API server to set the grace period to zero, and the Pod is finally removed.

By default the grace period is 30 seconds, but kubectl delete can override it with --grace-period=. Using --grace-period=0 together with --force forces an immediate deletion.