[DevOps] kubectl 기초 — 쿠버네티스를 실제로 조작하는 명령어

지난 글에서 Pod, Deployment, Service가 뭔지 개념을 잡고 YAML도 눈으로 봤다. 그런데 그 YAML을 어떻게 클러스터에 집어넣고, 잘 돌아가는지 어떻게 확인할까? 그걸 하는 도구가 kubectl(큐브컨트롤 / 큐브씨티엘)이다.

kubectl은 쿠버네티스 클러스터에 명령을 내리는 CLI 도구다. 클러스터랑 대화하는 리모컨이라고 보면 된다. 오늘은 실무에서 매일 쓰는 핵심 명령어만 추려서 익힌다.

---

연습 환경은 어떻게?

진짜 클러스터가 없어도 로컬에서 연습할 수 있다. 대표적으로,

• minikube: 내 컴퓨터에 1노드짜리 미니 클러스터를 띄운다. 입문용으로 가장 무난.
• kind: Docker 컨테이너로 클러스터를 만든다. 가볍다.
• Docker Desktop: 설정에서 쿠버네티스를 켜면 바로 쓸 수 있다. 이미 Docker Desktop 쓰면 제일 간단.

셋 중 아무거나 하나 켜두면 kubectl로 조작할 수 있다. 이 글의 명령어는 어느 환경에서든 똑같이 동작한다.

---

kubectl 명령어의 기본 형태

kubectl 명령어는 대부분 이 패턴을 따른다.

kubectl [동사] [리소스종류] [이름] [옵션]

• 동사: get(조회), apply(적용), delete(삭제), describe(상세보기) 등
• 리소스종류: pod, deployment, service 등
• 이름: 특정 대상 하나를 지정할 때

예를 들어 kubectl get pods는 "get(조회) + pods(파드들)" = "파드 목록 보여줘"다. 이 패턴만 알면 대부분의 명령어가 술술 읽힌다.

---

1. 조회하기 — get

가장 많이 쓰는 명령어다. 지금 뭐가 떠 있는지 본다.

kubectl get pods          # 파드 목록
kubectl get deployments   # 디플로이먼트 목록
kubectl get services      # 서비스 목록
kubectl get all           # 주요 리소스 한 번에

get pods를 치면 이런 결과가 나온다.

NAME                      READY   STATUS    RESTARTS   AGE
my-app-6d4b7f8c9-abcde    1/1     Running   0          2m
my-app-6d4b7f8c9-fghij    1/1     Running   0          2m
my-app-6d4b7f8c9-klmno    1/1     Running   0          2m

replicas: 3으로 선언했으니 파드가 3개 떠 있는 게 보인다. 각 열의 의미는,

• READY: 준비된 컨테이너 수 (1/1이면 정상)
• STATUS: 상태 (Running이면 잘 돌아가는 중)
• RESTARTS: 재시작 횟수 (자꾸 늘면 뭔가 문제)
• AGE: 생성된 지 얼마나 됐는지

-o wide를 붙이면 어느 노드에 떴는지, IP는 뭔지 같은 정보까지 더 보여준다.

kubectl get pods -o wide

---

2. 적용하기 — apply

지난 글에서 본 YAML 파일을 클러스터에 실제로 반영하는 명령이다.

kubectl apply -f deployment.yaml
kubectl apply -f service.yaml

# 폴더 안 YAML 전부 적용
kubectl apply -f ./k8s/

apply의 철학이 중요하다. 이건 "새로 만들어라"가 아니라 "이 파일에 적힌 상태가 되게 해라"다. 지난 글에서 말한 선언형이 여기서 실제로 동작한다.

• 없던 거면 → 만든다
• 이미 있는데 내용이 바뀌었으면 → 그 차이만큼 업데이트한다
• 이미 있고 똑같으면 → 아무것도 안 한다

그래서 YAML을 수정하고 다시 apply하면, 쿠버네티스가 알아서 현재 상태와 비교해서 필요한 부분만 바꿔준다. 예를 들어 replicas를 3에서 5로 바꾸고 다시 apply하면, 파드 2개가 더 생긴다.

---

