[k8s] kubectl 명령어 완벽 가이드: 클러스터 관리 필수 명령어

목차

• kubectl 명령어, 13년 경력자도 매일 찾아보는 이유
• kubectl이 뭔지 잠깐만 짚고 가요
• 1. 클러스터 기본 정보 조회 명령어
• 1-1. 클러스터 정보 확인
• 1-2. 노드(Node) 조회
• 2. 파드(Pod) 관련 필수 명령어
• 2-1. 파드 조회
• 2-2. 파드 상세 정보 및 로그
• 2-3. 파드 내부 접속 및 실행
• 3. 리소스 생성 및 수정 명령어
• 3-1. 리소스 생성
• 3-2. 리소스 수정
• 3-3. 롤아웃(Rollout, 배포) 관리
• 4. 서비스 및 네트워크 관련 명령어
• 4-1. 서비스 조회 및 포트 포워딩
• 5. kubectl 디버깅 필수 명령어
• 5-1. 이벤트 조회
• 5-2. 리소스 사용량 및 상태 확인
• 5-3. 임시 디버그 파드 실행

kubectl 명령어, 13년 경력자도 매일 찾아보는 이유

쿠버네티스(Kubernetes)를 처음 배울 때 가장 먼저 맞닥뜨리는 게 바로 kubectl 명령어입니다. 저도 처음엔 이게 뭔가 싶었거든요. 도커(Docker)는 어느 정도 익숙해졌는데, kubectl 앞에서는 또 새로 공부해야 하나 싶은 막막함이 있었어요.

근데 솔직히 말씀드리면, 13년 경력인 저도 지금도 자주 찾아봅니다. 워낙 옵션이 많고, 상황마다 쓰는 명령어가 다르거든요. 그래서 이번엔 제가 실무에서 진짜 자주 쓰는 명령어들, 그리고 "이게 왜 안 되지?"하고 삽질했던 경험까지 싹 정리해봤습니다.

kubectl 사용법을 제대로 익혀두면 쿠버네티스 클러스터 관리가 훨씬 수월해집니다. 이 글에서는 클러스터 조회부터 디버깅, 리소스 관리까지 실무에서 바로 쓸 수 있는 필수 명령어들을 카테고리별로 정리해드릴게요.

kubectl 명령어는 크게 조회, 생성/수정, 삭제, 디버깅, 클러스터 관리 카테고리로 나뉩니다. 각 카테고리별로 필수 명령어를 익혀두면 쿠버네티스 클러스터 관리가 훨씬 쉬워집니다.

---

kubectl이 뭔지 잠깐만 짚고 가요

쉽게 말해, kubectl은 쿠버네티스 클러스터에 명령을 내리는 CLI(Command Line Interface, 명령줄 인터페이스) 도구입니다. 쿠버네티스 API 서버와 통신하면서 파드(Pod), 서비스(Service), 디플로이먼트(Deployment) 같은 리소스들을 만들고, 조회하고, 수정하고, 삭제하는 역할을 하죠.

기본 구조는 이렇습니다:

kubectl [명령어] [리소스 타입] [리소스 이름] [옵션]

예를 들어 kubectl get pods my-app이라고 하면, "파드(pods) 중에서 my-app이라는 걸 조회(get)해줘"라는 뜻이에요. 구조 자체는 단순한데, 옵션이 어마어마하게 많아서 처음엔 좀 헷갈립니다 ㅎㅎ.

---

1. 클러스터 기본 정보 조회 명령어

가장 먼저 클러스터 상태부터 확인해야죠. 제가 새 환경에 접속하면 제일 먼저 치는 명령어들입니다.

1-1. 클러스터 정보 확인

# 클러스터 기본 정보
kubectl cluster-info

# 현재 컨텍스트(context, 연결된 클러스터) 확인
kubectl config current-context

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

# 컨텍스트 전환 (멀티 클러스터 관리 시 필수!)
kubectl config use-context [컨텍스트명]

# API 서버 버전 확인
kubectl version --short

💡 팁: 멀티 클러스터 환경에서 컨텍스트 전환을 자주 하다 보면 실수로 운영 클러스터에 명령어를 날리는 경우가 생깁니다. 저도 한 번 그랬거든요... 그래서 저는 프롬프트에 현재 컨텍스트를 항상 표시해두는 편이에요.

