Demystifying Kubernetes Pods: From YAML Basics to Full Lifecycle

As cloud‑native operations platforms become more widely used, many users still have questions about the underlying concepts of Kubernetes. This article, “Kubernetes Resource Orchestration,” starts from the basic Pod YAML and progressively explains the Resource, Object, Spec, and Status sections to clarify common doubts.

1. Pod Overall Structure

Pod YAML consists of four main parts: Resource, Object, Spec, and Status.

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

Object : metadata that uniquely identifies the resource.

Spec / Status

Spec : defines the desired state, including user‑provided configuration, default values, and values set by surrounding systems (scheduler, HPA, etc.).

Status : reflects the current observed state, allowing the pod to converge toward the desired state.

2. Resource – REST API

Kubernetes resources are scoped as Namespace or Cluster resources; Pods belong to the Namespace scope. The REST API for a Pod includes the apiVersion, kind, namespace, and name.

<code>apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  namespace: default</code>

From this YAML we can extract:

group:

api

apiVersion:

v1

kind:

Pod

name:

test-pod

namespace:

default

Typical API patterns are:

/api/{apiVersion}/{kind}

: list of all resources of that kind.

/api/{apiVersion}/namespace/{namespace}/{kind}/

: list of resources of that kind in the specified namespace.

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

: a specific resource.

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

: sub‑resource operations.

Defining the HTTP method completes a full REST API call.

3. Object (Metadata)

Object metadata contains fields that are common to all Kubernetes resources.

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.

deleteTimestamp : deletion time (used later in the pod lifecycle).

ownerReferences : links the pod to its owning controller; owners cannot cross namespaces.

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

annotations : arbitrary metadata for external systems (e.g., network plugins).

label & labelSelector

Deployments use a label selector (e.g.,

app=taihao-app-cluster

) and a pod‑template hash label to select matching ReplicaSets, which in turn select Pods; Services also use label selectors to discover Pods.

Owner & GC (Garbage Collection)

When a Pod’s

metadata.ownerReferences

points to a ReplicaSet, and the ReplicaSet points to a Deployment, deleting the Deployment triggers garbage collection of the owned ReplicaSet and Pods.

Deploy & ReplicaSet

<code>apiVersion: apps/v1
kind: ReplicaSet
metadata:
  generation: 1
  labels:
    app: testdemo
    pod-template-hash: bcd889947
  name: testdemo-bcd889947
  namespace: taihao
  ownerReferences:
  - apiVersion: apps/v1
    blockOwnerDeletion: true
    controller: true
    kind: Deployment
    name: testdemo
    uid: 1dddc849-c254-4cf5-aec8-9e1c2b5e65af
spec:
  replicas: 1
  selector:
    matchLabels:
      app: testdemo
      pod-template-hash: bcd889947
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: testdemo
        pod-template-hash: bcd889947
    spec:
      containers:
      - args:
        - -c
        - sleep 1000000
        command:
        - sh
        image: centos:7
        imagePullPolicy: IfNotPresent
        name: testdemo
status:
  fullyLabeledReplicas: 1
  observedGeneration: 1
  replicas: 1</code>

Key fields:

replicas : desired number of Pods.

selector : label selector that matches Pods.

template : Pod template used to create Pods.

status : current management state of the Pods.

4. Spec (Specification)

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

Pending : pod is not yet scheduled.

Creating : kubelet has discovered the pod and is creating it.

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

Terminating : pod is being deleted.

Terminated : pod has been destroyed.

During scheduling, the scheduler evaluates the pod’s YAML, matches node resources, and updates

spec.nodeName

with the chosen node.

Resource strategy defines the CPU and memory requirements; node‑affinity and pod‑affinity rules filter nodes based on labels such as

topology.kubernetes.io/region: cn-hangzhou

or custom labels like

disk-type=aaa

.

Creating a Pod involves several steps: configuring cgroups, preparing volumes and image secrets, creating a pause container for network setup, and finally launching the application containers.

<code>spec:
  containers:
  - image: testdemo:v1
    imagePullPolicy: Always
    name: test-config
  imagePullSecrets:
  - name: image-regsecret</code>

postStart can run a command (e.g.,

/bin/sh -c "sleep 5"

) or an HTTP request to perform initialization tasks.

<code>containers:
  - image: testdemo:v1
    lifecycle:
      postStart:
        exec:
          command:
          - /bin/sh
          - -c
          - sleep 5</code>

When a Pod is Running, kubelet performs health checks:

readiness : determines if the pod is ready to receive traffic.

liveness : determines if the pod should be restarted.

readinessGate : an extensible condition evaluated by third‑party components.

<code>spec:
  readinessGates:
  - conditionType: TestPodReady
  containers:
  - image: testdemo:v1
    livenessProbe:
      failureThreshold: 3
      initialDelaySeconds: 45
      periodSeconds: 5
      tcpSocket:
        port: 8080
      timeoutSeconds: 1
    readinessProbe:
      httpGet:
        path: /actuator/health
        port: 8989
        scheme: HTTP
      initialDelaySeconds: 25
      periodSeconds: 3
      timeoutSeconds: 1</code>

Readiness defaults to false (pod is unhealthy) until the probe succeeds; liveness defaults to true and only triggers a restart when it fails.

5. Status

Status provides a detailed view of the pod’s current condition.

<code>status:
  conditions:
  - lastProbeTime: null
    lastTransitionTime: "2022-07-05T09:16:07Z"
    status: "True"
    type: Ready
  containerStatuses:
  - containerID: containerd://xxxxx
    image: docker.io/library/testdemo:v1
    name: zxtest
    ready: true
    restartCount: 0
    state:
      running:
        startedAt: "2022-07-05T09:16:13Z"
  hostIP: 21.1.96.23
  phase: Running
  podIP: 10.11.17.172
  podIPs:
  - ip: 10.11.17.172
  qosClass: Guaranteed
  startTime: "2022-07-05T09:16:07Z"</code>

Key fields include:

conditions : detailed status reports, with

type: Ready

indicating overall health.

containerStatuses : status of each container.

hostIP and podIP/podIPs : network addresses.

phase : lifecycle phase (Pending, Running, Succeeded, Failed, Unknown).

qosClass : QoS tier (Guaranteed, Burstable, BestEffort).

startTime : pod creation time.

By dissecting the four sections of a Pod—Resource, Object, Spec, and Status—we gain a clear picture of where a Pod comes from in Kubernetes. Future articles will explore where it goes, highlighting the power of Kubernetes to orchestrate massive workloads on demand.