3. 상세 보기 — describe

get이 요약이라면, describe는 특정 대상의 자세한 정보와 이벤트 기록을 보여준다. 뭔가 문제가 생겼을 때 원인 찾는 데 필수다.

kubectl describe pod my-app-6d4b7f8c9-abcde

여기서 특히 아래쪽 Events 섹션이 중요하다. 파드가 왜 안 뜨는지, 이미지를 못 받아왔는지, 스케줄링에 실패했는지 같은 사건들이 시간순으로 찍혀 있다. "파드가 Pending에서 안 넘어가요" 할 때 여기부터 보면 된다.

---

4. 로그 보기 — logs

컨테이너가 뱉는 로그를 본다. 앱이 이상하게 동작할 때 첫 번째로 확인하는 곳이다.

kubectl logs my-app-6d4b7f8c9-abcde

# 실시간으로 계속 보기 (-f = follow)
kubectl logs -f my-app-6d4b7f8c9-abcde

docker logs랑 똑같은 개념이다. -f를 붙이면 로그가 실시간으로 흐르는 걸 볼 수 있다.

---

5. 컨테이너 안으로 들어가기 — exec

파드 안 컨테이너에 직접 들어가서 명령을 실행하거나 셸을 띄운다. 디버깅할 때 요긴하다.

# 파드 안에서 명령 하나 실행
kubectl exec my-app-6d4b7f8c9-abcde -- ls /app

# 파드 안에 셸로 들어가기
kubectl exec -it my-app-6d4b7f8c9-abcde -- /bin/sh

-it는 "터미널을 상호작용 모드로 붙여라"는 뜻이다. docker exec -it이랑 같은 감각이다.

---

6. 삭제하기 — delete

kubectl delete pod my-app-6d4b7f8c9-abcde   # 특정 파드 삭제
kubectl delete -f deployment.yaml           # 이 파일로 만든 것 삭제

여기서 재밌는 걸 하나 실험해보자. Deployment로 관리되는 파드를 하나 delete하면 어떻게 될까?

kubectl delete pod my-app-6d4b7f8c9-abcde
kubectl get pods

지웠는데도 다시 조회하면 파드가 여전히 3개다. Deployment가 "3개를 유지하라"는 선언을 지키려고 지워진 자리에 새 파드를 바로 띄운 것이다. 지난 글에서 말한 자동 복구를 눈으로 확인하는 순간이다. 그래서 파드를 진짜 없애려면 파드가 아니라 그걸 관리하는 Deployment를 지워야 한다.

---

자주 쓰는 명령어 모음

명령어	하는 일
kubectl get pods	파드 목록 조회
kubectl apply -f 파일	YAML 적용(생성/수정)
kubectl describe pod 이름	상세 정보 + 이벤트
kubectl logs -f 이름	로그 실시간 보기
kubectl exec -it 이름 -- /bin/sh	컨테이너 안으로 진입
kubectl delete -f 파일	리소스 삭제
kubectl get all	주요 리소스 한눈에

---

정리

• kubectl은 쿠버네티스 클러스터를 조작하는 리모컨이다.
• 명령어는 kubectl [동사] [리소스] [이름] 패턴을 따른다.
• get(조회), apply(적용), describe(상세), logs(로그), exec(진입), delete(삭제) 이 6개가 매일 쓰는 핵심이다.
• apply는 선언형이다. "이 상태가 되게 하라"는 뜻이라, 수정 후 다시 apply하면 차이만큼만 반영된다.
• Deployment가 관리하는 파드는 지워도 다시 살아난다. 자동 복구를 직접 눈으로 확인할 수 있다.

이 6개 명령어면 쿠버네티스를 조회하고 배포하고 디버깅하는 일상 작업은 거의 다 된다. 처음엔 파드 이름이 길어서 낯설지만, 며칠 쓰면 손에 익는다.

다음 글에서는 이걸 활용해서, 실제로 앱을 배포하고 replicas를 늘려 스케일링하고 이미지를 바꿔 롤링 업데이트하는 걸 직접 해본다. 지금까지 배운 개념들이 실제 동작으로 이어지는 걸 보게 될 거다.