안녕하세요, 13년차 서버실 지킴이입니다. 오늘도 서버실의 삐걱거리는 소리와 함께 하루를 시작하네요. 😊

인프라 엔지니어로 일하다 보면, 매일같이 손에서 놓지 못하는 도구들이 몇 가지 있습니다. 그중에서도 Kubernetes(쿠버네티스) 클러스터를 운영한다면 kubectl(큐브컨트롤)은 정말 없어서는 안 될 존재거든요. <code>kubectl은 쿠버네티스 클러스터와 상호작용하는 CLI(명령줄 인터페이스) 도구로, 파드(Pod), 서비스(Service), 디플로이먼트(Deployment) 등 모든 리소스(resource)를 관리할 수 있게 해줍니다.

근데 이거, 진짜 제대로 쓰고 있나? 하는 의문, 혹시 여러분도 해보신 적 있으신가요? 저도 처음엔 kubectl get pod, kubectl apply -f 같은 기본적인 명령어만으로 충분하다고 생각했거든요. 하지만 클러스터가 커지고 문제 상황이 복잡해질수록, 더 깊고 강력한 kubectl 활용법이 필요하다는 걸 깨달았습니다. 덕분에 삽질 좀 했습니다만, 그만큼 얻은 꿀팁들도 많았죠. ㅎㅎ

오늘은 13년차 인프라 엔지니어인 제가 직접 현업과 홈랩에서 써보면서 얻은 kubectl 고급 활용법들을 여러분께 알려드리려고 합니다. 특히 Pod, Service, Deployment를 효과적으로 관리하는 팁과 함께, 제가 겪었던 삽질 경험과 트러블슈팅 노하우도 솔직하게 공유해 드릴게요. 이 글을 통해 여러분의 쿠버네티스 운영 생산성이 한층 더 높아지기를 바랍니다!

쿠버네티스 Pod, Service, Deployment는 서로 유기적으로 연결되어 동작합니다. (이미지: 쿠버네티스 핵심 컴포넌트 아키텍처)

핵심 개념 다시 보기: Pod, Service, Deployment

본격적인 팁을 알려드리기 전에, 오늘 다룰 세 가지 핵심 리소스에 대해 간단히 짚고 넘어갈게요. 이미 잘 알고 계시겠지만, 다시 한번 머릿속에 정리하는 시간이라고 생각하시면 좋습니다.

• Pod (파드): 쿠버네티스에서 가장 작고 기본적인 배포 단위입니다. 하나 이상의 컨테이너(Container)를 포함할 수 있으며, 같은 파드 내의 컨테이너들은 네트워크와 스토리지를 공유해요. 쉽게 말해, ‘작업을 수행하는 최소한의 묶음’이라고 보시면 됩니다.
• Service (서비스): 여러 파드에 대한 안정적인 네트워크 접근을 제공하는 추상화 계층이죠. 파드는 언제든 생성되고 삭제될 수 있는데, 서비스는 이런 파드의 동적인 변화와 관계없이 일정한 IP 주소와 DNS 이름을 통해 파드 그룹에 접근할 수 있도록 해줍니다. 마치 변동하는 직원들에게 고정된 부서 전화번호를 할당해주는 것과 같죠.
• Deployment (디플로이먼트): 파드와 ReplicaSet(레플리카셋)을 선언적으로 관리하는 상위 리소스입니다. 애플리케이션의 버전을 관리하고, 원하는 수의 파드를 항상 유지하며, 롤링 업데이트(Rolling Update)나 롤백(Rollback) 같은 배포 전략을 손쉽게 구현할 수 있어요. ‘애플리케이션의 배포와 생명주기를 책임지는 관리자’라고 생각하시면 편합니다.

kubectl 고급 활용법: Pod 관리 팁

파드는 쿠버네티스에서 가장 많이 다루는 리소스 중 하나일 겁니다. 저도 매일 파드 상태를 확인하고, 로그를 보고, 문제가 생기면 파드 안으로 들어가 보곤 하거든요. 몇 가지 유용한 명령어들을 소개합니다.

1. 로그 실시간 확인 (Log Streaming)

애플리케이션 개발이나 트러블슈팅 시 가장 기본이 되는 작업이죠. kubectl logs 명령어로 특정 파드의 로그를 확인할 수 있습니다. 특히 -f (follow) 옵션은 로그를 실시간으로 스트리밍해주기 때문에, 마치 tail -f처럼 동작해서 에러를 잡을 때 정말 유용해요.

