쿠버네티스(Kubernetes) 주요 명령어 모음

작성자:

쿠버네티스 CLI는 대부분 kubectl 한 가지로 시작합니다. 실무에서 “확인 → 원인 파악 → 수정/배포 → 검증” 흐름을 가장 많이 타기 때문에, 아래 목차도 그 흐름에 맞춰 구성했습니다. 예시는 그대로 복사해서 써도 되도록 작성했습니다.

목차

  1. kubectl 기본 개념과 사용 습관
  2. 컨텍스트/네임스페이스 관리(실수 방지)
  3. 리소스 조회(get)와 출력 포맷 옵션
  4. 상세 확인(describe)과 이벤트(event) 보기
  5. 로그(logs)와 디버깅(실무에서 제일 많이 씀)
  6. 컨테이너 접속(exec)과 포트포워딩(port-forward)
  7. 리소스 생성/적용(apply)과 삭제(delete)
  8. Deployment/ReplicaSet/Pod 운영 핵심 명령어
  9. Service/Ingress 조회와 트래픽 관점 확인
  10. ConfigMap/Secret 다루기(기본 패턴)
  11. 노드/클러스터 상태 확인(top, nodes)
  12. 롤아웃/롤백(배포 안전장치)
  13. 라벨/셀렉터/어노테이션(운영의 기본 문법)
  14. 자주 쓰는 “실무 상황별” 커맨드 레시피
  15. 초보자가 자주 하는 실수 체크리스트

1) kubectl 기본 개념과 사용 습관

쿠버네티스 리소스는 “객체”다

쿠버네티스에서 다루는 대상은 Pod, Deployment, Service 같은 “리소스(객체)”입니다. kubectl은 이 객체들을 조회하고(get), 설명하고(describe), 수정/적용하고(apply), 삭제(delete) 하는 도구입니다.

커맨드 기본 구조

kubectl <동작> <리소스종류> <이름> -n <namespace> <옵션>
  • 동작: get, describe, logs, apply, delete, exec 등
  • 리소스종류: pods, deploy, svc, ing, cm, secret 등(축약 가능)
  • 네임스페이스: -n 또는 –namespace
  • 출력: -o wide, -o yaml, -o json

2) 컨텍스트/네임스페이스 관리 (실수 방지)

실무에서 가장 흔한 사고는 “다른 클러스터에 명령 실행” 또는 “default 네임스페이스에 실행”입니다.

현재 컨텍스트/클러스터 확인

kubectl config current-context
kubectl config get-contexts

컨텍스트 변경

kubectl config use-context <context-name>

기본 네임스페이스 지정(해당 컨텍스트에서)

kubectl config set-context --current --namespace=<ns>

명령어에 네임스페이스 붙이는 습관

kubectl get pod -n dev
kubectl get deploy -n prod

팁: “운영(production)” 작업 전엔 current-context부터 확인하는 습관이 사고를 줄입니다.

3) 리소스 조회(get)와 출력 포맷 옵션

가장 기본: 목록 보기

kubectl get pods -n dev
kubectl get deploy -n dev
kubectl get svc -n dev

이름 대신 축약

  • pod/po
  • deploy
  • svc
  • ing
  • cm (ConfigMap)

예:

kubectl get po -n dev
kubectl get deploy -n dev

더 많은 정보: wide

kubectl get po -n dev -o wide

Pod가 어떤 노드에 뜨는지, IP가 뭔지 등 실무에서 유용합니다.

YAML/JSON 출력(설정 확인/복사에 필수)

kubectl get deploy myapp -n dev -o yaml
kubectl get svc myapp -n dev -o yaml

특정 컬럼만 뽑기 (자주 쓰는 커스텀 컬럼)

kubectl get po -n dev \
  -o custom-columns=NAME:.metadata.name,STATUS:.status.phase,NODE:.spec.nodeName

라벨 셀렉터로 필터링

kubectl get po -n dev -l app=myapp
kubectl get po -n dev -l 'app in (myapp, yourapp)'

4) 상세 확인(describe)과 이벤트(event) 보기

get이 “목록/요약”이라면 describe는 “진단서”입니다.