1-2. 노드(Node) 조회

# 노드 목록 조회
kubectl get nodes

# 노드 상세 정보 (IP, OS, 역할 포함)
kubectl get nodes -o wide

# 특정 노드 상세 정보
kubectl describe node [노드명]

# 노드 리소스 사용량 (metrics-server 설치 필요)
kubectl top nodes

---

2. 파드(Pod) 관련 필수 명령어

실무에서 가장 많이 쓰는 건 역시 파드 관련 명령어입니다. 파드는 쿠버네티스에서 컨테이너가 실행되는 가장 작은 단위거든요.

2-1. 파드 조회

# 현재 네임스페이스의 파드 목록
kubectl get pods

# 모든 네임스페이스의 파드 조회 (전체 현황 파악 시 유용)
kubectl get pods --all-namespaces
# 또는 축약형
kubectl get pods -A

# 특정 네임스페이스의 파드 조회
kubectl get pods -n [네임스페이스명]

# IP, 노드 정보 포함해서 조회
kubectl get pods -o wide

# 실시간 상태 변화 감시 (watch)
kubectl get pods -w

# 특정 라벨(label)로 필터링
kubectl get pods -l app=my-app

2-2. 파드 상세 정보 및 로그

# 파드 상세 정보 (Events 섹션이 트러블슈팅의 핵심!)
kubectl describe pod [파드명]

# 파드 로그 조회
kubectl logs [파드명]

# 실시간 로그 스트리밍 (tail -f 같은 느낌)
kubectl logs -f [파드명]

# 최근 100줄만 조회
kubectl logs --tail=100 [파드명]

# 멀티 컨테이너 파드에서 특정 컨테이너 로그
kubectl logs [파드명] -c [컨테이너명]

# 이전에 크래시된 컨테이너 로그 (재시작 원인 파악 시 필수)
kubectl logs [파드명] --previous

⚠️ 주의: --previous 옵션은 파드가 재시작된 경우에만 동작합니다. 파드가 삭제되고 새로 생성된 경우엔 이전 로그를 볼 수 없어요. 로그 영구 보존이 필요하면 Loki나 Elasticsearch 같은 로그 수집 시스템을 별도로 구축해야 합니다.

2-3. 파드 내부 접속 및 실행

# 파드 내부에 bash 셸로 접속
kubectl exec -it [파드명] -- /bin/bash

# bash가 없는 경우 (alpine 기반 이미지 등)
kubectl exec -it [파드명] -- /bin/sh

# 파드 안에서 단일 명령어 실행
kubectl exec [파드명] -- env

# 특정 컨테이너에 접속
kubectl exec -it [파드명] -c [컨테이너명] -- /bin/bash

처음엔 -it 옵션이 뭔가 싶었는데, -i는 interactive(대화형), -t는 tty(터미널 할당)입니다. 셸로 접속할 때는 둘 다 붙여줘야 제대로 동작해요.

---

3. 리소스 생성 및 수정 명령어

조회만 할 줄 알면 반쪽짜리죠. 실제로 리소스를 만들고 수정하는 kubectl 명령어도 알아야 합니다.

3-1. 리소스 생성

# YAML 파일로 리소스 생성
kubectl apply -f [파일명.yaml]

# 디렉토리 내 모든 YAML 적용
kubectl apply -f ./manifests/

# URL에서 직접 적용 (공식 예제 실습 시 자주 씀)
kubectl apply -f https://example.com/manifest.yaml

# 명령형으로 디플로이먼트 생성 (빠른 테스트용)
kubectl create deployment my-app --image=nginx:1.21

# 네임스페이스 생성
kubectl create namespace my-namespace

💡 apply vs create 차이: create는 이미 존재하면 에러가 나고, apply는 없으면 생성, 있으면 업데이트합니다. 실무에서는 apply를 훨씬 많이 씁니다. GitOps 방식으로 쿠버네티스 클러스터를 관리할 때 특히 유용하더라고요.

3-2. 리소스 수정

# 리소스를 에디터로 직접 수정
kubectl edit deployment [디플로이먼트명]

# 이미지 변경 (롤링 업데이트 트리거)
kubectl set image deployment/[디플로이먼트명] [컨테이너명]=[새이미지:태그]