# 특정 파드의 로그 실시간 스트리밍
kubectl logs -f my-app-pod-abcdefg

# 특정 컨테이너의 로그만 보기 (파드에 여러 컨테이너가 있을 경우)
kubectl logs -f my-app-pod-abcdefg -c my-container-name

# 마지막 100줄만 보고 싶을 때
kubectl logs --tail=100 my-app-pod-abcdefg

# 특정 시간 이후 로그만 보고 싶을 때
kubectl logs --since=1h my-app-pod-abcdefg # 1시간 이내 로그
kubectl logs --since=2023-01-01T00:00:00Z my-app-pod-abcdefg # 특정 시각 이후 로그

제가 개발 중 에러를 잡을 때 정말 유용하게 썼던 기능입니다. 특히 컨테이너가 갑자기 재시작(restart)될 때, -f 옵션으로 로그를 계속 보고 있으면 어떤 이유로 죽었는지 금방 파악할 수 있더라고요. 💡

2. 컨테이너 내부 접속 (Exec into Container)

파드 안에서 직접 명령어를 실행하거나 파일 시스템을 확인해야 할 때가 있습니다. 마치 SSH로 서버에 접속하는 것처럼, kubectl exec 명령어로 컨테이너 내부에 접속할 수 있어요.

# 특정 파드의 컨테이너 내부로 접속 (bash 셸 사용)
kubectl exec -it my-app-pod-abcdefg -- bash

# 특정 컨테이너 내부로 접속 (파드에 여러 컨테이너가 있을 경우)
kubectl exec -it my-app-pod-abcdefg -c my-container-name -- sh # sh 셸 사용 예시

터미널이 없으면 답답하잖아요? 문제가 생겼을 때 바로 파드 내부로 들어가서 설정 파일을 확인하거나, 특정 명령어를 실행해서 상황을 진단해볼 수 있어서 정말 편하더라고요. ⚠️ 중요한 건 -- 뒤에 실행할 명령어를 붙여야 한다는 점입니다.

3. 자원 사용량 확인 (Resource Usage)

파드가 갑자기 죽거나 성능이 저하되는 원인 중 하나는 CPU나 메모리 같은 리소스 부족인 경우가 많습니다. kubectl top pod 명령어를 사용하면 파드별 리소스 사용량을 한눈에 볼 수 있어요. 다만, 이 기능을 사용하려면 클러스터에 Metrics Server(메트릭스 서버)가 설치되어 있어야 합니다.

# 모든 파드의 CPU 및 메모리 사용량 확인
kubectl top pod

# 특정 네임스페이스의 파드만 확인
kubectl top pod -n my-namespace

# 파드를 CPU 사용량 기준으로 정렬
kubectl top pod --sort-by=cpu

파드가 갑자기 죽는다? 대부분 CPU나 메모리를 너무 많이 쓰는 경우가 많더라고요. kubectl top pod로 확인해서 리소스 제한(resource limit)을 조정해주곤 합니다. 💡

4. Pod 이벤트 확인 (Event Check)

파드가 생성되지 않거나, Pending(대기) 상태에 머무르거나, 예상치 못하게 재시작될 때 그 원인을 알려주는 것이 바로 Event(이벤트)입니다. kubectl describe pod 명령의 하단에 이벤트 정보가 자세히 나옵니다.

# 특정 파드의 상세 정보 및 이벤트 확인
kubectl describe pod my-app-pod-abcdefg

왜 내 파드가 Pending에 머물러 있을까? 답은 Event에 있습니다. 예를 들어, 필요한 볼륨(Volume)이 마운트(mount)되지 않았거나, 노드의 리소스가 부족하거나, 컨테이너 이미지를 풀(pull)하지 못하는 등 다양한 원인이 이벤트로 기록돼요. 저도 처음에 이거 때문에 밤샜습니다. 결국 이벤트 로그에 답이 있더라고요!

kubectl 고급 활용법: Service 관리 팁

서비스는 외부 트래픽을 파드로 연결해주는 중요한 역할을 합니다. 서비스 관련 문제가 생기면 애플리케이션 전체가 먹통이 될 수 있죠. 서비스 관리 팁들을 알아볼게요.

1. 서비스 상세 정보 (Service Details)

서비스의 IP 주소, 포트 매핑, 연결된 파드 정보 등 상세 정보를 확인할 때 kubectl describe service 명령이 유용해요.

