[보충 강의] 파드(Pod) 디버깅 하는 방법

JSCODE 박재성

2026. 03. 30.

✅ 파드(Pod)가 정상적으로 실행되지 않았을 때

1. 매니페스트 파일 생성하기
nginx-pod.yaml

apiVersion: v1 # Pod를 생성할 때는 v1이라고 기재한다. (공식 문서)
kind: Pod # Pod를 생성한다고 명시
metadata:
  name: nginx-pod # Pod에 이름 붙이는 기능
spec:
  containers:
    - name: nginx-container # 생성할 컨테이너의 이름
      image: nginx:1.26.4 # 컨테이너를 생성할 때 사용할 Docker 이미지
      ports:
        - containerPort: 80 # 해당 컨테이너가 어떤 포트를 사용하는 지 명시적으로 표현

2. 파드 생성하기

$ kubectl apply -f nginx-pod.yaml
$ kubectl get pods # 파드가 잘 생성됐는 지 파드 조회해보기



파드를 관리하고 생성하다보면 위와 같이 파드 생성에 실패하는 경우가 종종 생긴다. 위의 출력값을 보면 STATUS가 ErrImagePull인걸 보고 에러가 발생했음을 짐작할 수 있다. 하지만 구체적인 에러 메시지가 아니기에 STATUS만 보고 문제점을 단번에 알아차리기 어려운 경우가 종종 있다. 어떻게 에러 메시지를 구체적으로 확인하는 지 알아보자.

3. 에러 메시지 확인하기

# kubectl describe pods [파드명]
$ kubectl describe pods nginx-pod # nginx-pod 파드의 세부 정보 조회

✅ 파드(Pod)의 로그를 확인하고 싶을 때

1. 매니페스트 파일 수정하기
nginx-pod.yaml

apiVersion: v1 # Pod를 생성할 때는 v1이라고 기재한다. (공식 문서)
kind: Pod # Pod를 생성한다고 명시
metadata:
  name: nginx-pod # Pod에 이름 붙이는 기능
spec:
  containers:
    - name: nginx-container # 생성할 컨테이너의 이름
      image: nginx:1.26.2 # 컨테이너를 생성할 때 사용할 Docker 이미지
      ports:
        - containerPort: 80 # 해당 컨테이너가 어떤 포트를 사용하는 지 명시적으로 표현

2. 변경사항 적용시키기

$ kubectl apply -f nginx-pod.yaml

 

2. 파드의 로그 확인하기

# kubectl logs [파드명]
$ kubectl logs nginx-pod # 파드 로그 확인하기

✅ 파드(Pod)에 접속하고 싶을 때

# kubectl exec -it [파드명] -- bash
$ kubectl exec -it nginx-pod -- bash

# kubectl exec -it [파드명] -- sh
$ kubectl exec -it nginx-pod -- sh

• 도커에서 컨테이너로 접속하는 명령어(docker exec -it [컨테이너 ID] bash)와 비슷하다.

• 컨테이너 종류에 따라 컨테이너 내부에 bash가 설치되어 있을 수도 있고, sh가 설치되어 있을 수도 있다. 만약 bash가 설치되어 있지 않은데 $ kubectl exec -it nginx-pod -- bash 명령어를 입력하면 에러가 뜨면서 컨테이너로 접속이 안 된다. 그럴 때는 $ kubectl exec -it nginx-pod -- sh으로 접속을 시도해보자.