Pod 상세(문제 원인 찾기)

kubectl describe pod <pod-name> -n dev

여기서 특히 많이 보는 구간:

  • Events: 이미지 풀 실패, readiness probe 실패, CrashLoopBackOff 원인 등
  • 컨테이너 상태/재시작 횟수
  • 볼륨 마운트, 환경변수 등

이벤트만 따로 보기

kubectl get events -n dev
kubectl get events -n dev --sort-by=.lastTimestamp

5) 로그(logs)와 디버깅 (실무에서 제일 많이 씀)

기본 로그 보기

kubectl logs <pod-name> -n dev

실시간 팔로우

kubectl logs -f <pod-name> -n dev

컨테이너가 여러 개인 Pod

kubectl logs <pod-name> -n dev -c <container-name>

이전 로그(재시작된 컨테이너)

CrashLoopBackOff 같은 상황에서 매우 유용:

kubectl logs <pod-name> -n dev -p

Deployment 기준으로 Pod 찾아 로그 보기(패턴)

  1. 먼저 pod 찾기:
kubectl get po -n dev -l app=myapp
  1. 해당 pod 로그:
kubectl logs -f <pod-name> -n dev

6) 컨테이너 접속(exec)과 포트포워딩(port-forward)

컨테이너 내부 쉘 진입

kubectl exec -it <pod-name> -n dev -- /bin/sh
# 또는 bash가 있으면
kubectl exec -it <pod-name> -n dev -- /bin/bash

컨테이너에 툴이 부족할 수 있습니다(특히 distroless 이미지). 그럴 땐 아래 “디버그용 임시 Pod” 패턴을 씁니다.

임시 디버그 Pod 실행(네트워크 확인)

kubectl run tmp-shell -n dev --rm -it --image=busybox -- sh

이 안에서 nslookup, wget, curl 같은 걸로 서비스 접근 확인을 합니다(이미지에 따라 도구가 다름).

포트 포워딩(로컬에서 Pod/Service 접근)

kubectl port-forward pod/<pod-name> -n dev 8080:80
kubectl port-forward svc/<svc-name> -n dev 8080:80
  • 로컬 8080 → 클러스터의 80으로 터널링
  • 내부망/권한 때문에 직접 접속이 어려울 때 디버깅에 좋습니다.

7) 리소스 생성/적용(apply)과 삭제(delete)

apply: 선언형 배포의 기본

kubectl apply -f deployment.yaml -n dev
kubectl apply -f k8s/ -n dev

diff로 변경점 확인 후 적용(실무 안전장치)

kubectl diff -f k8s/ -n dev
kubectl apply -f k8s/ -n dev

delete: 삭제

kubectl delete -f deployment.yaml -n dev
kubectl delete pod <pod-name> -n dev

팁: Pod를 직접 지우면(예: delete pod) 보통 Deployment가 다시 만들어줍니다. 즉 “재시작” 용도로도 종종 사용됩니다.

8) Deployment/ReplicaSet/Pod 운영 핵심 명령어

Deployment 목록/상세

kubectl get deploy -n dev
kubectl describe deploy myapp -n dev

ReplicaSet 확인(원하는 수 vs 실제 수)

kubectl get rs -n dev

Pod가 왜 계속 재생성되는지 확인할 때

  • deploy → rs → pod 흐름으로 원인 추적
kubectl get deploy -n dev
kubectl get rs -n dev
kubectl get po -n dev

스케일 조정

kubectl scale deploy myapp -n dev --replicas=3

9) Service/Ingress 조회와 트래픽 관점 확인

Service 확인

kubectl get svc -n dev
kubectl describe svc myapp -n dev

Service에서 자주 보는 것:

  • selector가 맞는지 (Pod 라벨과 일치해야 트래픽이 감)
  • ports 설정

Endpoints 확인(트래픽이 실제로 어디로 가는지)

서비스가 Pod를 제대로 물고 있는지 확인:

kubectl get endpoints -n dev
kubectl get endpoints myapp -n dev -o yaml

Ingress 확인

kubectl get ing -n dev
kubectl describe ing myapp -n dev

