[CKA Ch-06] 트러블슈팅: 증상에서 출발해 kubelet과 로그까지 내려가는 순서

결론부터

1. 트러블슈팅은 증상에서 출발해 한 층씩 내려갑니다. kubectl get으로 상태 보기, kubectl describe의 Events 읽기, kubectl logs로 컨테이너 출력 보기, 노드에 ssh로 들어가 journalctl -u kubelet과 crictl 보기 순서입니다. 0절의 판단 표가 이 순서를 증상별로 정리한 것입니다.
2. kubeadm 클러스터의 컨트롤 플레인 구성요소(kube-apiserver, kube-controller-manager, kube-scheduler, etcd)는 /etc/kubernetes/manifests의 static Pod입니다. 매니페스트를 고치면 kubelet이 다시 띄웁니다. API 서버가 죽어 kubectl이 안 되면 노드에서 crictl ps -a와 crictl logs, 또는 /var/log/pods의 파일을 봅니다.
3. kubelet과 컨테이너 런타임은 systemd 서비스입니다. 노드가 NotReady이면 그 노드에서 systemctl status kubelet과 journalctl -u kubelet부터 봅니다. kubeadm이 쓰는 kubelet 설정 파일은 /var/lib/kubelet/config.yaml입니다.
4. kubectl top은 metrics-server(또는 Metrics API를 제공하는 다른 어댑터)가 있어야 동작합니다. --sort-by는 cpu와 memory만 받고 메모리 수치는 working set 기준입니다.
5. 재시작된 컨테이너의 이전 로그는 kubectl logs --previous로 봅니다. 멀티 컨테이너 Pod에서 -c를 빼면 오류 없이 기본 컨테이너의 로그가 나오니 Defaulted container 안내를 보면 -c를 붙입니다.

커리큘럼 원문(CNCF, CKA Curriculum v1.37)의 Troubleshooting 항목은 다섯 개이고 이 글의 1~5절이 차례로 대응합니다. 0절은 다섯 항목에 앞서 증상별 판단 표를 둡니다.

예시는 가상의 쇼핑몰입니다. 네임스페이스 shop에 주문 API(order-api), 결제(payment), 게시판(board)이 있습니다. Ch-00에서 정리한 후기들이 공통으로 꼽은 어려움이 트러블슈팅에서 시간을 잃은 것이었습니다. 그래서 이 글은 “어디부터 볼지”를 정하는 데 비중을 둡니다.

0. 증상에서 출발하는 판단 표

0-1. 첫 3분

어떤 과제든 처음 세 명령은 같습니다.

1
kubectl get pod -n <ns> -o wide          # STATUS, RESTARTS, 노드
2
kubectl describe pod <pod> -n <ns>       # 맨 아래 Events
3
kubectl get events -n <ns> --sort-by=.metadata.creationTimestamp

이벤트는 네임스페이스 단위입니다(Debug Running Pods 문서). 다른 네임스페이스는 -n, 전체는 -A를 줍니다.

0-2. 증상별 판단 표

0-3. Pending

Debug Pods 문서는 Pending을 “노드에 스케줄할 수 없는 상태”로 정의하고 원인으로 자원 부족과 hostPort 충돌을 듭니다. 시험에서 더 자주 보는 것은 Workloads 영역과 겹치는 원인입니다. nodeSelector의 라벨이 어느 노드에도 없거나, 노드에 테인트가 있는데 톨러레이션이 없거나, 쓰는 PVC가 Pending인 경우입니다. PVC가 원인이면 Ch-05의 PVC 바인딩 점검으로 넘어갑니다.

1
kubectl describe pod order-api-xxxx -n shop | sed -n '/Events/,$p'
2
kubectl describe node <노드> | grep -A5 Taints
3
kubectl get node --show-labels

0-4. ImagePullBackOff

Images 문서는 이유로 잘못된 이미지 이름과 imagePullSecret 없이 비공개 레지스트리에서 받으려 한 경우를 듭니다. Debug Pods 문서의 점검 목록은 이미지 이름이 맞는지, 레지스트리에 있는지, 직접 pull해서 받아지는지 세 가지입니다.

1
kubectl -n shop get pod order-api-xxxx -o jsonpath='{.spec.containers[*].image}'
2
kubectl -n shop set image deployment/order-api order-api=nginx:1.27   # 이미지 이름을 고칠 때
3
sudo crictl pull nginx:1.27                                            # 노드에서 직접 받아 보기

0-5. Terminating에 멈춤

Debug Pods 문서는 흔한 원인으로 finalizer와 finalizer 제거를 막는 admission 웹훅을 듭니다. pods의 UPDATE를 대상으로 하는 웹훅 설정이 있는지 봅니다.

1
kubectl get validatingwebhookconfigurations,mutatingwebhookconfigurations
2
kubectl -n shop get pod board-xxxx -o jsonpath='{.metadata.finalizers}'

0-6. Running인데 기대와 다르게 동작

Pod 명세에 오타가 있으면 그 키가 조용히 무시될 수 있습니다. command를 commnd로 쓰면 Pod는 만들어지지만 의도한 명령을 쓰지 않습니다. Debug Pods 문서는 kubectl apply --validate -f mypod.yaml로 다시 만들고 kubectl get pods/mypod -o yaml로 저장된 내용과 원본을 비교하라고 권합니다.

1. 클러스터와 노드

1-1. 노드 목록부터

Troubleshooting Clusters 문서의 첫 단계는 노드가 모두 등록됐고 Ready인지 보는 것입니다.

1
kubectl get nodes
2
kubectl describe node <노드>
3
kubectl get node <노드> -o yaml