# 특정 서비스의 상세 정보 확인
kubectl describe service my-app-service

외부에서 접근이 안 될 때, 제일 먼저 살펴보는 곳입니다. Cluster IP(클러스터 IP), External IP(외부 IP), Port(포트) 매핑 정보가 정확한지 확인하곤 합니다. 특히 Type이 NodePort나 LoadBalancer일 경우, 외부 접근이 가능해야 하는데 안 된다면 여기서 단서를 찾을 수 있죠.

2. 서비스 포트 포워딩 (Port Forwarding)

클러스터 내부의 서비스에 로컬 머신에서 직접 접속해야 할 때가 있습니다. 예를 들어, 개발 중인 로컬 환경에서 클러스터 내부의 데이터베이스 서비스에 연결해야 할 때 유용해요. kubectl port-forward 명령으로 로컬 포트를 서비스 포트에 연결할 수 있습니다.

# 특정 서비스의 80포트를 로컬 8080포트로 포워딩
kubectl port-forward service/my-app-service 8080:80

# 특정 파드의 80포트를 로컬 8080포트로 포워딩 (서비스 대신 파드에 직접 연결)
kubectl port-forward my-app-pod-abcdefg 8080:80

홈랩에서 외부 IP 없이 내부 서비스 테스트할 때 이거 진짜 꿀팁입니다! 로컬에서 개발한 프론트엔드(frontend)가 백엔드(backend) 서비스에 잘 연결되는지 확인할 때 아주 유용하게 썼어요. 🎉

3. 엔드포인트 확인 (Endpoint Verification)

서비스는 파드들의 IP 주소를 모아놓은 Endpoint(엔드포인트)를 기반으로 트래픽을 라우팅합니다. 서비스는 있는데 왜 연결이 안 되지? 싶을 때는 엔드포인트가 제대로 생성되었는지 확인해야 해요. 파드가 정상적으로 Running(실행) 상태여야 엔드포인트에 등록됩니다.

# 특정 서비스에 연결된 엔드포인트 확인
kubectl get endpoints my-app-service

# 모든 엔드포인트 확인
kubectl get ep

서비스는 잘 있는데 왜 연결이 안 되지? 알고 보니 엔드포인트가 비어있을 때가 있더라고요. 파드가 죽었거나, readinessProbe(레디니스 프로브)가 실패해서 엔드포인트에서 제외된 경우였습니다. ⚠️

kubectl 고급 활용법: Deployment 관리 팁

디플로이먼트는 애플리케이션 배포의 핵심입니다. 새로운 버전을 배포하고, 문제가 생기면 이전 버전으로 되돌리고, 트래픽 변화에 따라 파드 개수를 조절하는 등 많은 작업을 디플로이먼트를 통해 하게 됩니다.

다양한 kubectl 명령어를 활용해 Pod, Service, Deployment의 상태를 실시간으로 모니터링하는 모습입니다. (이미지: kubectl 모니터링)

1. 롤링 업데이트 & 롤백 (Rolling Update & Rollback)

새로운 버전의 애플리케이션을 배포할 때, kubectl apply 명령을 사용하면 디플로이먼트가 롤링 업데이트(Rolling Update)를 수행합니다. 이 과정에서 업데이트 상태를 확인하고, 문제가 생겼을 때 이전 버전으로 롤백(Rollback)하는 것이 중요해요.

# 디플로이먼트 롤아웃(rollout) 상태 확인
kubectl rollout status deployment/my-app-deployment

# 디플로이먼트 롤아웃 히스토리(history) 확인
kubectl rollout history deployment/my-app-deployment

# 이전 버전으로 롤백 (이전 리비전으로 되돌리기)
kubectl rollout undo deployment/my-app-deployment

# 특정 리비전으로 롤백
kubectl rollout undo deployment/my-app-deployment --to-revision=2

실수로 잘못된 이미지를 배포했을 때, kubectl rollout undo 이거 한 방이면 되돌릴 수 있어서 얼마나 든든한지 모릅니다. 롤아웃 상태를 보면서 파드가 하나씩 교체되는 걸 지켜보는 것도 꽤 재미있고요. 😅

2. 스케일링 (Scaling)

애플리케이션에 트래픽이 몰리거나 반대로 줄어들 때, 파드의 개수를 동적으로 조절해야 합니다. kubectl scale 명령어를 사용하면 디플로이먼트의 파드 개수를 쉽게 늘리거나 줄일 수 있어요.

