Core Kubernetes · 03

Pods

1.What is a Pod ?

The smallest thing Kubernetes deploys : one or more containers that are always placed and scheduled together on one node, like a small logical host for one app. API : apiVersion: v1, kind: Pod.

  • One container per Pod is the usual case. A second one only for a tightly coupled helper, e.g. one that refreshes the web server's files.
  • Never add containers to get copies. Copies are more Pods, made by a workload (Deployments and Scaling).

2.Network and storage

  • One IP per address family (status.podIPs : max one IPv4 + one IPv6).
  • Hostname = Pod name by default. Other Pods must use IP networking to reach it.
  • spec.volumes is declared once. Each container mounts what it needs with its own volumeMounts (Volumes and Storage).
Shared in the PodSet per container
IP address and portsImage and command
localhost and IPCEnv variables
Volumes it mountsProbes, resources
Node the Pod is bound here once and never moves Pod : web one IP, one port space localhost seed-content init, exited 0 refresher native sidecar nginx :80 app container writes once every 10s reads html emptyDir : survives container restarts, deleted with this Pod (its UID) Other Pod to Pod IP:80 over the network (no localhost, no shared IPC)

3.Four kinds of container

KindDeclared inWhen it runsProbesRestarts
Appspec.containersAll together once init is done, for the whole Pod lifeliveness, readiness, startupPod restartPolicy (per-container rules beta v1.35)
Initspec.initContainersBefore the apps, one at a time, each must exit 0None, no lifecycle hooks eitherRetried, unless restartPolicy is Never
Native sidecarinitContainers + restartPolicy: AlwaysStarts in init order, stays up the whole Pod life, stops lastYes, its readiness counts for the PodAlways, on any exit (GA v1.33)
Ephemeralvia kubectl debugAdded to a running Pod to troubleshootNot allowed, no ports eitherNever (GA v1.25)

4.Example : init, sidecar and app

apiVersion: v1
kind: Pod
metadata: {name: web}     # DNS label, becomes the hostname
spec:
  volumes: [{name: html, emptyDir: {}}]
  initContainers:
  - name: seed-content    # init : must exit 0
    image: busybox:1.28
    command: [sh, -c, 'echo hello > /html/index.html']
    volumeMounts: [{name: html, mountPath: /html}]
  - name: refresher       # native sidecar
    image: busybox:1.28
    restartPolicy: Always
    command: [sh, -c, 'while sleep 10; do date > /html/time.txt; done']
    volumeMounts: [{name: html, mountPath: /html}]
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports: [{containerPort: 80}]
    volumeMounts: [{name: html, mountPath: /usr/share/nginx/html}]
Start order
Sandbox readynetwork and volumes, phase Pending
seed-contentmust exit 0 (STATUS Init:0/2)
refresherstarted (or startupProbe ok)
nginxapps start together, phase Running
Stop order is the reverse : apps get TERM first, sidecars only after the last app exits.
In short : A Pod is one or more containers that share a node, one IP and the volumes they mount. Init runs first, sidecars run beside the app, and a controller usually creates the Pods.

1.Pod phases (status.phase)

Pendingnot set up yet Runningon a node Unknownlost contact Succeededterminal Failedterminal bound container restarts all exit 0 one failed,no restart node lost init fails and restartPolicy is Never
  • A rough summary, not a state machine. An in-place Pod restart can go back to Pending. STATUS is not the phase.
PhaseMeans (STATUS you may see)
PendingAccepted, but not every container is set up : no node yet, image pulls, init steps. Init:0/1, ContainerCreating, ImagePullBackOff
RunningOn a node, all containers created, at least one running or restarting. Running, CrashLoopBackOff
SucceededEvery container exited 0 and none will restart. Completed
FailedAll stopped, at least one failed, no restart coming. Pods of a lost node end here too. Error
UnknownState cannot be read, usually because the node does not answer.

2.Container states and restarts

Waitingnot started yet pull retry (max 300s) RunningpostStart done container starts Terminatedreason + exit code exits or is killed(preStop first) Restart ?restartPolicy yes : CrashLoopBackOffat once, then 10s, 20s ... 300s no : stays Terminated OOMKilled = exit 137
  • ImagePullBackOff : bad name or tag, or a private registry without an imagePullSecret.
PolicyExit 0Exit 1+Where
Always (default)restartrestartOnly value in a Deployment
OnFailuredonerestartJobs
NeverdonedoneJobs, one-off Pods
SidecarrestartrestartIgnores the Pod policy
  • Restarts happen in the same Pod, on the same node. RESTARTS goes up, the phase stays Running. Backoff resets after 10 min of clean running.

3.Why not a bare Pod ?

  • Scheduled once. Node failure, eviction or delete ends it for good.
  • Deployment, StatefulSet, DaemonSet and Job build Pods from a template and replace lost ones (new UID).
  • An HPA scales a workload, never a single Pod.
  • Delete : 30s grace, TERM (after preStop), then KILL.
Gotchas
  • Two containers in one Pod cannot both use :80.
  • A helper in spec.containers is not a sidecar : no start or stop order.
  • Pod fields are mostly immutable. Change the template instead.
  • --grace-period=0 --force does not wait for the kubelet. The process may still run.

4.Commands

CommandWhat it does
kubectl run web --image=nginx --dry-run=client -o yamlPrints a Pod manifest skeleton, creates nothing
kubectl get pods --field-selector=status.phase=RunningFilters on the real phase, not on STATUS
kubectl describe pod webState, Last State, exit code, Conditions, then Events. Conditions in kubelet order : PodReadyToStartContainers (sandbox ready, GA v1.37), Initialized, Ready, ContainersReady, PodScheduled
kubectl logs web -c nginx --previousLogs of the crashed run of one container
kubectl debug -it web --image=busybox:1.28 --target=nginxAdds an ephemeral debug container
In short : The phase is only a summary. The kubelet restarts containers in place with a growing backoff, but only a controller replaces a Pod that is gone.