1-2. 노드 조건과 하트비트

Node Status 문서의 조건 표입니다.

kubelet은 kube-node-lease 네임스페이스의 Lease를 기본 10초마다, Node의 .status는 변화가 없으면 기본 5분마다 갱신합니다. Ready가 grace period보다 오래 Unknown이나 False이면 node.kubernetes.io/unreachable 또는 not-ready 테인트가 붙고 Pod의 기본 톨러레이션(300초)이 지나면 축출됩니다. kubelet을 멈춘 노드의 describe는 이렇게 나옵니다(kind v1.37.0 워커에서 확인).

1
Taints:             node.kubernetes.io/unreachable:NoExecute
2
                    node.kubernetes.io/unreachable:NoSchedule
3
...
4
  Ready                Unknown   ...   NodeStatusUnknown   Kubelet stopped posting node status.

Kubelet stopped posting node status.가 보이면 원인은 노드 쪽이니 그 노드로 들어갑니다. kind 워커 컨테이너를 멈췄을 때는 약 45초 안에 Unknown과 테인트가 붙었고 기본 톨러레이션 Pod는 약 300초 뒤 Terminating이 되어 노드가 돌아올 때까지 그 상태로 남았습니다.

kind 워커의 evictionHard에 가용량보다 큰 memory.available을 넣어 압박을 만들면 노드에 MemoryPressure True ... KubeletHasInsufficientMemory와 node.kubernetes.io/memory-pressure:NoSchedule 테인트가 생겼습니다. 축출된 Pod의 메시지는 The node was low on resource: memory. Threshold quantity: ...이고 압박 중 kubelet이 다시 받는 BestEffort Pod는 Pod was rejected: The node had condition: [MemoryPressure].로 거절됐습니다. 둘 다 .status.reason은 Evicted인데 STATUS 열은 Error나 ContainerStatusUnknown이라 --field-selector status.phase=Failed로 찾습니다.

1-3. 노드 안에서 볼 것

시험 환경은 과제마다 지정된 호스트에 ssh로 들어가고 권한이 필요하면 sudo를 씁니다. ssh 안에서 다시 ssh할 수는 없습니다.

1
ssh <노드>
2
sudo systemctl status kubelet
3
sudo journalctl -u kubelet --no-pager | tail -50
4
sudo systemctl restart kubelet
5
sudo systemctl enable --now kubelet      # 꺼져 있고 부팅 시 자동 시작도 꺼져 있을 때

kubeadm이 kubelet에 넘기는 파일은 Configuring each kubelet in your cluster using kubeadm 문서에 있습니다.

systemd drop-in의 경로는 설치 방법마다 다르니 systemctl cat kubelet으로 실제 위치를 봅니다. pkgs.k8s.io 패키지 설치에서는 /usr/lib/systemd/system/kubelet.service.d/10-kubeadm.conf였습니다. drop-in을 고쳤으면 systemctl daemon-reload 뒤 systemctl restart kubelet을 하고 kubectl get nodes로 Ready를 확인합니다.

1-4. kubelet 설정 파일 오류와 인증서 만료

systemctl status kubelet이 activating (auto-restart)를 반복하면 kubelet이 시작 단계에서 죽고 있습니다. config.yaml의 들여쓰기를 망가뜨리면 journalctl -u kubelet에 이런 줄이 반복됩니다(kind v1.37.0, Lima VM kubeadm 1.37.1에서 확인).

1
"command failed" err="failed to load kubelet config file, path: /var/lib/kubelet/config.yaml, error: ... yaml: line 36: mapping values are not allowed in this context"

노드 안에서 볼 순서입니다. 명령은 노드에서 sudo로 실행합니다.

버전에 따른 원인도 있습니다. 1.35부터 kubelet의 failCgroupV1 기본값이 true라 cgroup v1 노드에서는 기본으로 시작하지 않습니다(cgroups 문서). 스왑이 켜진 노드에서 기본 설정의 kubelet이 시작하지 않는 동작도 그대로입니다. 두 경우 모두 로그에 원인이 문장으로 남습니다.

인증서 쪽은 Certificate Management with kubeadm, Troubleshooting kubeadm 문서를 따릅니다.

• kubeadm은 kubelet 클라이언트 인증서를 자동 교체하게 설정합니다. /etc/kubernetes/kubelet.conf가 /var/lib/kubelet/pki/kubelet-client-current.pem을 가리키고 kubelet이 만료 전에 새 인증서를 받아 이 링크를 바꿉니다.
• 그래서 kubeadm certs check-expiration 목록에 kubelet.conf가 없고 kubeadm certs renew all도 이 인증서를 갱신하지 않습니다. 만료는 표 6번의 openssl로 직접 봅니다.
• 정상 subject는 O = system:nodes, CN = system:node:<노드 이름>이고 issuer는 클러스터 CA입니다. Node 인가자와 RBAC가 이 그룹과 이름으로 kubelet을 알아보므로 둘이 다르면 인증은 돼도 권한 오류가 납니다.
• “not yet valid”는 노드 시계가 인증서 시작 시각보다 이를 때도 나오니 date도 봅니다.

인증서가 만료되면 로그가 단계별로 바뀝니다(Lima VM kubeadm 1.37.1 단일 노드에서 시계를 옮겨 확인).

Troubleshooting kubeadm 문서의 복구 절차를 줄이면 이렇습니다.

