Part 1. 개발자를 위한 Kubernetes 입문
Ch 10. Kubernetes 모니터링과 디버깅
Ch 10. Kubernetes 모니터링과 디버깅
- Ch 10. Kubernetes 모니터링과 디버깅
- 01. Kubernetes 모니터링과 디버깅
- Kubernetes 모니터링과 디버깅
- Kubernetes 디버깅 흐름
- kubectl version
- 주요 확인 포인트
- 연결 오류 예시
- kubectl get
- Pod 조회
- 주요 컬럼 설명
- STATUS 주요 상태
- YAML 형식 조회
- 예시
- 왜 중요한가?
- kubectl describe
- 예시
- describe가 중요한 이유
- kubectl logs
- 로그 예시
- 자주 사용하는 옵션
- kubectl exec
- 내부 디버깅 가능
- 실무에서 자주 하는 작업
- kubectl run
- 예시
- 활용 사례
- 디버깅 Pod 활용 구조
- kubectl get events
- 이벤트 예시
- Events가 중요한 이유
- 자주 발견되는 문제
- kubectl diff
- 예시
- 왜 유용한가?
- kubectl edit
- 특징
- 주의사항
- Kubernetes 디버깅 핵심 흐름
- 실무 운영 환경
- 핵심 정리
- 한 줄 핵심 정리
- 01. Kubernetes 모니터링과 디버깅
01. Kubernetes 모니터링과 디버깅
Kubernetes 모니터링과 디버깅
Kubernetes는 수많은 Pod와 컨테이너가 동적으로 생성되고 삭제되는 환경이다.
따라서:
- 현재 어떤 상태인지
- 어떤 문제가 발생했는지
- 왜 Pod가 실행되지 않는지
- 어떤 이벤트가 발생했는지
를 빠르게 파악하는 능력이 매우 중요하다.
Kubernetes에서는 기본적으로 kubectl 명령어를 통해 모니터링과 디버깅 기능을 제공한다.
Kubernetes 디버깅 흐름
실무에서는 보통 다음 순서로 문제를 추적한다.
graph TD
A["kubectl get"] --> B["kubectl describe"]
B --> C["kubectl logs"]
C --> D["kubectl exec"]
D --> E["kubectl get events"]
kubectl version
클라이언트와 Kubernetes API 서버의 버전 및 연결 상태를 확인한다.
$ kubectl version
Client Version: v1.28.2
Kustomize Version: v5.0.4
Server Version: v1.27.3
주요 확인 포인트
| 항목 | 설명 |
|---|---|
| Client Version | kubectl 버전 |
| Server Version | Kubernetes API 서버 버전 |
| Kustomize Version | 내장 Kustomize 버전 |
연결 오류 예시
error: Get "http://localhost:8080/version":
connection reset by peer
이런 오류는 보통:
- API 서버 다운
- kubeconfig 문제
- 네트워크 연결 문제
등이 원인이다.
kubectl get
Kubernetes 객체 목록이나 상태를 조회한다.
가장 많이 사용하는 명령어 중 하나다.
Pod 조회
$ kubectl get pod my-simple-pod
NAME READY STATUS RESTARTS AGE
my-simple-pod 1/1 Running 0 5m
주요 컬럼 설명
| 컬럼 | 설명 |
|---|---|
| READY | 준비 완료 컨테이너 수 |
| STATUS | 현재 상태 |
| RESTARTS | 재시작 횟수 |
| AGE | 생성 후 경과 시간 |
STATUS 주요 상태
| 상태 | 의미 |
|---|---|
| Running | 컨테이너가 실행 중이거나 시작·재시작 중이며 서비스 정상 여부는 별도 확인 |
| Pending | 스케줄링 또는 이미지 준비 등 컨테이너 실행 준비 중 |
| CrashLoopBackOff | 반복 크래시 |
| Error | 실행 실패 |
| Completed | 정상 종료 |
YAML 형식 조회
$ kubectl get pod my-simple-pod -o yaml
예시
apiVersion: v1
kind: Pod
metadata:
name: my-simple-pod
namespace: default
왜 중요한가?
-o yaml 옵션은:
API Server에 저장된 객체의 현재 spec과 status
를 그대로 보여준다.
따라서:
- 설정 확인
- 필드 디버깅
- 상태 분석
에 매우 중요하다.
kubectl describe
객체의 상세 상태를 조회한다.
$ kubectl describe pod my-simple-pod
예시
Name: my-simple-pod
Namespace: default
Node: kind-control-plane
Status: Running
describe가 중요한 이유
실무에서 가장 많이 보는 정보 중 하나다.
특히:
Events
영역이 매우 중요하다.
예를 들어:
- 이미지 Pull 실패
- 스케줄 실패
- 볼륨 마운트 실패
- Probe 실패
같은 원인을 바로 확인할 수 있다.
kubectl logs
컨테이너 로그를 조회한다.
$ kubectl logs my-simple-pod
로그 예시
Spring Boot :: (v2.2.1.RELEASE)
Starting Application on my-simple-pod
Tomcat initialized with port(s): 8080
자주 사용하는 옵션
특정 컨테이너 로그
$ kubectl logs my-pod -c my-container
실시간 로그
$ kubectl logs -f my-pod
이전 크래시 로그
$ kubectl logs --previous my-pod
CrashLoopBackOff 디버깅 시 매우 중요하다.
kubectl exec
실행 중인 컨테이너 내부로 진입한다.
$ kubectl exec -it my-simple-pod -- bash
내부 디버깅 가능
컨테이너 내부에서:
- 파일 확인
- 환경 변수 확인
- curl 테스트
- 프로세스 확인
- 네트워크 확인
등을 수행할 수 있다.
실무에서 자주 하는 작업
환경 변수 확인
printenv SPRING_PROFILES_ACTIVE
DNS 확인
nslookup my-service
네트워크 확인
curl http://my-service
kubectl run
임시 Pod를 빠르게 생성한다.
디버깅 용도로 매우 많이 사용된다.
예시
$ kubectl run -it --rm redis-pod --image=redis -- sh
활용 사례
임시 컨테이너로:
- Redis 접속
- DB 연결 테스트
- DNS 확인
- 네트워크 확인
등을 수행한다.
디버깅 Pod 활용 구조
graph LR
DebugPod --> Redis
DebugPod --> Database
DebugPod --> Service
kubectl get events
클러스터 이벤트를 조회한다.
$ kubectl get events
이벤트 예시
Scheduled
Pulling image
Created container
Started container
Events가 중요한 이유
Kubernetes는 내부적으로 수많은 이벤트를 발생시킨다.
따라서:
왜 Pod가 실행되지 않는가?
를 분석할 때 매우 중요하다.
자주 발견되는 문제
| 이벤트 | 의미 |
|---|---|
| FailedScheduling | 스케줄 실패 |
| FailedMount | 볼륨 마운트 실패 |
| BackOff | 재시작 반복 |
| ErrImagePull | 이미지 다운로드 실패 |
kubectl diff
현재 상태와 YAML 파일 차이를 비교한다.
$ kubectl diff -f my-simple-pod.yaml
예시
- image: ubuntu
+ image: ubuntu:23.10
왜 유용한가?
실제 apply 전에:
무엇이 변경되는지
를 안전하게 검증할 수 있다.
GitOps 환경에서도 자주 사용된다.
kubectl edit
실행 중인 객체를 직접 수정한다.
$ kubectl edit pod my-simple-pod
특징
내부적으로:
현재 YAML 조회
→ 편집
→ 즉시 반영
과정으로 동작한다.
주의사항
실무에서는:
- 긴급 장애 대응
- 임시 수정
정도에만 사용하고
보통은:
YAML 수정 → Git 반영 → apply
방식을 선호한다.
Kubernetes 디버깅 핵심 흐름
실무에서 가장 자주 사용하는 패턴은 다음과 같다.
1단계: 상태 확인
kubectl get pod
2단계: 상세 정보 확인
kubectl describe pod
3단계: 로그 확인
kubectl logs
4단계: 컨테이너 진입
kubectl exec
5단계: 이벤트 확인
kubectl get events
실무 운영 환경
한 명령의 성공으로 애플리케이션 전체를 정상이라고 판단하지 않는다. get은 조사 대상을 찾고, describe는 조건과 이벤트를 확인하며, logs --previous는 같은 Pod에서 직전 컨테이너가 종료되기 전의 단서를 확인한다. exec는 실제 실행 중인 컨테이너가 있어야 가능하고, 이미지에 Shell이나 curl이 없을 수도 있다.
예를 들어 Pod가 Running인데 요청이 실패한다면 먼저 READY와 재시작 횟수를 보고, 해당 요청을 처리한 컨테이너의 로그에서 시각과 호출 대상을 찾는다. 반대로 Node가 배정되지 않은 Pending에서는 애플리케이션 로그보다 FailedScheduling 이벤트가 먼저다. 문제의 단계에 따라 사용하는 증거가 달라진다.
환경 변수를 검사할 때는 위 예시처럼 필요한 비민감 키만 선택한다. 전체 env 출력이나 Secret YAML은 자격 증명을 노출할 수 있다. 객체 YAML도 원본 배포 파일이나 데이터 백업과 동일하지 않으며, 이벤트는 보관 기간과 집계 특성 때문에 영구 감사 기록을 대신하지 않는다.
kubectl만으로도 기본 디버깅은 가능하지만 실제 운영 환경에서는 전문 모니터링 도구를 함께 사용한다.
대표적으로:
| 도구 | 용도 |
|---|---|
| Prometheus | 메트릭 수집 |
| Grafana | 대시보드 시각화 |
| Loki | 로그 수집 |
| Elasticsearch | 로그 검색 |
| Jaeger | 분산 트레이싱 |
등이 많이 사용된다.
핵심 정리
kubectl get→ 상태 확인kubectl describe→ 상세 분석kubectl logs→ 애플리케이션 로그 확인kubectl exec→ 컨테이너 내부 진입kubectl get events→ 클러스터 이벤트 확인kubectl diff→ 변경점 비교kubectl edit→ 즉시 수정
한 줄 핵심 정리
👉 Kubernetes 디버깅은 “상태 확인 → 이벤트 확인 → 로그 분석 → 내부 진입” 흐름으로 진행된다.