[Kubernetes] Pod의 상태와 Lifecycle

 

Pod의 Lifecycle과 상태 대해 정리한 문서 (kubernetes 1.32 기준)

 

Pod 상태

Pod는 Kubernets에서의 최소 배포 단위로, 하나의 Pod 내부에 여러 컨테이너를 포함할 수 있다. 따라서 Pod의 상태는 Pod 내 모든 컨테이너의 상태에 의해 결정된다.

 

Pod의 상태 정보는 Pod 조회 시 STATUS 값에서 확인할 수 있다.

NAMESPACE   NAME    READY   STATUS    RESTARTS   AGE
default     pod     1/1     Running   0          2d9h

 

여기서의 STATUS는 사용자가 알기 쉽도록 나타내는 필드이며, 실제로 Kubernetes에서 Pod가 갖는 상태는 PodStatus 객체의 필드인 phase의 값으로 나타낸다.

 

좀 더 자세하게 말하자면, phase는 Kubernetes API에서 정의된 Pod의 요약된 상태이다.

 

예를 들어, STATUS에는 CrashLoopBackOff, Terminating, Running 등 사람이 Pod 상태를 (비교적) 알기 쉽게 표시된다.

NAMESPACE               NAME               READY   STATUS             RESTARTS   AGE
alessandras-namespace   alessandras-pod    0/1     CrashLoopBackOff   200        2d9h

 

하지만 실제 Pod가 갖는 상태 값은 아래 다섯 가지이다.

• https://v1-32.docs.kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/

Pod Lifecycle

Pod의 단계	설명
Pending	Pod가 K8S 클러스터에 의해 승인되었지만, 하나 이상의 컨테이너가 아직 시작되지 않음 Pod가 노드에 배치되기 전이나, 컨테이너의 이미지를 다운로드 하는 중일 때
Running	Pod가 노드에 배치 되었고 모든 컨테이너가 시작됨 최소 하나의 컨테이너가 실행 중이거나 시작 또는 재시작 중인 상태
Succeeded	Pod의 모든 컨테이너가 성공적으로 종료되었고 다시 시작되지 않는 경우 컨테이너가 Exit 0으로 종료 됨
Failed	Pod에 있는 모든 컨테이너가 종료되었으나, 하나 이상의 컨테이너가 실패함  컨테이너가 Exit 0이 아닌 상태로 종료 됨(또는 시스템에 의해 종료 됨)
Unknown	클러스터가 Pod의 상태를 확인할 수 없는 상태 주로 Pod가 노드와 통신하는데 오류 발생했을 때

 

실제로 Kubernetes 소스 코드에서도 Pod phase가 아래와 같이 const로 선언되어 있는 것을 확인할 수 있다.

• https://github.com/kubernetes/kubernetes/blob/59526cd4867447956156ae3a602fcbac10a2c335/pkg/apis/core/types.go#L2915

kubernetes/pkg/apis/core/types.go at 59526cd4867447956156ae3a602fcbac10a2c335 · kubernetes/kubernetes

...
type PodPhase string

// These are the valid statuses of pods.
const (
	// PodPending means the pod has been accepted by the system, but one or more of the containers
	// has not been started. This includes time before being bound to a node, as well as time spent
	// pulling images onto the host.
	PodPending PodPhase = "Pending"
	// PodRunning means the pod has been bound to a node and all of the containers have been started.
	// At least one container is still running or is in the process of being restarted.
	PodRunning PodPhase = "Running"
	// PodSucceeded means that all containers in the pod have voluntarily terminated
	// with a container exit code of 0, and the system is not going to restart any of these containers.
	PodSucceeded PodPhase = "Succeeded"
	// PodFailed means that all containers in the pod have terminated, and at least one container has
	// terminated in a failure (exited with a non-zero exit code or was stopped by the system).
	PodFailed PodPhase = "Failed"
	// PodUnknown means that for some reason the state of the pod could not be obtained, typically due
	// to an error in communicating with the host of the pod.
	// Deprecated in v1.21: It isn't being set since 2015 (74da3b14b0c0f658b3bb8d2def5094686d0e9095)
	PodUnknown PodPhase = "Unknown"
)
...

 