# 레플리카(replica, 복제본) 수 조정
kubectl scale deployment [디플로이먼트명] --replicas=3

# 특정 필드를 JSON Patch로 수정
kubectl patch deployment [디플로이먼트명] -p '{"spec":{"replicas":5}}'

kubectl apply 명령어가 실행되면 API 서버를 통해 etcd에 저장되고, 컨트롤러가 원하는 상태로 파드를 조정하는 전체 흐름을 나타낸 다이어그램입니다.

3-3. 롤아웃(Rollout, 배포) 관리

# 배포 상태 확인
kubectl rollout status deployment/[디플로이먼트명]

# 배포 이력 조회
kubectl rollout history deployment/[디플로이먼트명]

# 이전 버전으로 롤백 (장애 시 생명줄!)
kubectl rollout undo deployment/[디플로이먼트명]

# 특정 버전으로 롤백
kubectl rollout undo deployment/[디플로이먼트명] --to-revision=2

# 배포 일시 중지/재개
kubectl rollout pause deployment/[디플로이먼트명]
kubectl rollout resume deployment/[디플로이먼트명]

롤백 명령어는 진짜 실무에서 몇 번 써봤는데, 쓸 때마다 심장이 쫄깃해집니다 ㅎㅎ. rollout undo 치고 배포 상태 보면서 "제발 됩시다..."하는 그 느낌 있잖아요.

---

4. 서비스 및 네트워크 관련 명령어

4-1. 서비스 조회 및 포트 포워딩

# 서비스 목록 조회
kubectl get services
# 축약형
kubectl get svc

# 서비스 상세 정보
kubectl describe svc [서비스명]

# 포트 포워딩 (로컬에서 클러스터 내부 서비스 접근 시)
kubectl port-forward svc/[서비스명] 8080:80

# 파드에 직접 포트 포워딩
kubectl port-forward pod/[파드명] 8080:80

# 인그레스(Ingress) 조회
kubectl get ingress
kubectl get ing

포트 포워딩은 개발/디버깅 환경에서 정말 자주 씁니다. 로드밸런서 없이 로컬에서 서비스를 바로 테스트할 수 있거든요. 실무에서 운영 환경 직접 접근이 막혀있을 때 이만큼 편한 게 없더라고요.

---

5. kubectl 디버깅 필수 명령어

이 섹션이 사실 제일 중요합니다. 쿠버네티스 클러스터 관리하다 보면 문제가 안 생기는 날이 없거든요. kubectl 디버깅 명령어를 제대로 알아두면 장애 시간을 확 줄일 수 있습니다.

5-1. 이벤트 조회

# 클러스터 이벤트 전체 조회 (문제 파악의 시작)
kubectl get events

# 특정 네임스페이스 이벤트
kubectl get events -n [네임스페이스]

# 시간순 정렬
kubectl get events --sort-by='.lastTimestamp'

# Warning 이벤트만 필터링
kubectl get events --field-selector type=Warning

5-2. 리소스 사용량 및 상태 확인

# 파드별 CPU/메모리 사용량 (metrics-server 필요)
kubectl top pods
kubectl top pods -A

# 특정 네임스페이스
kubectl top pods -n [네임스페이스]

# 리소스 할당량 확인
kubectl describe resourcequota -n [네임스페이스]

# PVC(PersistentVolumeClaim, 영구 볼륨 요청) 상태
kubectl get pvc
kubectl get pv

5-3. 임시 디버그 파드 실행

# 네트워크 디버깅용 임시 파드 실행
kubectl run debug-pod --image=busybox --rm -it --restart=Never -- sh

# curl이 있는 이미지로 HTTP 테스트
kubectl run curl-test --image=curlimages/curl --rm -it --restart=Never -- sh

# 특정 노드에 디버그 파드 배치
kubectl run debug-pod --image=busybox --rm -it --restart=Never \
  --overrides='{"spec":{"nodeName":"[노드명]"}}' -- sh

📚 함께 읽으면 좋은 글

• 쿠버네티스 보안 강화: 베스트 프랙티스 가이드
• Istio 서비스 메시 완벽 가이드: 설치부터 트래픽 관리, 보안까지
• 쿠버네티스 Pod 트러블슈팅: CrashLoopBackOff, OOMKilled 완벽 해결