쿠버네티스 첫걸음 3편 — kubectl로 파드와 노드 다루기: get·describe·logs·exec, 그리고 파드가 안 뜰 때 읽는 법

들어가며 — kubectl은 문법 하나만 알면 된다

크게 보기

kubectl 치트시트를 검색하면 수백 개의 명령이 나옵니다. 외우려고 하면 끝이 없습니다. 하지만 거의 모든 kubectl 명령은 한 가지 문법으로 되어 있습니다.

동사는 무엇을 할지(get, describe, apply, delete…), 리소스 종류는 무엇에 대해(pod, node, deployment, service…), 이름은 어느 것에(생략하면 전부), 옵션은 어떻게(-n 네임스페이스, -o 출력 형식…)입니다. 이 문법 하나로 이 글의 모든 명령이 읽힙니다.

실습하려면 2편의 로컬 클러스터가 켜져 있어야 합니다. kubectl get nodes에 Ready가 보이면 준비 완료입니다.

1. 시작 전에 — 편하게 만드는 두 가지

① 짧은 이름. 리소스 종류는 줄여 쓸 수 있습니다. pods는 po, services는 svc, deployments는 deploy, namespaces는 ns, nodes는 no입니다. 전체 목록은 이 명령으로 봅니다.

kubectl api-resources

② 자동 완성. Tab 키로 리소스 이름까지 완성되게 합니다. 맥의 기본 셸(zsh)이라면:

echo 'source <(kubectl completion zsh)' >> ~/.zshrc
echo 'alias k=kubectl' >> ~/.zshrc
echo 'compdef __start_kubectl k' >> ~/.zshrc
source ~/.zshrc

이제 k get po처럼 짧게 칠 수 있습니다. WSL2 우분투(bash)라면 completion zsh 대신 completion bash를, compdef 줄 대신 complete -o default -F __start_kubectl k를 ~/.bashrc에 넣습니다. 이 글에서는 알아보기 쉽게 kubectl을 다 적겠습니다.

2. 노드 살펴보기 — 우리 클러스터에는 컴퓨터가 몇 대?

kubectl get nodes -o wide

-o wide는 더 많은 열을 보여 줍니다. 노드의 내부 IP, 운영체제, 커널 버전, 컨테이너 런타임(containerd 등)까지 나옵니다.

노드 하나를 자세히 봅니다. 노드 이름은 get nodes에 나온 것을 씁니다.

kubectl describe node <노드이름>

출력이 길지만 처음에는 세 부분만 보면 됩니다.

3. 첫 파드 — 명령 한 줄로

kubectl run web --image=nginx:1.29 --port=80

도커의 docker run과 비슷해 보이죠. 상태를 봅니다.

kubectl get pods
kubectl get pods -o wide

-o wide를 붙이면 파드의 IP와 어느 노드에서 돌고 있는지(NODE)가 나옵니다. 1편의 그림처럼 파드는 노드 위에서 돌고, 자기 IP를 하나 가집니다.

4. 파드 들여다보기 — describe · logs · exec

도커 3편에서 쓰던 docker logs, docker exec가 쿠버네티스에서도 거의 그대로 있습니다.

kubectl describe pod web

맨 아래의 Events가 가장 중요합니다. 파드가 어느 노드에 배치됐고(Scheduled), 이미지를 받았고(Pulling, Pulled), 컨테이너를 만들고 시작했는지(Created, Started)가 시간순으로 적혀 있습니다. 무언가 잘못되면 여기에 이유가 나옵니다.

로그를 봅니다. -f는 실시간으로 따라갑니다.

kubectl logs web
kubectl logs -f web

파드 안에 들어가 셸을 엽니다. -- 뒤가 컨테이너 안에서 실행할 명령입니다.

kubectl exec -it web -- sh

안에서 cat /etc/nginx/nginx.conf, hostname 등을 쳐 보고 exit로 나옵니다. hostname이 파드 이름(web)과 같다는 것도 확인해 보세요.

5. 내 컴퓨터에서 접속하기 — port-forward

파드의 IP는 클러스터 안의 주소라 내 브라우저에서 바로 열 수 없습니다(도커에서 -p를 안 준 것과 비슷). 개발 중에 잠깐 접속할 때는 port-forward를 씁니다.

kubectl port-forward pod/web 8080:80

순서는 도커와 같습니다 — 내 쪽:파드 쪽. http://localhost:8080을 열면 nginx 페이지가 보입니다. 터미널을 닫거나 Ctrl+C를 누르면 연결이 끊깁니다. port-forward는 개발·디버깅용 임시 통로이고, 제대로 된 공개 방법(Service, Ingress)은 4편에서 다룹니다.

6. 직접 만든 파드는 되살아나지 않는다

