Pod

The smallest deployable unit of Kubernetes. A Pod is one or more containers sharing a network namespace, an IPC namespace, a UTS namespace, and a set of volumes. The Pod is the unit the scheduler binds, the kubelet runs, and almost every controller produces.

Where it lives

Concern	Path
Public type	staging/src/k8s.io/api/core/v1/types.go (type Pod struct {...})
Internal type	pkg/apis/core/types.go
Conversion external↔internal	pkg/apis/core/v1/zz_generated.conversion.go
Validation	pkg/apis/core/validation/validation.go (huge file; pod validation alone is several thousand lines)
Defaulting	pkg/apis/core/v1/defaults.go
REST registry	pkg/registry/core/pod/
Strategy	pkg/registry/core/pod/strategy.go
Storage	pkg/registry/core/pod/storage/storage.go
OpenAPI	pkg/generated/openapi/zz_generated.openapi.go
Apply config	staging/src/k8s.io/client-go/applyconfigurations/core/v1/pod.go

Subresources

Pods have an unusually rich set of subresources, each at /{name}/<subresource>:

Subresource	Purpose
/status	Status writes (kubelet, schedulers)
/binding	Bind a Pod to a Node (legacy scheduler path; modern scheduler patches spec.nodeName)
/eviction	Eviction respecting PodDisruptionBudget
/log	Container logs (proxied to kubelet)
/exec	Streaming exec (proxied to kubelet)
/attach	Streaming attach (proxied to kubelet)
/portforward	Streaming port-forward (proxied to kubelet)
/proxy	Generic HTTP proxy (proxied to kubelet)
/ephemeralcontainers	Add ephemeral debug containers
/resize	In-place resource resize (alpha)

The streaming subresources (exec, attach, portforward) terminate inside the apiserver and proxy through to the kubelet's HTTPS server (port 10250) over an SPDY or WebSocket connection.

Lifecycle

stateDiagram-v2
    [*] --> Pending: created
    Pending --> Pending: scheduling
    Pending --> Running: kubelet syncPod success
    Running --> Succeeded: all containers exited 0
    Running --> Failed: any container exited non-zero
    Running --> Running: container restart (RestartPolicy)
    Running --> Pending: kubelet evicts
    Pending --> Failed: scheduling rejected (Unschedulable + PostFilter denied)
    Failed --> [*]
    Succeeded --> [*]

Phase strings are Pending, Running, Succeeded, Failed, Unknown. The richer state lives in Pod.Status.Conditions (PodScheduled, PodReady, Initialized, ContainersReady, DisruptionTarget, PodReadyToStartContainers).

Containers within a Pod

Three categories:

• spec.initContainers — run sequentially before regular containers. A Pod is Initialized when every init container has exited 0.
• spec.containers — the regular containers, run in parallel. A Pod is ContainersReady when every container's readiness probe passes.
• spec.ephemeralContainers — added at runtime via the /ephemeralcontainers subresource for debugging. They share the Pod's namespaces but have no resource requirements.

A recent feature adds sidecar init containers — init containers with restartPolicy: Always that keep running alongside regular containers, providing the long-requested "real sidecar" pattern.

Resource model

spec.containers[].resources carries requests (used by the scheduler for fit decisions) and limits (enforced by the runtime). The classifier in pkg/apis/core/v1/helper/qos/qos.go derives a Pod's QoS class:

• Guaranteed — every container has both requests and limits, and they're equal for CPU and memory.
• Burstable — at least one container has requests/limits, but not Guaranteed.
• BestEffort — no container has any requests or limits.

QoS class drives eviction priority: BestEffort goes first, Guaranteed last.

Scheduling-related fields

• spec.nodeName — bound Node. The scheduler patches this.
• spec.nodeSelector — simple equality-based node match.
• spec.affinity.nodeAffinity — richer node match (required + preferred).
• spec.affinity.podAffinity / podAntiAffinity — co-locate or anti-co-locate with other Pods.
• spec.topologySpreadConstraints — spread across topology domains.
• spec.tolerations — taints the Pod is willing to ignore.
• spec.priorityClassName / spec.priority — preemption priority.
• spec.schedulerName — which profile to use (default: default-scheduler).
• spec.schedulingGates — opt-in pause point until a gate is removed.
• spec.resourceClaims (DRA) — references to ResourceClaim objects.

Network identity

Each Pod gets a unique IP from the cluster's pod CIDR (allocated by the CNI plugin). DNS records for the Pod are added by CoreDNS:

• <pod-name>.<svc>.<ns>.svc.<cluster-domain> if the Pod is part of a Service with publishNotReadyAddresses or via headless Service
• <pod-ip>.<ns>.pod.<cluster-domain> (deprecated)

spec.hostname and spec.subdomain let users opt into a custom DNS name.

Validation highlights

pkg/apis/core/validation/validation.go is the single largest validation file in the repo. The Pod validator alone enforces:

• Container names are unique within a Pod.
• Volume mounts reference declared volumes.
• Resource requests do not exceed limits.
• Pod-level resource constraints (cgroup v2 only) sum to ≤ container totals.
• Probes and lifecycle hooks have valid handlers.
• Init container start order is well-defined.
• Restricted-mode rejects privileged/HostPath/HostNetwork/HostPID/HostIPC unless allowed by Pod Security.

Where each component touches a Pod

Component	Operation
Scheduler	Read all Pods, write spec.nodeName (and status conditions)
kubelet	Watch Pods on its node, read spec.*, write status.*
Controllers (Deployment/RS/Job/etc.)	Create / delete Pods owned by their resource
kube-proxy	Read Pods only insofar as they are Service endpoints (via EndpointSlice)
kube-controller-manager (volume controllers)	Watch Pods to track PV/PVC binding
HPA controller	Read Pods to compute current utilization
GC controller	Delete Pods when their owner goes away

Key source files

File	Purpose
staging/src/k8s.io/api/core/v1/types.go	Public Pod type
pkg/apis/core/validation/validation.go	Pod validation
pkg/registry/core/pod/strategy.go	Pod REST strategy
pkg/registry/core/pod/storage/storage.go	Pod storage and subresources
pkg/kubelet/pod_workers.go	Pod lifecycle state machine
pkg/scheduler/schedule_one.go	The scheduling cycle