PodStatus

phase는 Kubernetes API 문서(PodStatus)에서 자세히 확인할 수 있다. 아래 표는 PodStatus의 일부 필드들이다.

• https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podstatus-v1-core

Kubernetes API Reference Docs

PodStatus 필드 명	데이터 타입	설명
phase	string	Pod의 수명주기 단계(phase) 수명 주기 중 어디에 있는지에 대한 개략적인 요약 Pending, Running, Succeeded, Failed, Unknown의 값을 가질 수 있음
conditions	PodCondition array	Pod의 현재 서비스 상태
containerStatuses	ContainerStatus array	Pod 내 컨테이너들의 상태
startTime	Time	Kubelet이 Pod를 인식한 시각
...	...	...

 

테스트 용 pod를 띄워, kubectl 명령어로 확인해보면 아래와 같은 값들을 확인할 수 있다.

# 테스트 용 nginx-test pod 확인
$ kubectl get po nginx-test -o yaml

...

status:
  conditions:
  - lastProbeTime: null
    lastTransitionTime: "2025-04-29T04:33:27Z"
    status: "True"
    type: PodReadyToStartContainers
  - lastProbeTime: null
    lastTransitionTime: "2025-04-29T04:33:19Z"
    status: "True"
    type: Initialized
  - lastProbeTime: null
    lastTransitionTime: "2025-04-29T04:33:27Z"
    status: "True"
    type: Ready
  - lastProbeTime: null
    lastTransitionTime: "2025-04-29T04:33:27Z"
    status: "True"
    type: ContainersReady
  - lastProbeTime: null
    lastTransitionTime: "2025-04-29T04:33:19Z"
    status: "True"
    type: PodScheduled
  containerStatuses:
  - containerID: containerd://02f72c2c01345dae3a88e16b4351c7b712e9d919f28e56775607147058942b68
    image: docker.io/library/nginx:latest
    imageID: docker.io/library/nginx@sha256:c15da6c91de8d2f436196f3a768483ad32c258ed4e1beb3d367a27ed67253e66
    lastState: {}
    name: nginx-test
    ready: true
    restartCount: 0
    started: true
    state:
      running:
        startedAt: "2025-04-29T04:33:26Z"
    volumeMounts:
    - mountPath: /var/run/secrets/kubernetes.io/serviceaccount
      name: kube-api-access-snslr
      readOnly: true
      recursiveReadOnly: Disabled
  phase: Running
  startTime: "2025-04-29T04:33:19Z"

...

 

API 문서와 kubectl 명령어 결과 값을 통해, status.phase 값 이외에도 status.conditions에서 Pod에 대한 세부적인 상태를 확인할 수 있는 것을 알 수 있다.

 

PodCondition

앞서 확인한 것처럼, PodStatus.phase는 Pod의 종합적인 상태에 대한 요약 정보를 나타낸다. 하지만 phase 만으로는 Pod의 상세 정보를 알기 어렵다.

 

그래서 PodStatus에는 phase 이외에도 세부적인 정보를 기술하고 있는 conditions 필드가 있다. 해당 필드의 데이터 타입은 PodCondition 타입의 배열이다.

 

API 문서에는 PodCondition을 다음과 같이 기술하고 있다.

• https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.32/#podcondition-v1-core

Kubernetes API Reference Docs

PodCondition 필드 명	데이터 타입	설명
lastProbeTime	Time	condition을 마지막으로 확인(probe)한 시간
lastTransitionTime	Time	condition이 마지막으로 변경된 시간
message	string	lastTransition에 대한 Human-readable 메시지
reason	string	lastTransition에 대한 간단한 이유
status	string	현재 condition (True, False, Unknown)
type	string	condition의 종류 (Ready, Initialized, ContainersReady, PodScheduled, PodReadyToStartContainers)

 