1편 시뮬레이터에서 파드를 죽이면 새로 생겼습니다. 여기서도 그럴까요?

kubectl delete pod web
kubectl get pods

아무것도 남지 않습니다. kubectl run으로 만든 파드는 관리해 줄 상위 부품(디플로이먼트)이 없는 "맨 파드"라서, 지우면 그걸로 끝입니다. 노드가 죽어도 마찬가지입니다. 그래서 실제 앱은 절대 맨 파드로 띄우지 않고 디플로이먼트로 띄웁니다(4편). 맨 파드는 지금처럼 실험하거나, 잠깐 디버깅용 셸을 띄울 때만 씁니다.

kubectl run tmp --rm -it --image=busybox:1.37 -- sh

--rm은 도커와 같습니다. 셸에서 나오면 파드가 자동으로 지워집니다. 클러스터 안에서 wget -qO- http://<다른파드IP>로 통신을 확인할 때 유용합니다.

7. 파드를 YAML로 — 쿠버네티스의 진짜 방식

kubectl run은 편하지만 협업에는 맞지 않습니다. 무엇을 띄웠는지 기록이 남지 않기 때문입니다. 쿠버네티스의 기본 방식은 YAML 파일에 원하는 상태를 적고 apply 하는 것입니다. pod.yaml을 만듭니다.

apiVersion: v1
kind: Pod
metadata:
  name: web
  labels:
    app: web
spec:
  containers:
    - name: nginx
      image: nginx:1.29
      ports:
        - containerPort: 80
      resources:
        requests:
          cpu: 100m
          memory: 64Mi
        limits:
          memory: 128Mi

kubectl apply -f pod.yaml
kubectl get pods --show-labels

YAML을 고친 뒤 다시 apply하면 차이만 반영됩니다(단, 파드는 대부분의 필드를 바꿀 수 없어 지우고 다시 만들어야 합니다 — 이것도 디플로이먼트를 쓰는 이유입니다). 지울 때도 파일로 지웁니다.

kubectl delete -f pod.yaml

8. 파드 안에 컨테이너가 여럿? — 사이드카

대부분의 파드는 컨테이너 하나지만, 가끔 둘 이상을 넣습니다.

크게 보기

같은 파드 안의 컨테이너들은 IP 하나(localhost로 서로 통신)와 볼륨을 공유하고, 항상 같은 노드에 함께 배치되고 함께 지워집니다. 그래서 떼려야 뗄 수 없는 관계일 때만 한 파드에 넣습니다. 예를 들면 앱의 로그 파일을 읽어 수집 서버로 보내는 로그 수집기, 앱 앞에서 암호화를 대신 처리하는 프록시 같은 사이드카(sidecar) 컨테이너입니다.

9. 파드가 안 뜰 때 — STATUS 읽는 법

파드 문제의 90%는 kubectl get pods의 STATUS 열과 describe의 Events, logs 세 가지로 풀립니다. 아래 진단기에서 STATUS를 골라 보세요. 실습으로 일부러 문제를 만들어 볼 수도 있습니다.

실습: 일부러 ImagePullBackOff 만들기

kubectl run broken --image=nginx:9.99-notexist
kubectl get pods -w

ErrImagePull → ImagePullBackOff로 바뀌는 것을 보고, Events에서 이유를 찾아봅니다.

kubectl describe pod broken | tail -n 10
kubectl delete pod broken

실습: 일부러 CrashLoopBackOff 만들기 — 시작하자마자 에러로 끝나는 컨테이너입니다.

kubectl run crash --image=busybox:1.37 -- sh -c "echo 설정 파일이 없습니다; exit 1"
kubectl get pods -w

RESTARTS가 늘면서 CrashLoopBackOff가 됩니다. 죽기 직전의 로그를 봅니다.

kubectl logs crash --previous
kubectl delete pod crash

설정 파일이 없습니다가 보입니다. 실제 앱에서도 이 자리에 "DB 연결 실패", "환경변수 누락" 같은 진짜 이유가 찍힙니다.

10. kubectl 치트시트 — 이 표만 있으면 된다

마치며

다음 편에서는 드디어 내 앱을 쿠버네티스에 올립니다. 도커 시리즈에서 만든 hello-api 이미지를 디플로이먼트로 배포하고, 서비스로 고정 주소를 주고, 개수를 늘리고, 새 버전으로 무중단 교체하고, 잘못되면 되돌리는 것까지 합니다.

👉 4편: 디플로이먼트와 서비스로 내 앱 배포하기

참고 자료

• Kubernetes 문서, kubectl Quick Reference
• Kubernetes 문서, Pod Lifecycle · Debug Pods
• Kubernetes 문서, Resource Management for Pods and Containers
• Kubernetes 문서, Sidecar Containers
• Kubernetes 문서, Nodes