워크로드 문제 해결

소개

배포가 항상 계획대로 진행되는 것은 아닙니다. 문제가 발생하면 반복해서 적용할 수 있는 문제 해결 방법이 필요합니다.

이 실습에서는 **"이미지가 사라진 사건"**을 해결합니다.

Kubernetes 에서 문제 해결은 일반적으로 객체 상태를 확인하고, 이벤트를 살펴본 다음, 더 자세히 검사하는 순서로 진행합니다. 이 실습에서는 이러한 근거 기반 작업 흐름에 집중합니다.

다음 작업을 수행합니다.

사건 현장 만들기: 의도적으로 문제가 있는 Pod 를 배포합니다.
조사하기: "쌍안경"(get) 을 사용해 문제가 있음을 확인합니다.
증거 수집하기: "돋보기"(describe) 를 사용해 근본 원인을 찾습니다.
사건 해결하기: 구성을 수정하고 애플리케이션이 복구되는지 확인합니다.

문제가 있는 Pod 만들기

의도적인 오타가 포함된 Pod 를 배포하면서 시작합니다. 이는 존재하지 않는 이미지를 지정하는 일반적인 오류를 재현합니다.

이 작업은 Kubernetes 가 많은 매니페스트를 받아들이지만, 그 문제는 나중에야 발견될 수 있다는 점을 보여줍니다. YAML 파일은 문법적으로 올바르면서도 실제 운영 관점에서는 잘못된 상태일 수 있습니다. 따라서 문제를 해결할 때는 "객체가 승인되었는가?"와 "워크로드가 실제로 정상적으로 시작되었는가?"를 구분해야 합니다.

broken-pod.yaml이라는 파일을 만듭니다.

nano broken-pod.yaml

다음 내용을 붙여 넣습니다. 의심스러운 이미지 태그 wrongtag123을 확인합니다.

apiVersion: v1
kind: Pod
metadata:
  name: broken-pod
spec:
  containers:
    - name: nginx
      image: nginx:wrongtag123

저장하고 종료합니다 (Ctrl+X, Y, Enter).

Pod 를 배포합니다.

kubectl apply -f broken-pod.yaml

YAML 형식이 올바르기 때문에 Kubernetes 는 파일을 받아들입니다. 아직 "사건"은 감지되지 않았습니다.

오류 상태 확인하기

이제 배포한 Pod 의 상태를 확인합니다. 쌍안경으로 현장을 살펴보는 것과 같습니다.

ErrImagePull 및 ImagePullBackOff와 같은 상태는 증상이지 최종 원인이 아닙니다. 이러한 상태는 다음에 어디를 조사해야 하는지 알려 줍니다. 효과적인 문제 해결에서는 상태 출력을 전체 진단 결과가 아니라 첫 번째 단서로 활용합니다.

default 네임스페이스의 Pod 를 확인합니다.

kubectl get pods

처음에는 ContainerCreating이 표시될 수 있지만, 몇 초 후에는 ImagePullBackOff 또는 **ErrImagePull**로 변경될 가능성이 높습니다.

ImagePullBackOff는 Kubernetes 에서 다음과 같은 의미입니다. "이 이미지를 가져오려고 했지만 실패했습니다. 잠시 물러나서 (대기한 후) 나중에 다시 시도하겠습니다."

이 결과로 피해자 (Pod) 가 정상 상태가 아님을 확인할 수 있습니다.

이벤트 검사하기

실패했다는 사실은 알지만, 왜 실패했는지는 아직 모릅니다. 원인을 알아내려면 더 자세히 살펴봐야 합니다.

kubectl describe 명령은 돋보기 역할을 합니다. 특정 리소스의 내부 이벤트와 로그를 보여 줍니다.

특히 Events 섹션이 중요합니다. 이 섹션에는 스케줄러와 kubelet 같은 Kubernetes 구성 요소가 남긴 짧은 처리 기록이 보존됩니다. 초보자가 이벤트를 읽지 않고 무작위로 수정부터 시도하면, 잘못된 문제를 해결하느라 시간을 낭비하기 쉽습니다.

문제가 있는 Pod 를 검사합니다.

kubectl describe pod broken-pod

많은 데이터가 출력됩니다. 맨 아래까지 스크롤하여 Events 섹션을 찾습니다.

다음과 비슷한 내용이 표시되어야 합니다.

Type     Reason     Message
----     ------     -------
Normal   Pulling    Pulling image "nginx:wrongtag123"
Warning  Failed     Failed to pull image "nginx:wrongtag123": manifest unknown
Warning  Failed     Error: ErrImagePull

manifest unknown이라는 메시지가 결정적인 단서입니다. 이미지가 저장된 Docker registry 에 nginx:wrongtag123에 대한 기록이 없다는 뜻입니다.

사건 해결: 이미지 태그가 잘못되었습니다.

Pod 수정하기

이제 근본 원인을 확인했으므로 문제를 수정할 수 있습니다.

이 마지막 단계에서는 더 일반적인 작업 방식도 보여 줍니다. 관찰하고, 증거를 바탕으로 가설을 세우고, 한 가지 대상만 수정한 다음, 복구 여부를 확인합니다. 한 번에 여러 항목을 추측으로 수정하는 것보다 이와 같은 체계적인 반복 작업이 더 안정적입니다.

broken-pod.yaml 파일을 다시 엽니다.

nano broken-pod.yaml

"오타"를 수정합니다. nginx:wrongtag123을 nginx로 변경합니다. nginx는 기본적으로 유효한 이미지인 nginx:latest를 사용합니다.

apiVersion: v1
kind: Pod
metadata:
  name: broken-pod
spec:
  containers:
    - name: nginx
      image: nginx

저장하고 종료합니다.

수정 내용을 적용합니다. Kubernetes 는 새 정보를 사용해 기존 Pod 를 업데이트할 수 있습니다.

kubectl apply -f broken-pod.yaml

이제 복구 과정을 확인합니다.

kubectl get pods -w

상태가 ImagePullBackOff에서 Running으로 변경되는 것을 확인할 수 있어야 합니다.

감시를 중지하려면 Ctrl+C를 누릅니다.

잘했습니다, 탐정님! 오류를 찾아내고 서비스를 성공적으로 복구했습니다.

요약

이 실습에서는 Kubernetes 문제 해결의 기본 작업 흐름을 배웠습니다.

관찰: kubectl get pods를 실행하여 문제가 발생한 워크로드를 확인합니다.
검사: kubectl describe pod를 사용하여 이벤트 로그를 보고 오류 메시지를 찾습니다.
수정: YAML 매니페스트를 업데이트하고 수정 내용을 적용합니다.

이러한 Get, Describe, Fix 과정은 Kubernetes 를 사용하면서 마주치는 배포 문제의 90% 를 해결하는 데 도움이 됩니다.