kubectl 소개

kubectl은 Kubernetes API Server와 통신하는 표준 CLI입니다. 클러스터 생성 도구가 아니라, 이미 존재하는 클러스터의 객체를 조회하고 변경하고 장애를 확인하는 운영 도구에 가깝습니다.

kubectl을 잘 쓰려면 명령어 암기보다 context, namespace, resource type, name, output format의 조합을 이해해야 합니다.

현재 접속 대상 확인

kubectl version
kubectl config get-contexts
kubectl config current-context
kubectl cluster-info
kubectl get nodes -o wide

운영 환경에서 가장 흔한 실수는 잘못된 context나 namespace에 명령을 실행하는 것입니다. 삭제나 scale 같은 변경 전에는 항상 context를 확인합니다.

kubectl config use-context lab
kubectl config set-context --current --namespace default
kubectl get pods

조회 기본기

kubectl get pods
kubectl get pods -A
kubectl get deployment,svc,ingress
kubectl get pod web-abc123 -o wide
kubectl describe pod web-abc123

get은 목록과 상태를 빠르게 보는 명령이고, describe는 이벤트, 스케줄링 실패, 이미지 pull 실패, probe 실패 같은 이유를 확인할 때 씁니다.

로그와 컨테이너 접근

kubectl logs deployment/web
kubectl logs pod/web-abc123 -c nginx --tail=100
kubectl logs pod/web-abc123 --previous
kubectl exec -it pod/web-abc123 -- sh

--previous는 컨테이너가 재시작된 뒤 이전 컨테이너 로그를 볼 때 유용합니다. CrashLoopBackOff를 볼 때 먼저 확인합니다.

선언형 적용

kubectl diff -f manifests/
kubectl apply -f manifests/
kubectl apply -k overlays/prod
kubectl rollout status deployment/web

운영에서는 kubectl edit로 즉시 수정하기보다 manifest를 수정하고 diff/apply/rollout 순서로 반영하는 편이 변경 이력을 남기기 좋습니다.

배포 롤백과 스케일

kubectl rollout history deployment/web
kubectl rollout undo deployment/web
kubectl scale deployment/web --replicas=3
kubectl set image deployment/web nginx=nginx:1.27

이미지 태그를 latest로 운영하면 같은 manifest인데 실제 이미지가 달라질 수 있습니다. 가능하면 명시 태그나 digest를 사용합니다.

출력 형식 활용

kubectl get pods -o wide
kubectl get pods -o yaml
kubectl get pods -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.phase}{"\n"}{end}'
kubectl get events -A --sort-by=.lastTimestamp

장애 확인 순서

1. kubectl get pods -A로 Pending, CrashLoopBackOff, ImagePullBackOff를 찾습니다.
2. kubectl describe pod로 이벤트와 scheduling reason을 봅니다.
3. kubectl logs --previous로 재시작 전 로그를 확인합니다.
4. kubectl get nodes와 kubectl describe node로 Node pressure를 확인합니다.
5. Service/Ingress 문제면 endpoint와 selector label을 확인합니다.

kubectl get svc web -o yaml
kubectl get endpoints web -o wide
kubectl get pod --show-labels

주의할 명령

kubectl delete pod web-abc123
kubectl delete namespace test
kubectl replace --force -f app.yaml

Pod 삭제는 Deployment가 관리 중이면 새 Pod가 다시 생길 수 있습니다. namespace 삭제는 하위 리소스를 광범위하게 제거하므로 대상과 context를 반드시 재확인합니다.

공식 문서

• Command line tool kubectl
• kubectl Quick Reference
• kubectl command reference