Kubectl 핵심 명령어 정리 — 실무에서 자주 쓰는 것 위주

kubectl은 Kubernetes API 서버와 대화하는 가장 기본적인 CLI입니다.

쿠버네티스를 익힌다는 것은 결국 kubectl 손에 익히기다. 매일 쓰는 명령어부터 디버깅 치트 시트까지 한번에 정리한다.

들어가며

쿠버네티스 클러스터에 어떤 일이 일어나는지 알기 위한 첫 번째 도구는 kubectl이다. API 서버는 JSON / protobuf 기반 HTTP 통신을 지원하지만 그대로 쓰기엔 불편하기 때문에, 거의 모든 K8s 작업은 kubectl이라는 CLI를 통해 수행된다.

이 글에서는 실무에서 가장 자주 쓰는 kubectl 명령어를 카테고리별로 정리한다. 단순 레퍼런스보다는, "어떤 상황에서 어떤 명령어를 쓰는지"에 초점을 맞춰 설명한다.

---

1. 한눈에 보는 kubectl 명령어 분류

apply     ─ 원하는 상태 적용 (주로 -f 옵션과 함께)
get       ─ 리소스 리스트 조회
describe  ─ 리소스 상세 상태 조회
delete    ─ 리소스 제거
logs      ─ 컨테이너 로그 조회
exec      ─ 컨테이너에 명령어 전달
config    ─ kubectl 설정/컨텍스트 관리

이 일곱 개만 자유롭게 다룰 수 있어도 일상 운영의 80%는 끝난다. 하나씩 살펴보자.

---

kubectl 명령은 API Server를 통해 Pod, Service, Deployment 같은 리소스 상태를 조회·변경합니다.

2. apply — 원하는 상태를 선언한다

kubectl apply -f {File_Name or URL}

쿠버네티스의 핵심 철학은 "Desired State" 다. 즉, 명령형으로 "어떻게"를 지시하는 대신 YAML 파일에 "어떤 상태" 인지를 선언한다.

# 예시
kubectl apply -f pod.yaml
kubectl apply -f https://raw.githubusercontent.com/.../deployment.yaml

실무에서는 보통 kubectl create 보다 kubectl apply 가 권장된다. 차이점은 다음과 같다.

• create: 같은 리소스가 이미 있으면 에러
• apply: 차분(Diff)을 계산해 변경 사항만 반영. CI/CD 자동화에 적합

---

3. get — 리소스 조회의 기본기

kubectl get {타입}
kubectl get {타입},{타입}
kubectl get all
kubectl get {타입} -o {원하는 포맷}
kubectl get {타입} --show-labels

3-1. Pod 조회 (복수형/축약형)

kubectl get pod
kubectl get pods
kubectl get po

세 명령어는 모두 동일하다. 익숙해지면 가장 짧은 kubectl get po 를 즐겨 쓴다.

3-2. 여러 타입 한 번에 조회

kubectl get pod,service                # Pod + Service
kubectl get pod,service,deployment     # 3개도 가능
kubectl get all                        # 클러스터의 거의 모든 리소스

kubectl get all은 trouble-shooting 시작점이다. "뭐가 떠 있는지" 빠르게 확인할 때 유용하다.

3-3. 출력 포맷 변경

kubectl get pod -o json    # JSON
kubectl get pod -o yaml    # YAML (자주 사용)
kubectl get pod -o wide    # 노드 이름, IP 등 추가 정보 포함

-o yaml 은 "이미 떠 있는 리소스의 정확한 명세"를 다시 추출할 때 매우 유용하다. CI/CD에서 환경별 차이를 비교할 때도 자주 쓰인다.

3-4. 라벨 확인

kubectl get pod --show-labels

라벨은 K8s 리소스 관리의 핵심이다. 디버깅 시 라벨 누락 여부를 가장 먼저 확인하자.

---

4. describe — 리소스 상세 보기

kubectl describe {타입}/{리소스 이름}
kubectl describe {타입} {리소스 이름}

get 으로 리소스 이름을 확인한 뒤, 상세 상태가 필요할 때 사용한다.

kubectl describe pod/wordpress-mysql-5447bfc5b-n6gz2

확인할 수 있는 정보 예시.

• 상태(Status), 라벨(Labels), IP
• 컨테이너 이미지, 환경 변수, 마운트된 볼륨
• 최근 이벤트(Events) — 이게 디버깅에서 가장 중요!

Pod가 안 뜨거나 CrashLoopBackOff에 빠졌을 때, 가장 먼저 보는 곳이 describe의 Events 섹션이다.

---

5. delete — 리소스 제거

kubectl delete {타입}/{리소스 이름}
kubectl delete {타입} {리소스 이름}
kubectl delete -f {리소스 파일명}

