Pods

A Pod created directly (kubectl run with no controller, or a bare kind: Pod manifest apply`d) is, deliberately, not durable: if its node fails, if it is evicted for resource pressure, or if a human deletes it, nothing recreates it. There is no live migration of a running Pod to another node — a Pod that must move is deleted on the old node and a new one (a new name, a new IP, a new UID) is created on a new one. This is exactly the "Pods are fragile, short-lived" starting point Book 1 ch. 2 spends most of its space on, and it is also why the same book immediately reaches for externalising state: rather than trusting a Pod’s own filesystem to survive, an application keeps anything that must outlive a single Pod in a store built for that — Redis or Memcached for a cache, Cassandra (or, in this section’s Bookshelf scenario, PostgreSQL and Redis) for data that must survive a Pod restart. In current Kubernetes that same idea is formalised as a spectrum: `emptyDir survives container restarts but not Pod deletion, a PersistentVolumeClaim survives Pod deletion but is still just as replaceable as the Pod that mounts it, and a StatefulSet gives a replacement Pod the same stable identity and the same volume, rather than making it durable in place (see Volumes and Ephemeral Storage, Persistent Volumes and Storage Classes and StatefulSets). In every case the answer to "what happens when this Pod dies" is: a controller creates a different Pod, not that the same Pod is repaired or moved. Almost every Bookshelf manifest in this section is therefore wrapped in a controller (a Deployment, a StatefulSet, a Job) — see ReplicaSets and Deployments for how a Deployment supplies exactly that layer over a bare Pod template. Source: Kubernetes Docs — Pods.

Source: Kubernetes Docs — Pods. A Pod this bare is useful only for a one-off debugging session (kubectl run catalog-api-debug --image=…​ --restart=Never); every long-running Bookshelf component is created through a Deployment or StatefulSet instead.

status.phase is a coarse, one-word summary of where a Pod is in its life, and only ever moves forward:

Pending and Running cover every long-lived Pod; Succeeded and Failed are terminal and are what Jobs and CronJobs actually watches for. CrashLoopBackOff and Terminating, which kubectl get pods prints in its STATUS column, are not phases — they are a kubectl display convenience layered on top of a container state and a deletion timestamp, respectively; the phase underneath a CrashLoopBackOff-displaying Pod is still Running (or Pending, before the first successful start). Source: Kubernetes Docs — Pod Lifecycle.

status.conditions is a finer-grained array the kubelet and scheduler maintain alongside the phase, each entry with a type, a status (True/False/Unknown), lastTransitionTime and a machine-readable reason:

kubectl get pods and kubectl describe pod both read this array; kubectl wait --for=condition=Ready is the scriptable way to block on it. Source: Kubernetes Docs — Pod Lifecycle: Pod conditions.

Independently of the Pod-level phase, each container has its own state (surfaced under status.containerStatuses[].state): Waiting (not yet running — pulling its image, or waiting on a previous container state; reason holds strings such as ImagePullBackOff or CrashLoopBackOff), Running, or Terminated (with an exitCode and, if it crashed, a reason such as OOMKilled).

spec.restartPolicy (a Pod-level field, applying to every ordinary container in the Pod) decides what happens next after a container terminates:

A restarted container backs off exponentially (10s, 20s, 40s, …​ capped, by default, at five minutes) so a container that fails immediately does not spin the node’s CPU and API server with restart attempts; kubectl describe pod shows this as CrashLoopBackOff while the container waits out its backoff window. Source: Kubernetes Docs — Pod Lifecycle: restart policy.

Inside the Running phase, each container moves through its own states, which is where a crash loop shows up while the Pod phase stays Running:

Source: Kubernetes Docs — Pod Lifecycle.

spec.initContainers is a separate, ordered list of containers that run to completion, one after another, before any of spec.containers starts. Each must exit 0 before the next begins; if one fails, the kubelet retries it according to restartPolicy (the Pod stays Pending throughout). They exist for setup that the application container itself should not have to know how to do: waiting for a dependency to become reachable, running a one-shot migration, or — the pattern Book 2 ch. 5’s Redis example uses — writing generated configuration files into a shared emptyDir volume that the main container then mounts read-only.

Source: Kubernetes Docs — Init Containers.

An init container can also be marked restartPolicy: Always, which turns it into a native sidecar: it still starts (and must reach a running state) before the main containers, but it is not required to exit before they start, and the kubelet keeps it running and restarts it independently for the Pod’s whole lifetime — and, on shutdown, stops it after every main container has terminated, so it stays available to the very end (for example to flush logs or proxy a final health check). This feature graduated to stable in Kubernetes 1.33 (it was first available, behind a feature gate, in 1.28), and is now the recommended way to run a log shipper, a service-mesh proxy or a metrics exporter alongside an application container, without the ordering problems an ordinary spec.containers entry used to have (a sidecar in spec.containers starts in no guaranteed order relative to the app container, and readiness probes on the whole Pod could pass before the sidecar was actually ready).

Source: Kubernetes Docs — Sidecar Containers.

Native sidecars formalise a scheduling guarantee; the pattern a sidecar container implements is still one of a few well-known shapes, all built from the same "extra container sharing this Pod’s network and volumes" primitive:

spec.ephemeralContainers is a fourth container list, added to an already-running Pod via the pods/ephemeralcontainers subresource rather than at creation time, purely for interactive troubleshooting: it has no ports, no probes, no resource guarantees, and (unlike a native sidecar) is never restarted. kubectl debug is the everyday interface to it — see Debugging and Troubleshooting for the full command set, including attaching a debug container to a minimal distroless image that ships no shell of its own. Source: Kubernetes Docs — Ephemeral Containers.

A static Pod is a Pod the kubelet manages directly from a manifest file on its own node’s filesystem (by default /etc/kubernetes/manifests), completely bypassing the API server and the scheduler: the kubelet watches that directory and starts, restarts or removes Pods as files appear, change or disappear, with no controller and no kubectl apply involved. The kubelet still mirrors each one onto the API server as a read-only mirror Pod so it shows up in kubectl get pods, but kubectl delete on that mirror Pod only removes the mirror — the kubelet recreates it immediately, because the real source of truth is still the file on disk. Static Pods are how kubeadm itself runs kube-apiserver, etcd, kube-scheduler and kube-controller-manager as ordinary Pods on the control plane’s own nodes, without needing a running control plane to bootstrap the control plane (see Cluster Setup and Administration); outside that bootstrapping role, application workloads should use a Deployment or DaemonSet instead, since a static Pod has none of a controller’s rescheduling, rolling-update or multi-node consistency guarantees. Source: Kubernetes Docs — Static Pods.

Each container’s env list sets variables directly (value) or from another object’s field (valueFrom), without the application ever reading Kubernetes objects itself — the mechanism Book 1 ch. 3 already relies on for service discovery before cluster DNS existed, and still the simplest way to hand a container one or two values:

envFrom injects every key of a ConfigMap or Secret at once, each key becoming an env-var name (optionally prefixed), which is the pattern to reach for once a container needs more than a couple of individually-named values:

Source: Kubernetes Docs — Define an environment variable for a container and Kubernetes Docs — Expose Pod information to containers through environment variables; see also Kubernetes Docs — Distribute credentials securely using Secrets.

The Downward API is the general form of fieldRef/resourceFieldRef: a way to expose a Pod’s own metadata and a container’s own resource limits to itself, either as environment variables (above) or as files in a mounted downwardAPI volume, without the container ever calling back into the API server. Typical fields: metadata.name, metadata.namespace, metadata.uid, metadata.labels, metadata.annotations, spec.nodeName, status.podIP, status.hostIP, and limits.cpu / requests.memory per container. The volume form is the only way to expose labels and annotations (their keys can contain characters an env-var name cannot), and it updates the mounted files automatically if labels or annotations change on a running Pod, unlike a configMapKeyRef env var which is fixed at container start.

Source: Kubernetes Docs — Downward API.

A Pod’s own hostname defaults to metadata.name (overridable via spec.hostname), and setting spec.subdomain together with a headless Service of the same name gives it a stable, resolvable DNS name of its own — the exact mechanism StatefulSets builds per-Pod DNS on top of. Separately, spec.hostAliases adds fixed entries to the Pod’s /etc/hosts, useful for pointing at a host that has no DNS entry yet (or overriding one) without touching cluster DNS:

Source: Kubernetes Docs — Add entries to Pod /etc/hosts with HostAliases.

Every container’s image is subject to imagePullPolicy, which decides whether the kubelet trusts a locally cached image or asks the runtime to pull again — the Kubernetes-side counterpart of the tag and registry choices Registries and Docker Hub covers on the build side:

imagePullSecrets names one or more kubernetes.io/dockerconfigjson Secrets (created with kubectl create secret docker-registry) the kubelet presents when pulling from a private registry — the Kubernetes-side equivalent of docker login running once on every node instead of once on a developer’s machine:

A Deployment’s every Pod needs the same imagePullSecrets entry (or the cluster-wide default set on the namespace’s default ServiceAccount), so a private-registry pull failure shows up as ImagePullBackOff on new Pods rather than as a build-time error. Source: Kubernetes Docs — Pull an Image from a Private Registry and Kubernetes Docs — Images.