1. 고장 난 노드에서 /etc/kubernetes/kubelet.conf와 /var/lib/kubelet/pki/kubelet-client*를 백업하고 지웁니다.
2. /etc/kubernetes/pki/ca.key가 있는 컨트롤 플레인 노드에서 새 kubeconfig를 만듭니다. server와 클러스터 이름은 원래 kubelet.conf에 맞춥니다.
3. 만든 파일을 고장 난 노드의 /etc/kubernetes/kubelet.conf로 복사하고 kubelet을 재시작합니다.
4. /var/lib/kubelet/pki/kubelet-client-current.pem이 다시 생기면 kubelet.conf의 client-certificate-data, client-key-data를 아래 두 줄로 바꿉니다.
5. kubelet을 다시 재시작하고 노드가 Ready인지 봅니다.

1
# 2번: 컨트롤 플레인 노드에서 (NODE는 고장 난 노드 이름)
2
sudo kubeadm kubeconfig user --org system:nodes --client-name system:node:$NODE > kubelet.conf

1
# 4번: kubelet.conf의 users 항목
2
    client-certificate: /var/lib/kubelet/pki/kubelet-client-current.pem
3
    client-key: /var/lib/kubelet/pki/kubelet-client-current.pem

kind v1.37.0 워커와 만료시킨 Lima VM 모두 이 절차 뒤 새 CSR이 자동 승인되고 노드가 Ready로 돌아왔습니다.

kubelet 서빙 인증서는 별개입니다. kubeadm이 배포하는 서빙 인증서는 기본이 자체 서명이고 이것이 3-4절 metrics-server x509 오류의 원인입니다. serverTLSBootstrap: true로 클러스터 CA 서명 인증서를 받게 하면 그 CSR은 자동 승인되지 않아 kubectl certificate approve로 승인합니다.

1-5. kubectl debug로 노드 들여다보기

ssh를 쓸 수 없으면 Debug Running Pods 문서의 노드 디버그를 씁니다.

1
kubectl debug node/<노드> -it --image=ubuntu

노드의 루트 파일시스템이 /host에 마운트되고 호스트의 IPC, 네트워크, PID 네임스페이스에서 돕니다. 특권 Pod가 아니라서 chroot /host 같은 일부 동작이 실패할 수 있고 그때는 --profile=sysadmin을 씁니다. 끝나면 디버그 Pod를 지웁니다.

1-6. 노드를 서비스에서 빼고 넣기

1
kubectl cordon <노드>                         # 새 Pod 배치 금지
2
kubectl drain --ignore-daemonsets <노드>      # Pod 축출. DaemonSet Pod는 건너뜀
3
kubectl uncordon <노드>                       # 다시 배치 허용

DaemonSet Pod가 있으면 --ignore-daemonsets가 있어야 drain이 성공합니다(Safely Drain a Node 문서). cordon된 노드는 출력에 SchedulingDisabled로 보이고 Node Status 문서는 이것이 조건 목록에 없는 출력용 표시라고 적습니다.

1-7. 자주 틀리는 지점

• systemctl restart kubelet만 하고 enable을 빠뜨립니다. 과제가 “재부팅 뒤에도 유지”를 요구하면 enable 상태까지 확인합니다.
• 다른 노드에서 고칩니다. 과제마다 지정된 호스트가 있고 kubelet은 각 노드에서 따로 돕니다. 워커 NotReady는 그 워커에서 고칩니다.
• 노드 조건이 NetworkUnavailable이거나 kubelet 로그에 CNI 오류가 있는데 kubelet만 재시작합니다. 네트워크 플러그인 Pod 상태를 함께 봅니다.
• kubeadm certs check-expiration만 보고 kubelet 인증서가 정상이라고 판단합니다.

1-8. 직접 해 보기

1. 워커에서 sudo systemctl stop kubelet을 하고 kubectl get nodes -w로 Unknown이 되는 시점과 테인트를 봅니다.
2. /var/lib/kubelet/config.yaml을 백업한 뒤 들여쓰기를 망가뜨리고 journalctl -u kubelet에서 오류 줄을 찾아 되돌립니다.
3. 워커에서 1-4절 표 6번의 openssl로 kubelet 클라이언트 인증서를 읽고 ls -l /var/lib/kubelet/pki/로 kubelet-client-current.pem이 가리키는 파일을 확인합니다.

2. 클러스터 구성요소

2-1. 무엇이 어디서 도나

바이너리를 systemd 서비스로 설치한 클러스터라면 컨트롤 플레인 구성요소도 systemctl status kube-apiserver, journalctl -u kube-apiserver로 봅니다. 어느 방식인지는 ls /etc/kubernetes/manifests와 kubectl -n kube-system get pod로 먼저 가립니다.

2-2. static Pod의 동작

Static Pods와 Create static Pods 문서에서 시험에 필요한 사실을 모았습니다.

마지막 줄이 실전 함정입니다. cp kube-apiserver.yaml kube-apiserver.yaml.backup처럼 디렉터리 안에 백업을 만들면 kubelet이 두 파일을 모두 읽어 같은 이름의 Pod를 두 번 만들려 합니다. 결과는 정의되지 않았고 백업의 옛 스펙이 적용될 수도 있습니다. 백업은 디렉터리 밖(문서 예시는 /etc/kubernetes/backup/)에 둡니다.

1
sudo mkdir -p /etc/kubernetes/backup
2
sudo cp /etc/kubernetes/manifests/kube-apiserver.yaml /etc/kubernetes/backup/
3
sudo vi /etc/kubernetes/manifests/kube-apiserver.yaml

static Pod를 재시작하려면 매니페스트를 잠시 디렉터리 밖으로 옮겼다가 되돌립니다. Certificate Management with kubeadm 문서는 kubelet의 fileCheckFrequency만큼(문서는 20초) 기다리라고 적습니다.