# 디플로이먼트의 파드 개수를 5개로 스케일링
kubectl scale deployment/my-app-deployment --replicas=5

# 오토스케일러(Horizontal Pod Autoscaler, HPA) 설정
kubectl autoscale deployment my-app-deployment --cpu-percent=50 --min=2 --max=10

갑자기 트래픽이 몰릴 때, 빠르게 파드를 늘려줄 수 있죠. 물론 HPA를 설정하면 자동으로 스케일링되겠지만, 수동으로 빠르게 대응해야 할 때 이 명령어가 아주 유용해요.

3. 환경 변수/시크릿 확인 (Env/Secret Check)

애플리케이션이 제대로 동작하지 않을 때, 환경 변수(Environment Variable)나 시크릿(Secret) 설정이 잘못되었을 가능성도 있습니다. 디플로이먼트의 상세 정보를 통해 이를 확인할 수 있어요.

# 특정 디플로이먼트의 상세 정보 확인
kubectl describe deployment my-app-deployment

describe 명령의 출력에서 Environment 섹션과 Volumes 섹션을 확인하면, 어떤 환경 변수가 설정되었고 어떤 시크릿이나 컨피그맵(ConfigMap)이 마운트(mount)되었는지 알 수 있습니다. 간혹 환경 변수 오타 때문에 앱이 안 뜨는 경우도 있더라고요. 디스크라이브로 확인하면 됩니다.

⚠️ 삽질 경험 & 트러블슈팅 팁

제가 13년 동안 인프라 엔지니어로 일하면서 수없이 겪었던 삽질 경험들 중, kubectl과 관련하여 특히 기억에 남는 몇 가지를 공유합니다. 여러분은 저처럼 밤새지 마세요! 😅

Problem 1: 파드가 계속 Pending 상태인 경우

새로운 디플로이먼트를 배포했는데, 파드가 Running 상태가 되지 않고 계속 Pending(대기) 상태에 머무는 경우가 있습니다. 저도 처음엔 이게 뭔가 싶어서 계속 파드를 삭제하고 다시 만들고 했었죠.

• 원인:
  • 노드의 리소스(CPU, 메모리) 부족
  • 이미지 풀(Image Pull) 실패 (예: 잘못된 이미지 이름, 프라이빗 레지스트리 인증 실패)
  • 볼륨(PersistentVolume, PersistentVolumeClaim) 바인딩 실패
  • 노드 셀렉터(Node Selector)나 테인트/톨러레이션(Taints/Tolerations) 설정 문제로 스케줄링할 노드를 찾지 못함
• 해결:

  # 파드 상세 정보 확인 (가장 중요!)
  kubectl describe pod <pod-name>
  # 이벤트 섹션에서 FailedScheduling, Failed to pull image 등의 에러 메시지를 찾습니다.
  
  # 노드 리소스 확인
  kubectl top nodes
  
  # 이미지 레지스트리 인증 정보 확인 (Secret)
  kubectl get secret <image-pull-secret-name> -o yaml

  결국 답은 kubectl describe pod의 Events 섹션에 있습니다. 어떤 이유로 파드가 스케줄링되지 못했는지, 이미지를 가져오지 못했는지 자세히 알려주거든요. 저도 이거 때문에 밤샜습니다. 결국 이벤트 로그에 답이 있더라고요! 💡

Problem 2: 서비스가 외부에서 접근 안 되는 경우

분명히 서비스를 만들었고 파드도 잘 돌고 있는데, 외부에서 접속이 안 되는 경우가 있습니다. 특히 클라우드 환경에서 많이 겪었던 문제인데요.

• 원인:
  • 서비스 타입(Service Type) 오설정 (ClusterIP는 외부 접근 불가)
  • 로드밸런서(LoadBalancer)나 인그레스(Ingress) 컨트롤러 문제
  • 클라우드 프로바이더(Cloud Provider)의 방화벽(Firewall) 설정
  • 서비스의 selector와 파드의 labels가 일치하지 않아 엔드포인트가 비어있음
• 해결:

  # 서비스 타입 및 외부 IP 확인
  kubectl get svc <service-name> -o wide
  
  # 엔드포인트 확인 (파드가 서비스에 제대로 연결되었는지)
  kubectl get ep <service-name>
  
  # 서비스 상세 정보 확인
  kubectl describe svc <service-name>

  로드밸런서 타입으로 만들었는데 왜 안 돼? 알고 보니 클라우드 provider 설정 문제였던 적도 있었어요. 예를 들어, GCP나 AWS에서 로드밸런서가 프로비저닝(provisioning)되지 않았거나, 보안 그룹(Security Group) 설정이 잘못되어 있었죠. 😅 항상 엔드포인트와 서비스 타입을 먼저 확인하는 습관을 들이세요!