# 단일 Pod 제거
kubectl delete pod/wordpress-mysql-5447bfc5b-n6gz2

# YAML 파일에 정의된 모든 리소스 제거
kubectl delete -f deployment.yaml

⚠️ 주의: Pod를 직접 삭제해도 다시 생성되는 경우가 있다. 이는 ReplicaSet이 "Pod 개수를 유지" 하고 있기 때문이다. 진짜 제거하려면 상위 오브젝트(Deployment, ReplicaSet) 를 삭제하자.

---

6. logs — 컨테이너 로그 조회

kubectl logs [Pod 이름]
kubectl logs -f [Pod 이름]                # 실시간 스트리밍
kubectl logs [Pod 이름] -c [컨테이너 이름]   # 멀티 컨테이너

자주 쓰는 패턴

# 마지막 100줄만 보기
kubectl logs --tail=100 my-app-pod

# 실시간 스트림 (tail -f 와 동일)
kubectl logs -f my-app-pod

# 이전(crash 직전) 컨테이너 로그
kubectl logs my-app-pod --previous

--previous 는 CrashLoopBackOff 디버깅의 핵심이다. 죽은 컨테이너의 마지막 stdout을 그대로 보여준다.

---

7. exec — 컨테이너 내부 진입

kubectl exec [pod] -- [Command]
kubectl exec -it [pod] -- [Command]

Docker의 docker exec 와 거의 동일하다. 컨테이너 내부에서 직접 명령을 실행하거나 셸로 진입할 때 사용한다.

# 파일 리스트 확인
kubectl exec my-app-pod -- ls /app

# 인터랙티브 셸 진입
kubectl exec -it my-app-pod -- bash
kubectl exec -it my-app-pod -- sh        # alpine 등 bash가 없을 때

# 멀티 컨테이너 Pod에서 특정 컨테이너 지정
kubectl exec -it my-app-pod -c sidecar -- bash

-it 는 --stdin --tty 의 줄임말. SSH 접속 같은 인터랙티브 환경을 원할 때 필수.

---

8. config — 멀티 클러스터 컨텍스트 관리

kubectl config [Command]

여러 개의 K8s 클러스터(개발, 스테이징, 프로덕션)를 동시에 다룰 때 사용한다.

# 현재 컨텍스트 확인
kubectl config current-context

# 컨텍스트 목록
kubectl config get-contexts

# 컨텍스트 전환
kubectl config use-context dev-cluster
kubectl config use-context prod-cluster

Minikube, EKS, GKE 등을 함께 쓸 때 컨텍스트 전환 실수는 사고의 단골 원인이다. 프롬프트에 현재 컨텍스트를 띄워주는 [kube-ps1](https://github.com/jonmosco/kube-ps1) 같은 도구를 함께 쓰는 것을 권장.

---

9. 알아두면 유용한 보조 명령어

# 전체 API 리소스 종류 확인
kubectl api-resources

# 특정 리소스의 명세(스키마) 확인 - 공식 문서 대용으로 매우 유용
kubectl explain pod
kubectl explain pod.spec.containers
kubectl explain deployment.spec.strategy

kubectl explain 은 사실상 "내장 매뉴얼"이다. YAML 작성하다 막힐 때 공식 문서 보러 가기 전에 먼저 시도해보자.

---

장애 대응에서는 describe → logs → exec 순서로 원인을 좁혀가는 경우가 많습니다.

10. 실무 디버깅 치트 시트

상황	명령어
Pod가 왜 안 뜨지?	kubectl describe pod {name} → Events 확인
Pod가 계속 재시작	kubectl logs {name} --previous
컨테이너 내부 확인	kubectl exec -it {name} -- sh
떠 있는 모든 리소스	kubectl get all -A (-A: 모든 네임스페이스)
노드 자원 확인	kubectl top node, kubectl top pod
YAML 정확한 스펙	kubectl get {type} {name} -o yaml
변경 사항 적용	kubectl apply -f xxx.yaml
변경 사항 롤백	kubectl rollout undo deployment/{name}

---

마무리

쿠버네티스의 모든 명령어를 외울 필요는 없다. 다만 "이런 일을 하고 싶을 때 어떤 명령어를 쓰는지" 의 매핑은 머릿속에 그려져 있어야 한다.

옵션이 너무 많아 헷갈린다면 두 가지를 기억하자.

1. kubectl explain 으로 필드 스키마를 즉석에서 확인한다.
2. --help 는 모든 서브커맨드에서 동작한다. (kubectl get --help, kubectl logs --help)

이 두 가지만으로도 거의 모든 옵션을 즉석에서 찾을 수 있다.