Mastering Kubernetes Pod Restart Policies and Lifecycle: A Practical Guide

System Environment

Server Version

Docker Version

Kubernetes (k8s) Cluster Version

CPU Architecture

CentOS Linux release 7.4.1708 (Core)

Docker version 20.10.12

v1.21.9

x86_64

Kubernetes cluster architecture: k8scloude1 as master node, k8scloude2 and k8scloude3 as worker nodes.

Server

OS Version

CPU Architecture

Processes

Description

k8scloude1/192.168.110.130

CentOS Linux release 7.4.1708 (Core)

x86_64

docker, kube-apiserver, etcd, kube-scheduler, kube-controller-manager, kubelet, kube-proxy, coredns, calico

K8s master node

k8scloude2/192.168.110.129

CentOS Linux release 7.4.1708 (Core)

x86_64

docker, kubelet, kube-proxy, calico

K8s worker node

k8scloude3/192.168.110.128

CentOS Linux release 7.4.1708 (Core)

x86_64

docker, kubelet, kube-proxy, calico

K8s worker node

Preface

This article introduces three pod restart policies (Always, OnFailure, Never) and five pod phases (Pending, Running, Succeeded, Failed, Unknown). It assumes a functional Kubernetes cluster is already set up.

Pod Restart Policy

The restartPolicy field in a pod spec can be Always, OnFailure, or Never, with Always as the default. It applies to all containers in the pod and is handled by the kubelet on the same node, which uses exponential back‑off for restarts.

Always: always restart.

OnFailure: restart only on failure (a normal exit like sleep 10 does not trigger a restart).

Never: never restart.

Example to view the field description:

kubectl explain pods.spec.restartPolicy

Pod Lifecycle

A pod progresses through predefined phases: Pending, Running, Succeeded, Failed, and Unknown. The kubelet can restart containers during the Running phase, and the pod’s status includes conditions that can be customized.

Pods are scheduled only once; after being assigned to a node they remain there until they stop or are terminated.

The status.phase field provides a high‑level overview of the pod’s current state.

Phase

Description

Pending

Pod accepted by the system but containers are not yet created or running; includes scheduling and image pull time.

Running

Pod bound to a node and all containers created; at least one container is running or starting.

Succeeded

All containers terminated successfully and will not be restarted.

Failed

All containers terminated, with at least one failing (non‑zero exit or killed).

Unknown

Pod status cannot be obtained, often due to communication failure with the node.

If a node dies or loses connectivity, Kubernetes sets the phase of its pods to Failed.

Pod deletion can be slow (default 30 seconds). The terminationGracePeriodSeconds field controls the graceful termination period.

kubectl explain pods.spec.terminationGracePeriodSeconds

Setting terminationGracePeriodSeconds to 0 removes the grace period, allowing immediate deletion.

# pod2.yaml
apiVersion: v1
kind: Pod
metadata:
  labels:
    run: pod1
  name: pod1
spec:
  terminationGracePeriodSeconds: 0
  containers:
  - image: nginx
    imagePullPolicy: IfNotPresent
    name: n1
    resources: {}
  - image: nginx
    imagePullPolicy: IfNotPresent
    command: ["sh","-c","sleep 10"]
    name: n2
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always

Applying the manifest and deleting the pod:

# kubectl apply -f pod2.yaml
pod/pod1 created
# kubectl delete pod pod1
pod "pod1" deleted