Clarify Pod restartPolicy behavior in “Always” vs “OnFailure” scenarios #51757
Description
Problem
The Kubernetes documentation for restartPolicy in Pods (https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#restart-policy) does not clearly explain the differences in container restart behavior between Always, OnFailure, and Never.
New users are often confused when a pod restarts even after exit code 0 or doesn't restart despite an error, especially when used with Deployments or Jobs.
Steps to Reproduce
- Create a Pod with
restartPolicy: OnFailure - Run a container that exits with code 0
- Notice the pod does not restart
- Change it to exit with code 1 → Now it restarts
Expected Addition to Docs
- Table comparing:
- Exit code vs Restart behavior
- Behavior under different controllers (e.g., Deployment, Job)
- Add concrete YAML examples
- Link to kubelet behavior references
Suggested Fix
I'd like to improve the docs page with:
- A comparison table
- Clear examples of
OnFailure,Always,Never - Add links to the underlying kubelet logic
Let me know if this would be accepted — happy to draft the PR!
Labels: documentation, good first issue, help wanted