안녕하세요, 자바파커입니다.
"
kubectl get pods까지는 외웠는데, 막상 Pod가 죽었을 때 뭘 쳐야 할지 막막합니다."
솔직히 저도 그랬습니다. K8S 공식 문서를 열면 명령어가 수십 개 나오는데, 어떤 걸 먼저 익혀야 할지 순서가 없어서 금방 지칩니다. "외워야 한다"는 부담감에 실전에서는 결국 구글링으로 돌아가게 되죠.
결론부터 말씀드리면 — kubectl은 5개 카테고리, 30개 명령어만 외우면 일상 운영의 90%가 커버됩니다. 조회·배포·롤아웃·디버깅·컨텍스트. 이 5개 축으로 정리하면 새 명령어를 만났을 때도 어디에 속하는지 바로 감이 옵니다. 오늘은 이 순서대로, 실전에서 바로 쓰는 패턴까지 정리하겠습니다.
이전 편을 안 보셨다면 K8S에 대한 이해부터 읽어오시면 도움이 됩니다.
kubectl이란?
쿠버네티스를 사용하는 공식 CLI입니다. 본질은 단순합니다 — K8S API Server에 REST 요청을 보내는 클라이언트입니다.
- 단일 바이너리, 크로스 플랫폼 (macOS·Linux·Windows)
- 설정 파일:
~/.kube/config(여러 클러스터 전환 가능) - 서버 버전과 클라이언트 버전은 마이너 1개 차이 이내 권장
# 버전 확인 — 가장 먼저 치는 명령어
kubectl version --short
# 현재 연결된 클러스터 확인
kubectl cluster-info기본 명령 구조
모든 kubectl 명령은 같은 패턴을 따릅니다.
kubectl <동사> <리소스> <이름> [옵션]예시:
kubectl get pod nginx -o yaml
# ──┬── ─┬─ ──┬── ───┬───
# 동사 리소스 이름 옵션리소스 약어 — 외우면 타이핑이 절반
| 약어 | 풀네임 |
|---|---|
po |
pods |
deploy |
deployments |
svc |
services |
ing |
ingresses |
cm |
configmaps |
ns |
namespaces |
no |
nodes |
rs |
replicasets |
pvc |
persistentvolumeclaims |
kubectl api-resources 로 전체 약어 목록을 볼 수 있습니다.
1. 조회(Read) — 가장 많이 쓰는 5개
K8S 운영의 80%는 "지금 뭐가 돌고 있지?"를 확인하는 일입니다.
# 전체 Pod 상태
kubectl get pods
kubectl get pods -o wide # IP·노드 정보까지
kubectl get pods -n kube-system # 특정 네임스페이스
kubectl get pods -l app=nginx # 라벨 필터
kubectl get pods -A # 모든 네임스페이스
kubectl get pods --watch # 실시간 변화 관찰
# 상세 정보 (이벤트·조건·연결 확인)
kubectl describe pod <pod-name>
# 로그
kubectl logs <pod-name>
kubectl logs -f <pod-name> # 실시간 팔로우
kubectl logs --previous <pod-name> # 직전 종료된 컨테이너 로그
kubectl logs --tail=100 <pod-name> # 마지막 100줄
kubectl logs -l app=nginx --all-containers # 라벨 기반 일괄 조회
# 리소스 사용량 (metrics-server 필요)
kubectl top pods
kubectl top nodes
# YAML 원본 추출
kubectl get deployment nginx -o yaml실전 팁:
describe의 맨 아래 Events 섹션을 먼저 읽으세요. Pod가 안 뜨는 이유 80%는 여기에 나옵니다.
2. 배포(Write) — apply 하나로 대부분 해결
선언형(apply)과 명령형(create·run)이 있는데, 실무에선 거의 apply만 씁니다.
# 선언적 배포 — YAML을 원천으로
kubectl apply -f deployment.yaml
kubectl apply -f ./k8s/ # 디렉토리 전체
kubectl apply -k ./overlays/prod # Kustomize 오버레이
# 삭제
kubectl delete -f deployment.yaml
kubectl delete pod <name>
kubectl delete pods --all -n test # 네임스페이스 내 Pod 일괄
# 즉석 편집 (배포본 수정 → 저장 시 반영)
kubectl edit deployment nginx
# 스케일
kubectl scale deployment nginx --replicas=5
# 이미지만 빠르게 교체 (CD 파이프라인에서 자주 사용)
kubectl set image deployment/nginx nginx=nginx:1.28선언형 vs 명령형 선택 기준
| 상황 | 추천 |
|---|---|
| 운영 환경, GitOps | 선언형(apply) |
| 빠른 테스트·실험 | 명령형(run·create) |
| 리뷰·버전 관리 필요 | 선언형(apply) |
실험용으로 명령형 쓸 때도 --dry-run=client -o yaml로 YAML 뽑아서 저장해두는 습관을 들이면 좋습니다.
kubectl create deployment demo --image=nginx --dry-run=client -o yaml > demo.yaml3. 롤아웃 관리 — 배포 추적과 롤백
Deployment를 업데이트할 때 가장 쓸모 있는 명령들입니다.
# 배포 진행 상태 확인 (CD 파이프라인 체크용)
kubectl rollout status deployment/nginx
# 배포 히스토리
kubectl rollout history deployment/nginx
kubectl rollout history deployment/nginx --revision=3 # 특정 리비전 상세
# 롤백
kubectl rollout undo deployment/nginx # 직전 버전
kubectl rollout undo deployment/nginx --to-revision=2 # 특정 버전
# 재시작 (ConfigMap 변경 후 Pod 재생성 강제)
kubectl rollout restart deployment/nginx
# 진행 중인 배포 일시정지 / 재개
kubectl rollout pause deployment/nginx
kubectl rollout resume deployment/nginx실전 팁:
rollout restart는 Secret/ConfigMap 변경 시imagePullPolicy: Always가 아니어도 Pod를 새로 뜨게 해줍니다. 배포 YAML 수정 없이 Pod만 리프레시할 때 유용합니다.
4. 디버깅 — 여기서 진짜 실력이 나옵니다
Pod가 안 뜨거나 이상하게 동작할 때 쓰는 명령들. 입문자가 가장 어려워하는 영역이지만, 패턴 몇 개만 익히면 됩니다.
# 컨테이너 안으로 진입
kubectl exec -it <pod-name> -- bash
kubectl exec -it <pod-name> -- sh # bash 없는 이미지용
kubectl exec <pod-name> -- env # 환경변수만 출력
# 로컬 포트 ↔ Pod/Service 연결 (브라우저에서 테스트)
kubectl port-forward svc/nginx 8080:80
kubectl port-forward pod/nginx-xxxx 8080:80
# 파일 전송
kubectl cp ./local.txt <pod>:/tmp/local.txt
kubectl cp <pod>:/var/log/app.log ./app.log
# 임시 디버그 컨테이너 붙이기 (K8S 1.25+)
kubectl debug -it <pod> --image=busybox --target=<container>
# 네임스페이스 이벤트 모아보기
kubectl get events --sort-by='.lastTimestamp' -n <ns>자주 만나는 에러 3종 대응표
| 상태 | 원인 후보 | 첫 명령 |
|---|---|---|
Pending |
스케줄링 실패 · 리소스 부족 | kubectl describe pod <name> |
CrashLoopBackOff |
앱이 시작 직후 죽음 | kubectl logs --previous <name> |
ImagePullBackOff |
이미지 없음 · 레지스트리 권한 부족 | kubectl describe pod <name> (Events) |
패턴은 동일합니다. describe로 Events 보고 → 필요하면 logs --previous.
5. 컨텍스트 & 네임스페이스 — 여러 클러스터 다룰 때
클러스터가 여러 개(dev·staging·prod)일 때 필수입니다.
# 현재 컨텍스트 / 전체 컨텍스트
kubectl config current-context
kubectl config get-contexts
# 컨텍스트 전환
kubectl config use-context prod-cluster
# 현재 컨텍스트의 기본 네임스페이스 변경
kubectl config set-context --current --namespace=production강력 추천: kubectx / kubens
매번 긴 명령어 치기 귀찮으면 kubectx·kubens를 설치하세요.
# 컨텍스트 전환
kubectx prod
# 네임스페이스 전환
kubens production대화형 선택(fzf 연동)도 되고, 몇 글자 입력하면 자동완성됩니다. 실무에선 사실상 표준입니다.
생산성 팁 4가지
1) alias 세팅
가장 효과 큰 한 줄입니다. 셸 rc 파일(~/.bashrc·~/.zshrc)에 추가하세요.
alias k=kubectl
alias kg='kubectl get'
alias kd='kubectl describe'
alias kl='kubectl logs'2) 자동완성 활성화
# bash
source <(kubectl completion bash)
echo 'source <(kubectl completion bash)' >> ~/.bashrc
complete -F __start_kubectl k # alias에도 자동완성
# zsh
source <(kubectl completion zsh)3) -o jsonpath — 원하는 필드만 뽑기
스크립트에서 자주 쓰는 패턴입니다.
# 모든 Pod 이름
kubectl get pods -o jsonpath='{.items[*].metadata.name}'
# Pod별 노드 확인
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.nodeName}{"\n"}{end}'
# 이미지 목록
kubectl get pods -o jsonpath='{.items[*].spec.containers[*].image}'4) 드라이런 + 서버사이드 검증
# 클라이언트 측 검증 (빠름)
kubectl apply -f app.yaml --dry-run=client
# 서버 측 검증 (admission webhook까지 검증됨, 더 정확)
kubectl apply -f app.yaml --dry-run=serverCI/CD에 --dry-run=server를 끼워두면 배포 사고를 크게 줄일 수 있습니다.
실전 시나리오: "Pod가 안 뜹니다"
입문자들이 가장 많이 겪는 상황. 순서만 정리하면 90%는 해결됩니다.
# 1. 현재 상태 확인
kubectl get pods
# 2. 상세 이벤트 확인 (가장 중요)
kubectl describe pod <pod-name>
# 3. 로그 확인 (컨테이너가 한 번이라도 떴다면)
kubectl logs <pod-name>
kubectl logs --previous <pod-name> # 직전에 죽은 기록
# 4. 네임스페이스 전체 이벤트 스캔
kubectl get events --sort-by='.lastTimestamp' -n <ns>
# 5. 노드 상태 확인
kubectl top nodes
kubectl describe node <node-name>이 흐름은 어떤 장애든 공통입니다. 외워두시면 당황하지 않습니다.
FAQ
Q. kubectl을 매번 풀네임으로 치는 게 너무 귀찮습니다.
alias k=kubectl 한 줄이 시작입니다. 여기에 자동완성까지 붙이면 타이핑이 체감상 1/3로 줄어듭니다. kubectx·kubens까지 붙이면 사실상 완성이라고 봅니다.
Q. 명령형(create)과 선언형(apply) 중 뭘 써야 하나요?
운영은 무조건 선언형(apply)입니다. YAML을 Git에 두고 kubectl apply -f 하나로만 배포하면 히스토리·리뷰·롤백이 모두 Git 기반으로 정리됩니다. 명령형은 일회성 실험이나 빠른 리소스 생성 시에만 사용하세요.
Q. 여러 클러스터를 자주 오갑니다. 실수로 운영에 배포할까봐 걱정입니다.
세 가지를 추천합니다. (1) kube-ps1로 셸 프롬프트에 현재 컨텍스트 표시, (2) 운영 컨텍스트는 이름을 🔴 prod 같이 경고 이모지로 시각화, (3) kubectl apply에 --context=prod 명시적으로 추가. 눈으로 한 번 더 확인하는 장치를 만들어두는 게 안전합니다.
Q. kubectl exec가 안 먹힙니다.
두 가지 가능성이 큽니다. (1) 이미지에 shell이 없음(예: distroless) → kubectl debug로 사이드카 진입, (2) Pod가 Running 상태가 아님 → 먼저 describe로 상태 확인. shell 없는 프로덕션 이미지는 보안상 좋은 선택이지만, 디버깅할 땐 debug 명령이 답입니다.
마무리 — 다음 단계
kubectl 명령어를 한 번에 다 외울 필요는 없습니다. 자주 쓰는 패턴부터 손에 붙이면 나머지는 자연스럽게 따라옵니다. 오늘 정리한 5개 카테고리만 기억해도 충분합니다.
- 조회:
get·describe·logs - 배포:
apply·delete - 롤아웃:
rollout status/undo/restart - 디버깅:
exec·port-forward·describe - 컨텍스트:
config use-context· kubectx·kubens
다음 편에서는 Helm으로 K8S 패키지 관리하기를 다룰 예정입니다. YAML이 수백 줄로 불어나기 전에 Helm을 익혀두면, 환경별 설정 분리·버전 관리·손쉬운 롤백이 기본으로 따라옵니다.
시리즈 다음 주제
- Helm으로 K8S 패키지 관리하기
- HPA·VPA로 오토스케일링 구성
- Ingress + cert-manager로 HTTPS 자동화
- ArgoCD로 GitOps 배포 파이프라인
- kustomize로 환경별 YAML 관리
여러분은 kubectl을 쓰면서 가장 자주 헷갈리거나 "이 명령어 몰랐으면 고생했겠다" 싶었던 게 있나요? 댓글로 공유해주시면 다음 포스팅에 반영하겠습니다.