새벽에 울리는 알람, 파드가 죽어 있다면?
평화로운 새벽, 갑자기 슬랙(Slack) 알람이 요란하게 울려요. 서비스 장애를 알리는 메시지예요. 확인해 보니 운영 중인 파드(Pod) 하나가 CrashLoopBackOff 상태에 빠져 있어요. 당황스러운 마음에 급하게 터미널을 열지만, 머릿속이 하얘지며 어떤 명령어를 먼저 입력해야 할지 막막해지곤 해요.
소규모 스타트업에서 혼자 서버를 담당하다 보면 이런 상황이 정말 자주 발생해요. 쿠버네티스(Kubernetes) 환경은 강력하지만, 그만큼 관리해야 할 명령어의 양도 방대하거든요. 명령어를 제대로 모르면 단순한 상태 확인조차 한참 걸리고, 결국 장애 복구 시간만 늦추게 돼요.
하지만 걱정하지 마세요. 파드 운영의 핵심이 되는 파드 kubectl 명령어만 제대로 손에 익혀두면, 어떤 돌발 상황에서도 침착하게 대응할 수 있어요. 단순히 명령어를 나열하는 것이 아니라, 실제 장애 상황에서 어떤 순서로 명령어를 조합해 문제를 해결하는지 그 흐름을 알려드릴게요.
이 글을 다 읽고 나면 다음 기능들을 능숙하게 다룰 수 있어요.
- 파드의 현재 상태를 정확하게 조회하고 필터링하는 방법
- 파드를 생성, 수정, 삭제하며 생명 주기를 관리하는 방법
- 로그 확인과 컨테이너 내부 진입을 통한 실전 디버깅 기술
- 복잡한 출력 결과를 효율적으로 가공하여 보는 팁
명령어를 치기 전, 반드시 체크해야 할 기본기
무작정 명령어를 입력하기 전에 현재 내가 어떤 환경에 있는지 확인하는 과정이 꼭 필요해요. 엉뚱한 네임스페이스(Namespace)에서 명령어를 날리거나, 잘못된 클러스터 컨텍스트(Context)에 연결되어 있다면 엉뚱한 서버를 건드리는 대참사가 일어날 수 있거든요.
가장 먼저 kubeconfig 설정이 제대로 되어 있는지 확인해야 해요. 내가 지금 운영 중인 서버에 접근 권한이 있는지, 그리고 현재 선택된 컨텍스트가 운영(Production) 환경인지 개발(Development) 환경인지 구분하는 것이 운영자의 첫 번째 임무예요.
kubectl 명령어의 기본 구조는
kubectl [동사] [리소스 종류] [리소스 이름] [옵션] 형식을 따라요. 예를 들어 kubectl get pods my-app이라고 하면, ‘my-app이라는 이름의 파드들을 가져와라’라는 뜻이 돼요.효율적인 작업을 위해 상황에 맞는 조회 범위를 결정해야 해요. 아래 표를 통해 어떤 기준으로 명령어를 사용할지 판단해 보세요.
| 현재 네임스페이스 |
| 모든 네임스페이스 |
| 특정 라벨 기준 |
준비가 끝났다면 이제 본격적으로 파드를 다루는 실전 명령어로 들어가 볼게요. 단순한 조회를 넘어, 파드의 상태를 깊이 있게 파헤치는 방법을 배우게 될 거예요.
파드 운영의 핵심: 조회부터 디버깅까지
실무에서는 파드가 단순히 ‘떠 있다’는 사실보다, ‘어떤 상태로 어떻게 떠 있는가’가 훨씬 중요해요. 단계별로 꼭 필요한 명령어들을 살펴볼게요.
STEP 1. 파드 상태와 정보 조회하기
가장 먼저 사용하는 것은 파드의 목록을 확인하는 파드 조회 명령이에요. kubectl get pods를 입력하면 현재 네임스페이스에 있는 파드들의 상태, 생성 시간, IP 주소 등을 볼 수 있어요. 만약 더 자세한 정보가 필요하다면 -o wide 옵션을 붙여보세요. 파드가 어느 노드(Node)에 배치되었는지까지 한눈에 보여주거든요.
상태가 이상하다면 kubectl describe pod [파드이름] 명령어가 구세주가 될 거예요. 이 명령어는 파드의 설정 값뿐만 아니라, 가장 중요한 이벤트(Events) 기록을 보여줘요. 왜 파드가 생성되지 않는지, 왜 노드에 배치되지 못하는지 등에 대한 원인이 하단에 상세히 적혀 있어요. 장애 대응 시 가장 먼저 실행해야 할 필수 코스예요.
STEP 2. 파드 생성, 수정 및 삭제 관리하기
파드를 직접 생성하고 싶을 때는 kubectl run 명령어를 사용해요. 하지만 실무에서는 대부분 YAML 파일을 이용한 kubectl apply -f [파일명].yaml 방식을 사용하죠. 이 방식은 선언적이라서 설정이 바뀌었을 때 다시 적용하기 매우 편리해요.
운영 중에 파드의 설정을 살짝 바꿔야 한다면 kubectl edit pod [파드이름]을 사용해 보세요. 텍스트 에디터가 열리면서 즉시 수정이 가능해요. 다만, 파드는 한 번 생성되면 이미지 주소 같은 핵심 설정은 수정이 불가능한 경우가 많으니 주의해야 해요. 이럴 때는 기존 파드를 삭제하고 다시 생성하는 것이 깔끔해요.
파드를 삭제할 때는 kubectl delete pod [파드이름]을 사용해요. 만약 파드가 ‘Terminating’ 상태에서 멈춰서 지워지지 않는다면, –force 옵션을 사용해 강제로 종료할 수 있어요. 하지만 이는 최후의 수단으로만 사용해야 해요.
STEP 3. 로그 확인과 컨테이너 내부 진입하기
파드가 실행은 되었는데 서비스가 안 된다면, 범인은 보통 컨테이너 내부의 로그에 있어요. kubectl logs [파드이름] 명령어를 치면 애플리케이션이 남긴 표준 출력(stdout)을 볼 수 있어요. 로그가 계속 올라오는 것을 실시간으로 보고 싶다면 -f 옵션을 꼭 붙여주세요. 마치 tail -f를 쓰는 것처럼 실시간으로 로그를 추적할 수 있어요.
만약 파드 내부에 여러 개의 컨테이너가 있다면,
-c [컨테이너이름] 옵션을 사용해 어떤 컨테이너의 로그를 볼 것인지 명시해야 해요.더 깊숙이 들어가고 싶다면 kubectl exec -it [파드이름] -- /bin/bash 명령어를 사용하세요. 파드 내부의 쉘(Shell)로 직접 접속하는 거예요. 여기서 직접 네트워크 통신을 테스트하거나, 설정 파일을 직접 열어보는 등 강력한 디버깅이 가능해져요.
STEP 4. 고급 필터링과 출력 포맷 활용하기
관리해야 할 파드가 수백 개라면 하나씩 이름을 치는 건 불가능해요. 이때는 라벨(Label)을 활용한 필터링이 빛을 발해요. kubectl get pods -l app=nginx처럼 입력하면, 라벨이 지정된 특정 앱의 파드들만 쏙 골라낼 수 있어요.
또한, 자동화 스크립트를 만들 때는 출력 형식을 바꿔야 해요. -o json이나 -o yaml 옵션을 사용하면 파드의 모든 정보를 구조화된 데이터로 받을 수 있어요. 특정 필드 값만 뽑아내고 싶다면 jsonpath를 함께 사용해 보세요. 예를 들어 모든 파드의 IP 주소만 리스트로 뽑아내는 작업도 단 한 줄의 명령어로 끝낼 수 있답니다.
[실전 시나리오] 파드 장애 대응 워크플로우
실제로 장애가 발생했을 때 제가 사용하는 순서를 예시로 보여드릴게요.
kubectl get pods -A: 어떤 네임스페이스의 파드가 문제인지 확인해요.kubectl get pods [파드이름] -n [네임스페이스]: 상태가Error나CrashLoopBackOff인지 확인해요.kubectl logs [파드이름] -n [네임스페이스] --tail=100: 최근 로그 100줄을 보고 애플리케이션 에러 메시지를 찾아내요.kubectl describe pod [파드이름] -n [네임스페이스]: 로그에 아무것도 없다면, 쿠버네티스 이벤트(Events)를 보고 스케줄링 문제인지 확인해요.kubectl exec -it [파드이름] -n [네임스페이스] -- /bin/sh: 컨테이너 내부로 들어가서 환경 변수나 네트워크 연결 상태를 직접 점검해요.
자주 하는 실수와 해결법 + FAQ
운영 업무를 하다 보면 명령어 하나 때문에 땀을 뻘뻘 흘리는 순간이 있어요. 많은 분이 반복하는 실수들을 모아봤어요.
- ❌ 실수: 네임스페이스를 지정하지 않고 명령어를 날려요.
왜 발생하는가: 기본 네임스페이스인default만 조회되기 때문에, 실제 서비스가 있는 파드가 안 보인다고 당황하게 돼요.
✅ 해결법: 항상-n [네임스페이스명]을 붙이거나,kubectl config set-context --current --namespace=[네임스페이스명]으로 기본 네임스페이스를 설정해 두세요. - ❌ 실수: 파드 이름만 입력하고 컨테이너 이름을 빼먹어요.
왜 발생하는가: 파드 안에 컨테이너가 여러 개 있는 경우(Sidecar 패턴 등), 어떤 로그를 볼지 지정하지 않으면 에러가 나요.
✅ 해결법:-c [컨테이너이름]옵션을 사용하는 습관을 들여야 해요. - ❌ 실수:
describe의 이벤트만 보고 로그를 안 봐요.
왜 발생하는가: 이벤트는 인프라 수준의 문제(메모리 부족, 노드 문제)를 알려주지만, 애플리케이션 코드의 에러는 로그에만 남기 때문이에요.
✅ 해결법: 인프라 문제가 아니면 반드시kubectl logs를 병행하세요. - ❌ 실수:
apply를 할 때 기존 YAML 파일과 다른 내용을 명령어로만 수정해요.
왜 발생하는가: 나중에 다시apply를 실행하면 명령어로는 수정했던 내용이 다시 덮어씌워져 사라져요.
✅ 해결법: 모든 설정 변경은 반드시 YAML 파일을 수정하고apply하는 방식으로 관리해야 해요. - ❌ 실수: 잘못된 컨텍스트에서 삭제 명령을 내려요.
왜 발생하는가: 운영 환경과 개발 환경의 접속 정보가 섞여 있을 때 발생해요.
✅ 해결법: 명령어를 치기 전kubectl config current-context로 현재 위치를 꼭 확인하세요.
자주 묻는 질문
Q. 파드가 계속 재시작되는데, 이전 실행 시의 로그를 볼 수 있나요?
네, 가능해요! 파드가 재시작되면 이전 컨테이너의 로그는 사라지지만, kubectl logs [파드이름] --previous 명령어를 사용하면 재시작되기 직전의 로그를 확인할 수 있어요. 에러 원인을 찾는 데 아주 유용해요.
Q. 특정 라벨을 가진 파드들만 한꺼번에 삭제할 수 있나요?
물론이에요. kubectl delete pods -l app=my-app처럼 라벨 셀렉터를 사용하면 해당 라벨을 가진 모든 파드를 한 번에 삭제할 수 있어요. 다만, 실수하면 대형 사고로 이어지니 꼭 get 명령어로 먼저 대상을 확인한 뒤 실행하세요.
Q. 파드 내부의 파일을 로컬 PC로 가져오고 싶을 때는 어떻게 하나요?
kubectl cp [네임스페이스]/[파드이름]:[컨테이너내부경로] [로컬경로] 명령어를 사용하면 돼요. 마치 scp 명령어를 쓰는 것처럼 편리하게 파일을 복사할 수 있어요.
Q. 로컬에서 돌아가는 웹 브라우저로 파드 서비스를 확인하고 싶어요.
kubectl port-forward [파드이름] [로컬포트]:[파드포트] 명령어를 사용해 보세요. 이 명령어를 실행하면 파드의 포트가 내 로컬 PC의 포트와 터널로 연결되어, 외부 노출 없이도 안전하게 테스트할 수 있어요.
Q. 파드의 자원 사용량(CPU, 메모리)을 실시간으로 볼 수 있나요?
기본 kubectl 명령어만으로는 어렵지만, kubectl top pod 명령어를 사용하면 현재 사용량을 확인할 수 있어요. 단, 클러스터에 metrics-server가 설치되어 있어야 한다는 전제 조건이 있어요.
실전 운영을 위한 마지막 체크리스트
쿠버네티스 운영은 결국 얼마나 침착하게 상황을 파악하고, 정확한 명령어를 입력하느냐의 싸움이에요. 오늘 배운 내용들을 잊지 않도록 아래 요약표를 잘 간직해 두세요.
- 상태 확인:
get pods(목록),describe pod(상세 정보 및 이벤트) - 로그 확인:
logs -f(실시간),logs --previous(재시작 전 로그) - 디버깅:
exec -it(내부 진입),port-forward(로컬 연결) - 필터링:
-l [라벨](라벨 기반),-n [네임스페이스](범위 지정) - 관리:
apply -f(설정 적용),delete pod(삭제)
오늘 배운 명령어들을 눈으로만 보지 마시고, 지금 당장 테스트 환경에서 직접 타이핑해 보세요. 손에 익어야 진짜 내 실력이 됩니다.
오늘 할 일: 테스트용 파드를 하나 생성해 보고, describe 명령어로 이벤트 기록 확인하기
이번 주 할 일: kubectl logs와 exec 명령어를 조합해 컨테이너 내부 설정 파일 점검해 보기
실습 중에 명령어가 뜻대로 작동하지 않거나, 예상치 못한 에러 메시지가 나온다면 주저하지 말고 댓글로 질문을 남겨 주세요. 함께 고민해 드릴게요!
💡 다음 단계로 넘어가고 싶다면, 쿠버네티스 파드 기본 개념 정리 글이나 클러스터 구축 입문 가이드를 읽어보시는 것을 추천해요.