1
sudo mv /etc/kubernetes/manifests/kube-scheduler.yaml /tmp/
2
sleep 20
3
sudo crictl ps | grep kube-scheduler     # 사라졌는지
4
sudo mv /tmp/kube-scheduler.yaml /etc/kubernetes/manifests/

2-3. 구성요소가 죽으면 무엇이 멈추나

Troubleshooting Clusters 문서의 장애 시나리오 중 시험과 맞닿은 부분입니다.

2-4. API 서버가 응답하지 않을 때

kubectl이 쓸모없어지므로 노드 안 도구로 내려갑니다. Debugging Kubernetes nodes with crictl 문서의 명령입니다.

1
ssh <컨트롤 플레인 노드>
2
sudo crictl ps -a | grep kube-apiserver        # 종료된 컨테이너까지
3
sudo crictl logs --tail=20 <컨테이너 ID>
4
sudo crictl pods --name kube-apiserver

crictl은 런타임 엔드포인트를 --runtime-endpoint, CONTAINER_RUNTIME_ENDPOINT, /etc/crictl.yaml 중 하나로 압니다. containerd는 unix:///var/run/containerd/containerd.sock입니다.

crictl은 시험 안내의 사전 설치 도구 목록(kubectl, yq, curl, wget, man)에 없습니다. pkgs.k8s.io의 kubeadm 1.37 패키지도 cri-tools를 의존성으로 끌어오지 않습니다. 과제 노드에 crictl이 없으면 kubelet이 런타임에 쓰게 하는 로그 파일(Logging Architecture 문서)을 직접 읽습니다. 디렉터리 이름은 <ns>_<pod>_<uid>/<컨테이너>/<재시작 번호>.log 꼴입니다(kind 노드에서 확인).