Problem 3: Deployment 롤아웃이 멈춘 경우

새로운 버전으로 디플로이먼트를 업데이트했는데, 롤아웃이 중간에 멈춰버리고 진행되지 않는 경험, 다들 있으시죠?

• 원인:
  • 새로 생성된 파드가 CrashLoopBackOff 상태로 계속 죽음
  • 파드의 readinessProbe(레디니스 프로브)가 실패하여 새 파드가 Ready 상태가 되지 못함
  • 리소스 부족으로 새 파드가 생성되지 못함
• 해결:

  # 롤아웃 상태 확인
  kubectl rollout status deployment/<deployment-name>
  
  # 새로운 파드의 이름 확인 (롤아웃 중 생성된 파드)
  kubectl get pod -l app=<app-label> --sort-by=.metadata.creationTimestamp
  
  # 문제의 파드 로그 및 이벤트 확인
  kubectl logs <new-pod-name>
  kubectl describe pod <new-pod-name>

  새로운 이미지가 문제가 있어서 기존 파드도 못 죽고 롤아웃이 멈춰버린 경험, 다들 있으시죠? 저도 몇 번 겪었습니다. 이럴 때는 새로 생성되는 파드의 로그와 이벤트를 확인해서 왜 Ready 상태가 되지 못하는지 파악하는 것이 중요해요. 그리고 문제가 파악되면 kubectl rollout undo로 빠르게 이전 버전으로 롤백하는 것이 현명한 방법입니다!

쿠버네티스 환경에서 흔히 겪을 수 있는 트러블슈팅 상황을 한눈에 볼 수 있습니다. (이미지: 쿠버네티스 트러블슈팅)

검증 및 결과 확인

위에서 배운 명령어들을 활용하여 변경 사항이 잘 적용되었는지, 클러스터의 상태는 정상적인지 확인하는 것이 중요합니다. 주로 사용하는 명령어는 다음과 같아요.

# 모든 네임스페이스의 모든 리소스 확인 (초보자에게 추천!)
kubectl get all --all-namespaces

# 특정 네임스페이스의 주요 리소스 확인 (파드, 서비스, 디플로이먼트, 레플리카셋)
kubectl get deploy,svc,pod,rs -n my-namespace

# 특정 리소스의 자세한 정보 확인 (IP 주소, 노드 정보 등)
kubectl get deploy,svc,pod -o wide -n my-namespace

이 명령어들로 제가 고친 설정이 잘 반영되었는지, 파드들이 정상적으로 돌고 있는지, 외부 IP는 제대로 할당되었는지 확인하곤 합니다. 특히 -o wide 옵션은 더 많은 정보를 보여줘서 매우 편리해요. ✅

오늘 다룬 kubectl 고급 활용 팁들을 한 장으로 요약한 인포그래픽입니다. (이미지: kubectl 팁 요약)

마무리하며: `kubectl` 마스터가 되는 그날까지!

오늘은 13년차 인프라 엔지니어의 경험을 담아 kubectl 고급 활용법에 대해 알아봤습니다. Pod, Service, Deployment를 관리할 때 유용하게 사용할 수 있는 명령어들과 함께, 제가 직접 겪었던 삽질 경험과 트러블슈팅 노하우까지 솔직하게 공유해 드렸네요.

사실 kubectl은 알면 알수록 강력한 도구거든요. 기본적인 명령어만 쓰기엔 아까운 기능들이 너무 많아요. 클러스터의 모든 것을 kubectl 하나로 제어할 수 있다고 해도 과언이 아닙니다. 저도 처음엔 헷갈렸지만, 꾸준히 사용하고 궁금한 점은 직접 찾아보면서 익혔습니다. 여러분도 저처럼 삽질하면서 얻은 팁들을 활용해서 kubectl 마스터가 되시길 바랍니다! 🎉

다음에는 kubectl 플러그인이나 K9s 같은 터미널 UI 도구들에 대해서도 다뤄보면 좋겠네요. 쿠버네티스 운영에 또 다른 재미를 더해줄 도구들이거든요. 긴 글 읽어주셔서 감사합니다. 다음에도 더 유익한 정보로 찾아오겠습니다! 😉