10) ConfigMap/Secret 다루기 (기본 패턴)

ConfigMap 목록/확인

kubectl get cm -n dev
kubectl get cm my-config -n dev -o yaml

파일로부터 ConfigMap 생성(예시)

kubectl create configmap my-config -n dev --from-file=app.conf

Secret 확인(주의: 기본 출력은 base64)

kubectl get secret -n dev
kubectl get secret my-secret -n dev -o yaml

주의: Secret의 실제 값은 base64 인코딩일 뿐 암호화가 아닐 수 있습니다(클러스터 설정에 따라 다름). 출력/공유 시 주의하세요.

11) 노드/클러스터 상태 확인(top, nodes)

노드 목록

kubectl get nodes
kubectl describe node <node-name>

리소스 사용량(top)

(클러스터에 metrics-server 등이 있어야 동작)

kubectl top nodes
kubectl top pods -n dev

12) 롤아웃/롤백 (배포 안전장치)

배포 상태 확인

kubectl rollout status deploy/myapp -n dev

롤아웃 히스토리

kubectl rollout history deploy/myapp -n dev

롤백

kubectl rollout undo deploy/myapp -n dev
# 특정 리비전으로
kubectl rollout undo deploy/myapp -n dev --to-revision=3

실무에서는 “배포 후 장애 → 바로 롤백”이 가장 빠른 복구 루트인 경우가 많습니다.

13) 라벨/셀렉터/어노테이션 (운영의 기본 문법)

라벨 확인

kubectl get po -n dev --show-labels

라벨로 검색

kubectl get po -n dev -l app=myapp

라벨 추가/수정

kubectl label pod <pod-name> -n dev tier=backend
# 덮어쓰기
kubectl label pod <pod-name> -n dev tier=backend --overwrite

어노테이션 추가

kubectl annotate deploy myapp -n dev owner="team-a"

14) 실무 상황별 커맨드 레시피

(1) Pod가 CrashLoopBackOff일 때

  1. Pod 상태 확인
kubectl get po -n dev
  1. 이벤트/원인 확인
kubectl describe pod <pod-name> -n dev
  1. 이전 로그 확인(핵심)
kubectl logs <pod-name> -n dev -p

(2) 서비스 접속이 안 될 때(트래픽 경로 점검)

  1. Service selector 확인
kubectl describe svc myapp -n dev
  1. Endpoints 존재 여부 확인
kubectl get endpoints myapp -n dev
  1. Pod 라벨이 Service selector와 일치하는지 확인
kubectl get po -n dev --show-labels

(3) “재배포 없이” 이미지 태그만 바꾸고 싶을 때

kubectl set image deploy/myapp -n dev myapp-container=myrepo/myapp:1.2.3
kubectl rollout status deploy/myapp -n dev

(4) 설정 일부만 빠르게 수정하고 싶을 때(주의해서 사용)

kubectl edit deploy myapp -n dev

에디터가 열리고 저장하면 바로 반영됩니다.

실무에선 “핫픽스”로 유용하지만, YAML 소스(GitOps)와 불일치가 생기기 쉬워서 추적/정리가 필요합니다.

(5) YAML을 “현재 상태 기준”으로 뽑아서 비교하고 싶을 때

kubectl get deploy myapp -n dev -o yaml > live.yaml

15) 초보자가 자주 하는 실수 체크리스트

  • -n <namespace> 안 붙이고 실행해서 다른 곳을 만짐
  • current-context 확인 안 하고 운영 클러스터에 적용
  • 서비스 장애인데 Pod만 보고 끝냄(Endpoints/selector 확인 누락)
  • CrashLoop인데 logs -p를 안 봄(이전 로그가 핵심인 경우가 많음)
  • 여러 컨테이너 Pod에서 -c 옵션 빼서 엉뚱한 로그를 봄
  • kubectl edit로 급하게 고치고 Git/YAML 원본 반영을 잊음

자주 쓰는 리소스 축약(암기용)

  • Pod: po
  • Deployment: deploy
  • Service: svc
  • Ingress: ing
  • ConfigMap: cm
  • Namespace: ns
  • ReplicaSet: rs

댓글 남기기