PodCondition의 type 종류(값)는 아래와 같다.

• https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#pod-conditions

Pod Lifecycle

PodCondition.type 필드의 값	설명
PodScheduled	Pod가 노드에 스케줄링 됨
PodReadyToStartContainers	(v1.32 기준 베타 기능) Pod 샌드박스 생성 및 네트워킹 구성 됨
ContainersReady	Pod 내 모든 컨테이너가 준비 됨
Initialized	모든 init 컨테이너가 완료 됨
Ready	Pod가 request를 처리할 수 있는 상태

 

Kubernetes 소스코드에서 확인하면 아래와 같다.

• https://github.com/kubernetes/kubernetes/blob/59526cd4867447956156ae3a602fcbac10a2c335/pkg/apis/core/types.go#L2939

kubernetes/pkg/apis/core/types.go at 59526cd4867447956156ae3a602fcbac10a2c335 · kubernetes/kubernetes

...
// PodConditionType defines the condition of pod
type PodConditionType string

// These are valid conditions of pod.
const (
	// PodScheduled represents status of the scheduling process for this pod.
	PodScheduled PodConditionType = "PodScheduled"
	// PodReady means the pod is able to service requests and should be added to the
	// load balancing pools of all matching services.
	PodReady PodConditionType = "Ready"
	// PodInitialized means that all init containers in the pod have started successfully.
	PodInitialized PodConditionType = "Initialized"
	// ContainersReady indicates whether all containers in the pod are ready.
	ContainersReady PodConditionType = "ContainersReady"
	// DisruptionTarget indicates the pod is about to be terminated due to a
	// disruption (such as preemption, eviction API or garbage-collection).
	DisruptionTarget PodConditionType = "DisruptionTarget"
)

// PodCondition represents pod's condition
type PodCondition struct {
	Type   PodConditionType
	Status ConditionStatus
	// +optional
	LastProbeTime metav1.Time
	// +optional
	LastTransitionTime metav1.Time
	// +optional
	Reason string
	// +optional
	Message string
}
...

 

결국 PodStatus는 Pod의 전체적인 상태를 나태내는 상위 구조이며, 그 하위 필드인 PodStatus.conditions에 포함된 PodCondition은 Pod의 세부적인 상태를 나타낸다는 것을 알 수 있다.

 

 

Pod Lifecycle

Kubernetes API 문서와 소스 코드 등을 통해 Kubernetes(kubelet)가 Pod의 상태를 정의 및 추척한다는 것을 알 수 있었다. 즉, Kubernetes는 Pod의 Lifecycle을 관리한다고 할 수 있다.

https://bobcares.com/blog/kubernetes-pod-states/

 

Pod의 Lifecycle을 간략히 살펴 보면 다음과 같다.

 

Pod 객체가 생성된 직후, 노드에 아직 스케줄 되지 않았거나 컨테이너 이미지를 다운로드 중일 때는 Pod가 Pending 상태가 된다.

 

Pod가 노드에 스케줄되면 PodCondition 객체에서 type: PodScheduled의 status 값이 True로 설정되며, Init 컨테이너가 모두 완료되면 type: Initialized의 status도 True가 된다. 이러한 조건들이 충족되고 메인 컨테이너들이 실행되면, Pod는 Running 상태로 전환된다.

 

이후 모든 컨테이너들이 성공적으로 종료되면 Succeeded를, 하나 이상의 컨테이너가 비정상적으로 종료되면 Failed 상태가 된다.

 

 

이와 같이 정리해 보면, Pod의 각 Lifecycle 단계는 전체적인 상태 변화(phase)로 표현되며, 이러한 상태는 결국 Pod 내부의 컨테이너들의 상태에 따라 결정된다는 것을 알 수 있다.

 

그러니 이번에는 컨테이너의 상태에 대해 알아보...려고 했으나,

생각보다 내용이 길어져 따로 정리해야겠다.

 

---

EOF.