1
sudo ls /var/log/pods/ | grep kube-apiserver
2
sudo tail -50 /var/log/pods/kube-system_kube-apiserver-*/kube-apiserver/*.log

2-5. 매니페스트에서 자주 망가지는 곳

트러블슈팅 과제는 보통 “일부러 고장 낸 클러스터를 고치라”입니다. 아래는 매니페스트 구조에서 끌어낸 점검 순서이고 출제 범위를 문서로 확인한 것은 아닙니다.

2-6. 자주 틀리는 지점

• kubectl delete pod kube-apiserver-<노드>로 재시작하려는 것. mirror Pod만 지워집니다.
• 매니페스트를 고친 뒤 바로 kubectl을 치고 실패를 보고 다시 고치는 것. kubelet이 변경을 감지하고 컨테이너를 다시 띄우는 데 시간이 걸리니 crictl ps로 새 컨테이너부터 봅니다.
• API 서버가 죽은 상태에서 컨트롤 플레인 로그를 kubectl logs로 보려는 것. 그때는 crictl logs나 /var/log/pods입니다.

2-7. 직접 해 보기

1. kube-scheduler 매니페스트의 이미지 태그를 없는 값으로 바꾸고 Deployment를 스케일해 새 Pod가 Pending에 머무는 것을 봅니다. 원인을 찾아 되돌립니다.
2. kube-apiserver 매니페스트의 --etcd-servers 포트를 바꾸고 crictl ps -a, crictl logs로 오류 문장을 찾아 되돌립니다. 백업은 /etc/kubernetes/backup/에 둡니다.
3. 워커의 /etc/kubernetes/manifests에 정적 웹 서버 Pod를 만들고 kubectl delete로 mirror Pod를 지워 다시 나타나는지 봅니다.

3. 리소스 사용량 모니터링

3-1. 리소스 메트릭 파이프라인

Resource metrics pipeline 문서의 구성입니다.

1
컨테이너 런타임 -> cAdvisor(kubelet에 포함) -> kubelet(/metrics/resource)
2
   -> metrics-server(각 kubelet에서 수집) -> Metrics API(metrics.k8s.io, API 서버 aggregation)
3
   -> HPA, VPA, kubectl top

metrics-server는 Metrics API의 참조 구현인 클러스터 애드온이고 이것(또는 다른 어댑터)을 배포해야 Metrics API가 생깁니다. README는 수집 간격 15초, 자동 확장 전용이라고 적습니다. kubectl top의 값도 가장 최근 수집값뿐입니다.

API 버전은 두 층을 나눠서 봅니다.

aggregation 계층은 등록된 버전만 응답하므로 v0.9.0에서 /apis/metrics.k8s.io/v1/...을 직접 부르면 NotFound입니다(kind에서 확인, KEP-5207의 버전 표와 같음). kubectl top은 버전을 알아서 고르니 경로를 손으로 칠 때만 kubectl get apiservice | grep metrics로 버전을 먼저 봅니다.

3-2. kubectl top

1
kubectl top node
2
kubectl top node --sort-by=cpu
3
kubectl top pod -n shop --sort-by=memory
4
kubectl top pod -n shop --containers           # 컨테이너별
5
kubectl top pod -n shop -l app=order-api --sum # 합계 행 추가
6
kubectl top pod -A --sort-by=cpu --no-headers | head -1   # 가장 많이 쓰는 Pod 하나

--sort-by는 cpu나 memory만 받습니다. 다른 값을 주면 --sort-by accepts only cpu or memory로 실패합니다(kubectl v1.37.1). 막 만든 Pod는 파이프라인 지연 때문에 몇 분 동안 error: Metrics not available for pod ...가 나올 수 있습니다. 결과를 파일로 옮길 때는 과제가 요구하는 형식(이름만인지, 네임스페이스를 포함하는지)을 다시 읽습니다.

3-3. 숫자를 읽는 법

메모리 수치가 컨테이너 안의 free와 달라도 이상한 일은 아닙니다. 컨테이너가 limits.memory를 넘으면 커널이 종료하고 describe의 Last State에 OOMKilled, Exit Code 137이 남습니다. 이 과정을 cgroup 쪽에서 본 설명은 쿠버네티스 아래의 리눅스 3편에 있습니다(시험 범위 밖 심화).

3-4. kubectl top이 안 될 때

Troubleshooting kubeadm 문서에 kubeadm 클러스터 고유의 함정이 있습니다. kubeadm은 kubelet에 자체 서명 서빙 인증서를 배포하므로 metrics-server가 kubelet에 붙을 때 x509: certificate signed by unknown authority 같은 오류가 납니다. 문서는 --kubelet-insecure-tls로 우회할 수 있지만 운영에는 권하지 않고 서명된 서빙 인증서(1-4절 끝)를 쓰라고 안내합니다. 시험장에서는 과제 지시를 따릅니다. kind에서는 로그에 x509: cannot validate certificate for 172.18.0.5 because it doesn't contain any IP SANs가 찍히고 APIService가 False (MissingEndpoints)였으며 metrics-server v0.9.0 매니페스트에 --kubelet-insecure-tls를 더해야 Pod가 Ready가 됐습니다.

3-5. 출력 형식으로 값 뽑기

모니터링 과제는 대개 출력의 일부를 파일로 옮기는 데서 끝납니다. kubectl Quick Reference와 JSONPath Support 문서의 형식을 과제 형태로 묶었습니다.

1
# 노드마다 이름과 Ready 상태
2
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.conditions[?(@.type=="Ready")].status}{"\n"}{end}'
3

4
# 재시작이 가장 많은 Pod (오름차순이라 마지막 줄)
5
kubectl get pods -A --sort-by='.status.containerStatuses[0].restartCount' --no-headers | tail -1
6

7
# 테인트가 걸린 노드 (Quick Reference 예시)
8
kubectl get nodes -o custom-columns='NODE:.metadata.name,TAINT:.spec.taints[*].key,EFFECT:.spec.taints[*].effect'

3-6. JSONPath를 jq 없이 쓰기

식은 세 단계로 세웁니다. 먼저 kubectl get <리소스> -o yaml로 구조를 봅니다. 필드 이름이 헷갈리면 kubectl explain pod.status.containerStatuses로 스키마를 확인합니다. 찾은 경로를 -o jsonpath='{...}'에 넣으면 끝입니다. 목록을 조회하면 결과가 items 배열로 감싸이고 이름을 준 단일 객체 조회에는 items가 없다는 점이 첫 함정입니다.

1
# 노드마다 이름과 내부 IP
2
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.addresses[?(@.type=="InternalIP")].address}{"\n"}{end}'
3

4
# 컨테이너가 여럿인 Pod에서 app 컨테이너의 이미지만
5
kubectl -n shop get pod board -o jsonpath='{.spec.containers[?(@.name=="app")].image}{"\n"}'
6

7
# custom-columns는 원소 하나 기준이라 .items[*]를 붙이지 않는다. 필터도 쓸 수 있다
8
kubectl get node -o custom-columns='NODE:.metadata.name,READY:.status.conditions[?(@.type=="Ready")].status'

JSONPath는 정규 표현식을 지원하지 않고 문서는 그럴 때 jq를 쓰라고 적습니다. 그런데 시험 호스트의 사전 설치 목록에는 jq가 없고 yq가 있습니다. 그래서 jq로 하던 일은 이렇게 바꿉니다.

1
# 노드별 Pod 수
2
kubectl get pods -A -o jsonpath='{range .items[*]}{.spec.nodeName}{"\n"}{end}' | sort | uniq -c

자주 하는 실수는 네 가지입니다. 식을 작은따옴표로 감싸지 않아 셸이 [*]나 "를 먼저 해석하는 것, 중괄호를 빼먹는 것, custom-columns에 .items[*]를 붙이는 것, 마지막 {"\n"}이 없어 파일 끝 줄바꿈이 빠지는 것입니다. 파일로 옮겼다면 cat -A로 탭(^I)과 줄 끝($)까지 확인합니다.

3-7. 직접 해 보기

1. 연습 클러스터에 metrics-server를 설치하고 kubectl get apiservice | grep metrics로 등록된 버전을 봅니다. kubectl get --raw "/apis/metrics.k8s.io/<그 버전>/nodes"의 window와 usage를 kubectl top node와 맞춰 봅니다.
2. 결제 Deployment에 CPU를 쓰는 루프 컨테이너를 넣고 kubectl top pod --containers --sort-by=cpu로 맨 위에 오는지 확인합니다.

4. 컨테이너 출력 스트림

4-1. 로그가 어디서 오나

Logging Architecture 문서의 흐름입니다. 컨테이너 런타임이 앱의 stdout과 stderr를 받아 kubelet이 지정한 /var/log/pods 아래 파일에 씁니다. kubelet이 로그 회전을 맡고(기본 containerLogMaxSize 10Mi, containerLogMaxFiles 5개) kubectl logs를 치면 그 노드의 kubelet이 파일을 읽어 돌려줍니다.

4-2. kubectl logs

1
kubectl logs order-api-xxxx -n shop                    # 컨테이너가 하나일 때
2
kubectl logs order-api-xxxx -n shop -c app             # 컨테이너 지정
3
kubectl logs order-api-xxxx -n shop -c app --previous  # 직전 종료 인스턴스(-p)
4
kubectl logs order-api-xxxx -n shop --all-containers=true
5
kubectl logs -f order-api-xxxx -n shop                 # 계속 따라가기
6
kubectl logs --tail=20 --since=1h order-api-xxxx -n shop
7
kubectl logs -l app=order-api -n shop --all-containers=true --prefix
8
kubectl logs deployment/order-api -n shop --all-pods=true

멀티 컨테이너 Pod에서 -c를 빼면 kubectl은 오류 없이 컨테이너 하나를 골라 보여 줍니다. 고르는 순서는 이렇습니다(kubectl 소스 logsforobject.go 기준).

1. Pod에 kubectl.kubernetes.io/default-container 어노테이션이 있으면 그 컨테이너
2. 없으면 spec.containers의 첫 번째 컨테이너. 표준 오류에 Defaulted container "app" out of: app, access-log 꼴의 안내가 찍힘

어노테이션이 없는 이름을 가리키면 Default container name "nope" not found in pod board 안내 뒤 첫 컨테이너로 넘어갑니다(kubectl v1.37.1). init 컨테이너와 네이티브 사이드카(initContainers에 있음)도 -c <이름>으로 봅니다. 이름은 이렇게 확인합니다.

1
kubectl -n shop get pod board -o jsonpath='{.spec.containers[*].name}{"\n"}{.spec.initContainers[*].name}{"\n"}'

4-3. CrashLoopBackOff를 로그로 읽기

Pod Lifecycle 문서 기준으로 재시작 지연은 10초, 20초, 40초로 두 배씩 늘어 300초에서 멈추고 컨테이너가 10분 동안 문제없이 돌면 초기화됩니다. 원인은 앱 오류, 잘못된 환경 변수나 빠진 설정 파일, 자원 부족, liveness나 startup probe 실패입니다. 조사 순서는 로그, 이벤트, 설정, 자원 한도입니다.

1
kubectl -n shop logs payment-xxxx --previous              # 죽기 직전 출력
2
kubectl -n shop describe pod payment-xxxx                 # Last State, Reason, Exit Code, Events
3
kubectl -n shop get pod payment-xxxx -o jsonpath='{.status.containerStatuses[0].lastState}'
4
kubectl -n shop get deploy payment -o yaml | grep -A5 -E 'command|args|env|resources|livenessProbe'

--previous를 붙이는 습관이 안전합니다. 다음 재시작을 기다리는 동안에는 실행 중인 컨테이너가 없어 kubectl logs와 --previous가 같은 직전 인스턴스를 보여 줍니다. 새 컨테이너가 도는 동안에는 --previous를 빼면 새 컨테이너의 짧은 로그가 나옵니다(kind v1.37.0에서 확인).

Determine the Reason for Pod Failure 문서는 컨테이너가 /dev/termination-log에 쓴 종료 메시지를 읽는 방법을 보여 줍니다. terminationMessagePolicy: FallbackToLogsOnError를 주면 메시지 파일이 비었고 오류로 끝났을 때 로그 마지막 부분(2048바이트와 80줄 중 작은 쪽)을 메시지로 씁니다.

1
kubectl get pod <pod> -o go-template="{{range .status.containerStatuses}}{{.lastState.terminated.message}}{{end}}"

lastState는 재시작된 컨테이너에만 채워집니다. restartPolicy: Never인 Pod가 끝났다면 .lastState를 .state로 바꿉니다.

4-4. 셸이 없는 컨테이너

kubectl exec로 셸에 들어갈 수 없는 이미지(distroless 등)는 임시 컨테이너를 붙입니다(Debug Running Pods 문서).

1
kubectl debug -it <pod> --image=busybox:1.36 --target=<컨테이너 이름>
2
kubectl debug payment-xxxx -it --copy-to=payment-debug --container=app -- sh   # Pod를 복사해 명령을 바꿔 띄움

--target은 대상 컨테이너의 프로세스 네임스페이스를 공유하게 합니다. 임시 컨테이너는 v1.25부터 stable이고 static Pod에는 붙일 수 없습니다.

4-5. 사이드카로 로그 스트림 나누기

앱이 파일에 로그를 쓰면 Logging Architecture 문서의 스트리밍 사이드카를 씁니다. 사이드카가 공유 볼륨의 로그 파일을 읽어 자기 stdout으로 내보내면 kubectl logs <pod> -c <사이드카>로 볼 수 있습니다.

1
apiVersion: v1
2
kind: Pod
3
metadata:
4
  name: board
5
  namespace: shop
6
spec:
7
  containers:
8
  - name: app
9
    image: busybox:1.36
10
    args: [/bin/sh, -c, 'i=0; while true; do echo "$i GET /board" >> /var/log/board/access.log; i=$((i+1)); sleep 1; done']
11
    volumeMounts:
12
    - name: logs
13
      mountPath: /var/log/board
14
  - name: access-log
15
    image: busybox:1.36
16
    args: [/bin/sh, -c, 'tail -n+1 -F /var/log/board/access.log']
17
    volumeMounts:
18
    - name: logs
19
      mountPath: /var/log/board
20
  volumes:
21
  - name: logs
22
    emptyDir: {}

1
kubectl -n shop logs board -c access-log

이 Pod에서 -c 없이 kubectl -n shop logs board를 치면 Defaulted container "app" out of: app, access-log 안내와 함께 빈 출력이 나옵니다. app은 파일에만 쓰기 때문입니다. 같은 구조를 네이티브 사이드카(initContainers에 restartPolicy: Always, 1.33 stable)로 쓰는 법은 Ch-03에 있습니다.

4-6. 자주 틀리는 지점

• 멀티 컨테이너 Pod에서 -c 없이 쳐서 기본 컨테이너의 로그를 원하는 로그로 착각하는 것.
• 재시작된 Pod에서 --previous를 빼먹는 것.
• 로그를 파일로 저장하라는 과제에서 다른 호스트에 저장하는 것. 과제가 지정한 호스트에서 리다이렉트합니다.
• kubeadm 클러스터에서 API 서버 로그를 journalctl -u kube-apiserver로 찾는 것. static Pod라서 kubectl logs나 crictl logs로 봅니다.

4-7. 직접 해 보기

1. command: ["sh","-c","echo start; exit 1"]로 결제 Pod를 만들어 CrashLoopBackOff를 만들고 kubectl logs와 --previous의 차이, RESTARTS가 늘어나는 간격을 봅니다.
2. 4-5의 게시판 Pod를 만들고 kubectl logs board -c app이 비어 있는 이유를 설명합니다.
3. kubectl logs -l app=order-api --all-containers=true --prefix --tail=5로 여러 Pod의 로그를 한 번에 봅니다.

5. 서비스와 네트워킹 트러블슈팅

5-1. Debug Services 문서의 순서

Debug Services 문서는 질문을 하나씩 확인하는 순서로 짜여 있습니다. 앞 질문이 “예”여야 다음으로 넘어갑니다.

5번의 점검 목록은 문서 원문입니다. 접근하려는 포트가 spec.ports[]에 있는지, targetPort가 Pod가 쓰는 포트인지, 숫자 포트를 의도했는데 문자열로 쓰지 않았는지, 이름 붙은 포트라면 Pod가 같은 이름의 포트를 노출하는지, 프로토콜이 맞는지입니다.

6번에서 ENDPOINTS가 비어 있으면(kubectl get endpointslices는 <unset>, 1.33부터 사용 중단 경고를 찍는 kubectl get endpoints는 <none>) Service의 spec.selector가 Pod의 라벨을 실제로 고르는지 봅니다. 라벨은 맞는데 비어 있으면 readiness probe 실패입니다. Pod Lifecycle 문서는 readiness가 실패한 Pod의 IP를 EndpointSlice 컨트롤러가 뺀다고 적습니다.

5-2. 쇼핑몰 예로 따라가기

주문 API Service order-api가 응답하지 않는다고 가정합니다. 엔드포인트 확인(6번)이 selector, 라벨, readiness 문제를 한 번에 가르므로 존재 확인 바로 다음에 둡니다.

1
# 1. 존재
2
kubectl -n shop get svc order-api
3

4
# 6. 엔드포인트와 라벨 대조
5
kubectl -n shop get endpointslices -l kubernetes.io/service-name=order-api
6
kubectl -n shop get pod --show-labels
7
kubectl -n shop get pod -l app=order-api       # Service selector 그대로
8

9
# 5. 정의
10
kubectl -n shop get svc order-api -o yaml | grep -A8 -E 'ports:|selector:'
11

12
# 3, 4, 7. 클러스터 안에서 이름, Service IP, Pod IP로
13
kubectl -n shop run tmp --rm -it --restart=Never --image=busybox:1.36 -- sh
14
#   nslookup order-api
15
#   wget -qO- -T 2 order-api:80
16
#   wget -qO- -T 2 <Pod IP>:<targetPort>
17

18
# 2. 정책
19
kubectl -n shop get networkpolicy
20
kubectl -n shop describe networkpolicy <이름>

임시 Pod 이미지는 busybox:1.36을 씁니다. 문서 예시의 busybox:1.28은 arm64 노드에서 wget이 Segmentation fault로 죽었습니다(kind). 1.36의 nslookup은 order-db-0.order-db처럼 점이 든 짧은 이름을 풀지 못하니 그럴 때는 <svc>.<ns>.svc.cluster.local 전체 이름을 씁니다.

5-3. kube-proxy 확인

엔드포인트가 있고 Pod 직접 호출도 되는데 Service IP로만 안 되면 서비스 프록시를 의심합니다. kubeadm 클러스터의 kube-proxy는 DaemonSet입니다.

1
kubectl -n kube-system get ds,cm | grep kube-proxy
2
kubectl -n kube-system get pod -l k8s-app=kube-proxy -o wide
3
kubectl -n kube-system logs <kube-proxy Pod>
4
kubectl -n kube-system get configmap kube-proxy -o yaml | grep mode

kind v1.37.0에서 ConfigMap의 mode는 iptables였고 kube-proxy 로그에 Using iptables Proxier가 찍혔습니다. iptables 모드라면 노드에서 sudo iptables-save | grep <svc 이름>으로 Service용 규칙이 생겼는지 봅니다(Debug Services 문서). 규칙의 체인 구조를 해석하는 것은 시험 범위 밖이고 쿠버네티스 아래의 리눅스 5편에 정리했습니다. 클러스터가 kube-proxy를 쓰지 않으면 대신 쓰는 서비스 구현체를 조사합니다.

5-4. 그 밖의 경우

5-5. 자주 틀리는 지점

• Service를 지우고 다시 만들어 ClusterIP가 바뀌는 것. 고칠 때는 kubectl edit입니다.
• 임시 Pod를 기본 네임스페이스에 만들어 짧은 이름으로 다른 네임스페이스의 Service를 찾는 것. -n을 맞추거나 <svc>.<ns>로 부릅니다.
• 테스트용 임시 Pod를 남기는 것. --rm을 붙입니다.
• nslookup이 성공했으니 Service도 정상이라고 판단하는 것. 엔드포인트가 비어 있어도 이름은 풀립니다.
• 엔드포인트가 있으니 정상이라고 판단하는 것. targetPort가 틀려도 슬라이스에는 Pod IP와 잘못된 포트가 그대로 들어갑니다(kind에서 확인).

5-6. 직접 해 보기

1. order-api Service의 selector를 app=order로 바꾸고 5-2의 순서로 원인을 찾습니다. ENDPOINTS 열이 <unset>이 되는 것을 봅니다.
2. targetPort를 없는 포트로 바꾸고 엔드포인트는 있는데 요청이 실패하는 것을 확인합니다.
3. 주문 API에 실패하는 readiness probe를 붙여 READY 0/1과 빈 ENDPOINTS를 함께 관찰합니다.

6. 확인 문제

직접 만든 연습 과제입니다. 시험 문항이나 덤프에서 옮긴 것이 아닙니다.

문제 1. 워커 노드 node02가 NotReady입니다. kubectl describe node node02의 조건 메시지는 Kubelet stopped posting node status.입니다. 해결 순서를 적으세요.

문제 2. kubectl get pod 명령이 API 서버에 연결하지 못합니다. 컨트롤 플레인 노드에서 무엇을 보나요?

1
sudo crictl ps -a | grep kube-apiserver
2
sudo crictl logs <가장 최근 컨테이너 ID>
3
sudo journalctl -u kubelet --no-pager | tail -30
4
sudo cat /etc/kubernetes/manifests/kube-apiserver.yaml

문제 3. 네임스페이스 shop의 payment Pod가 CrashLoopBackOff입니다. 컨테이너 이름은 app입니다. 죽기 직전 로그를 /opt/payment-crash.log에 저장하세요.

1
kubectl -n shop logs <payment Pod 이름> -c app --previous > /opt/payment-crash.log

문제 4. 모든 네임스페이스에서 메모리를 가장 많이 쓰는 Pod의 이름을 /opt/top-mem.txt에 적으세요.

1
kubectl top pod -A --sort-by=memory --no-headers | head -1 | awk '{print $2}' > /opt/top-mem.txt
2
cat /opt/top-mem.txt

문제 5. 컨트롤 플레인 노드의 /etc/kubernetes/manifests 안에서 cp kube-scheduler.yaml kube-scheduler.yaml.bak을 실행했습니다. 무엇이 문제인가요?

문제 6. board Service의 ENDPOINTS가 비어 있습니다. Pod는 3개 모두 Running이고 READY는 0/1입니다. 원인과 확인 방법은요?

문제 7. 새 Deployment board를 만들었는데 ReplicaSet은 있고 Pod 객체가 하나도 생기지 않습니다. 반대로 Pod 객체는 생겼는데 모두 Pending이고 Events에 아무것도 없다면 어떤가요? 각각 어느 구성요소를 보나요?

문제 8. 워커 node03이 NotReady이고 kubelet은 active (running)입니다. kube-apiserver 로그에 x509: certificate has expired or is not yet valid가 반복됩니다. 무엇을 확인하고 어떻게 복구하나요?

1
sudo openssl x509 -in /var/lib/kubelet/pki/kubelet-client-current.pem -noout -subject -issuer -dates
2
date

문제 9. 모든 노드의 이름과 InternalIP를 탭으로 구분해 한 줄에 하나씩 /opt/node-ips.txt에 저장하세요. jq는 쓸 수 없습니다.

1
kubectl get nodes -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.addresses[?(@.type=="InternalIP")].address}{"\n"}{end}' > /opt/node-ips.txt
2
cat -A /opt/node-ips.txt     # 탭은 ^I, 줄 끝은 $

7. 범위와 한계

• 명령과 오류 문구는 kind v1.37.0 클러스터(arm64)와 Lima VM의 kubeadm 1.37.1 클러스터에서 2026년 10월에 직접 돌려 확인했습니다. 본문에 “(kind)”, “(Lima VM)“으로 표시한 출력이 그 결과입니다.
• jq는 2025년 3월 판 시험 안내부터 사전 설치 목록에서 빠졌고 crictl은 있다는 근거가 없습니다. 그래서 /var/log/pods와 JSONPath, yq 대안을 함께 적었습니다.
• cgroup v1과 스왑 노드, serverTLSBootstrap 서빙 인증서 승인, hairpin, NodePort 외부 접속, Ingress와 Gateway 경유 장애는 돌려 보지 못했습니다.
• Metrics API는 1.37에서 v1이 Stable이지만 2026년 10월 기준 릴리스된 metrics-server(v0.9.0)는 v1beta1만 제공합니다. 시험 클러스터의 metrics-server 버전은 확인하지 못했습니다.
• etcd 백업과 복구, kubeadm 업그레이드 절차는 Ch-02에 있습니다.

참고 자료

• CNCF, CKA Curriculum v1.37
• Linux Foundation, Important Instructions: CKA and CKAD, Resources Allowed
• kubernetes.io, Troubleshooting Clusters, Debug Pods, Debug Running Pods, Debug Services, Determine the Reason for Pod Failure
• kubernetes.io, Debugging Kubernetes nodes with crictl, Resource metrics pipeline, Logging Architecture
• kubernetes.io, kubectl Quick Reference, JSONPath Support, kubectl logs, kubectl top pod
• kubernetes.io, Pod Lifecycle, Images, Node Status, Safely Drain a Node
• kubernetes.io, Static Pods, Create static Pods, kubeadm Implementation details
• kubernetes.io, Configuring each kubelet in your cluster using kubeadm, Troubleshooting kubeadm, Certificate Management with kubeadm, About cgroup v2
• Kubernetes, CHANGELOG-1.37, KEP-5207 metrics.k8s.io API definition, 블로그 Kubernetes v1.37: Garhwal
• kubernetes-sigs, metrics-server README, metrics-server releases
• kubernetes/kubectl, pkg/polymorphichelpers/logsforobject.go (기본 컨테이너 선택)