Demystifying Kubernetes Pods: From YAML to Full Lifecycle

SREWorks, Alibaba's cloud‑native operations platform, launches a "Kubernetes Resource Orchestration Series" that starts from the basic Pod YAML and progressively explains core concepts.

Pod Overall Structure

A Pod YAML is divided into four main parts: Resource, Object, Spec, and Status.

Resource : defines the resource type and API version, required for REST API access.

Object : contains metadata that uniquely identifies the resource.

Spec / Status : Spec describes the desired state; Status reflects the current state.

Resource – REST API

Kubernetes resources are scoped as Namespace or Cluster resources. Pods belong to Namespace scope, and their REST API endpoints follow a predictable pattern.

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: default

From this YAML the following REST API paths are derived: /api/{apiVersion}/{kind}: list all resources of this kind. /api/{apiVersion}/namespace/{namespace}/{kind}/: list resources of this kind in a specific namespace. /api/{apiVersion}/namespace/{namespace}/{kind}/{name}: access a specific resource.

/api/{apiVersion}/namespace/{namespace}/{kind}/{name}/{subresource}

: operate on a sub‑resource.

Object (Metadata)

Metadata provides common fields used by all Kubernetes objects.

namespace : the logical tenant for the resource.

name : the instance name.

uid : a unique identifier that distinguishes deleted and recreated objects.

resourceVersion : internal version used for watch mechanisms.

creationTimestamp : creation time of the instance.

deleteTimestamp : deletion time, relevant for graceful termination.

ownerReferences : links the object to its owning controller (e.g., a ReplicaSet owns a Pod).

labels : key‑value pairs used for service discovery and selector matching.

annotations : arbitrary metadata, often consumed by external systems (e.g., k8s.aliyun.com/pod-eni="true" for network plugins).

Labels and label selectors drive the relationship between Deployments, ReplicaSets, and Pods, while ownerReferences enable garbage collection of dependent resources.

Spec (Specification)

Spec defines the desired state of a Pod and includes its lifecycle phases.

Pending : the Pod is not yet scheduled.

Creating : kubelet creates the Pod based on the spec.

Running : at least one container is running and health checks start.

Terminating : the Pod is being deleted.

Terminated : the Pod has been fully removed.

Resource strategies such as node resource requests, node affinity, and taints determine where a Pod can be scheduled. For example, a node affinity rule topology.kubernetes.io/region: cn-hangzhou or a taint‑toleration pair controls placement.

Status

Status reports the current observed state of the Pod.

status:
  conditions:
  - type: Ready
    status: "True"
  - type: Initialized
    status: "True"
  containerStatuses:
  - name: testdemo
    ready: true
    restartCount: 0
  hostIP: 21.1.96.23
  podIP: 10.11.17.172
  phase: Running
  qosClass: Guaranteed
  startTime: "2022-07-05T09:16:07Z"

Key fields include conditions (detailed status reports), containerStatuses (per‑container state), hostIP , podIP , phase (overall lifecycle stage), qosClass (resource guarantee level), and startTime .

By dissecting these four sections—Resource, Object, Spec, and Status—we gain a clear understanding of where a Pod originates, how it is scheduled, what it does, and how its state is reported, laying the foundation for deeper cloud‑native orchestration topics.