Kubernetes (1) - kubectl 기본 명령어로 Pod와 Deployment 다루기

게시 2026/08/23

By eta_kyung

11 분읽는 시간

Kubernetes 클러스터와 상호작용할 때 사용하는 기본 CLI가 kubectl이다. 리소스의 상태를 조회하는 것부터 Pod와 Deployment 생성, 컨테이너 로그 확인, 내부 애플리케이션 접속까지 대부분의 작업을 kubectl 명령으로 수행한다.

이번 글에서는 kind로 구성한 로컬 클러스터에서 Nginx Pod와 Apache Deployment를 실행한 기록을 바탕으로, 처음 알아두면 좋은 kubectl 명령어를 작업 흐름에 맞춰 정리한다.

1. kubectl 도움말과 리소스 종류 확인

처음에는 현재 클러스터에서 다룰 수 있는 리소스와 명령어를 확인하는 것부터 시작하면 좋다.

  
# kubectl의 전체 명령 목록 확인
kubectl --help

# 현재 API 서버가 지원하는 리소스 종류와 축약형 확인
kubectl api-resources

# 특정 리소스의 필드 설명 확인
kubectl explain pods

kubectl api-resources는 pods, deployments, services처럼 API 서버가 지원하는 리소스와 축약형을 보여준다. 예를 들어 Pod는 po, Deployment는 deploy, Service는 svc로 줄여 쓸 수 있다.

kubectl get 뒤에는 반드시 조회할 리소스 종류가 필요하다. 따라서 kubectl get만 실행하면 오류가 나며, kubectl get pods나 kubectl get nodes처럼 대상을 지정해야 한다.

명령	확인 대상
`kubectl get nodes`	클러스터를 구성하는 노드
`kubectl get pods`	현재 네임스페이스의 Pod
`kubectl get deployments`	Deployment 상태와 레플리카 수
`kubectl get services`	네트워크 접근을 위한 Service

2. 노드와 Pod 상태 조회하기

get은 리소스 목록과 상태를 빠르게 확인할 때 가장 자주 사용한다.

  
# 노드의 이름, 상태, 역할 확인
kubectl get nodes

# IP, 컨테이너 런타임 등 상세 열까지 표시
kubectl get nodes -o wide

# Pod 목록과 실행 상태 확인
kubectl get pods

# Pod IP와 배치된 노드까지 표시
kubectl get pods -o wide

-o wide 옵션을 붙이면 Pod가 어느 노드에 배치되었는지와 Pod IP를 확인할 수 있다. 실습에서는 Nginx Pod에 할당된 Pod IP로 curl을 실행해 HTTP 응답을 확인할 수 있었다.

kubectl get pods -o wide
curl <POD_IP>

Pod IP는 클러스터 내부에서의 테스트에는 쓸 수 있지만, Pod가 다시 생성되면 바뀔 수 있다. 애플리케이션을 안정적으로 노출하려면 이후에 Service를 사용하는 것이 일반적이다.

3. 상세 정보와 YAML·JSON으로 살펴보기

문제가 생겼거나 설정을 자세히 확인해야 할 때는 describe와 출력 형식 옵션을 사용한다.

  
# 노드의 조건, 할당량, 이벤트 확인
kubectl describe node cka-control-plane

# Deployment의 레플리카, 이미지, 이벤트 확인
kubectl describe deployment mainui

# Pod의 현재 정의를 YAML 또는 JSON으로 출력
kubectl get pod webserver -o yaml
kubectl get pod webserver -o json

describe는 사람이 읽기 쉬운 형태로 상태, 이벤트, 관련 리소스를 요약한다. 예를 들어 Pod가 Pending이나 ContainerCreating 상태에 오래 머문다면 Events 영역에서 이미지 다운로드, 스케줄링, 볼륨 마운트 문제를 먼저 확인할 수 있다.

-o yaml과 -o json은 API 서버에 저장된 리소스 정의 전체를 보여준다. metadata, spec, status 구조를 직접 확인할 수 있어 설정을 파일로 옮기거나 API 객체를 이해할 때 유용하다.

4. Pod와 Deployment 생성하기

가장 간단한 실습은 이미지를 하나 지정해 Pod를 실행하는 것이다.

  
kubectl run webserver --image=nginx:1.14 --port=80
kubectl get pods

kubectl run은 위와 같이 단일 Pod를 빠르게 만들 때 편리하다. 다만 Pod를 직접 만들면 Pod가 삭제되었을 때 원하는 개수를 유지해줄 컨트롤러가 없다.

여러 개의 Pod를 유지하는 웹 애플리케이션에는 Deployment를 사용한다.

  
kubectl create deployment mainui --image=httpd --replicas=3

kubectl get deployments
kubectl get pods -o wide

Deployment는 원하는 레플리카 수를 선언하고, 그 수만큼 Pod가 실행되도록 관리한다. 위 명령을 실행하면 mainui Deployment와 이를 관리하는 ReplicaSet, 그리고 Apache 컨테이너를 담은 세 개의 Pod가 생성된다.

리소스	역할
Pod	하나 이상의 컨테이너를 실행하는 최소 배포 단위
ReplicaSet	지정한 수의 Pod가 존재하도록 유지
Deployment	ReplicaSet을 관리하고 배포·업데이트를 제어

5. 실행 중인 컨테이너 확인과 접속

Pod가 실행된 뒤에는 로그를 읽고, 필요하면 컨테이너 안에서 명령을 실행할 수 있다.

  
# Pod의 기본 컨테이너 로그 확인
kubectl logs webserver

# 로그를 계속 출력
kubectl logs -f webserver

# 실행 중인 컨테이너에서 셸 실행
kubectl exec -it webserver -- /bin/bash

하나의 Pod에 컨테이너가 여러 개라면 -c <컨테이너이름>으로 대상을 지정한다. 이전에 종료된 컨테이너 인스턴스의 로그는 kubectl logs -p <POD>로 확인할 수 있다.

kubectl logs webserver -c nginx
kubectl logs -p webserver

kubectl exec로 컨테이너 안의 파일을 수정할 수는 있지만, 이는 임시 확인 용도로만 사용해야 한다. Pod가 재시작되거나 교체되면 컨테이너 파일 시스템의 변경은 사라질 수 있으므로, 실제 설정 변경은 이미지나 Kubernetes 매니페스트로 관리하는 편이 안전하다.

6. 로컬에서 Pod 포트로 연결하기

클러스터 내부의 Pod에 잠시 접속해보고 싶을 때는 port-forward를 사용할 수 있다.

# 로컬 8080 포트를 Pod의 80 포트로 전달
kubectl port-forward pod/webserver 8080:80

명령이 실행 중인 터미널을 유지한 채 다른 터미널에서 다음처럼 접속한다.

curl http://localhost:8080

port-forward는 개발과 디버깅에 적합한 임시 연결이다. 터미널을 종료하면 포워딩도 함께 끝나며, 외부 사용자에게 서비스를 지속적으로 공개하는 방법은 아니다.

7. YAML 파일 만들기와 리소스 정리

명령어로 만든 Pod는 --dry-run=client -o yaml로 YAML 초안을 생성할 수 있다. --dry-run만 사용하는 형식은 더 이상 권장되지 않으므로 --dry-run=client를 명시한다.

  
kubectl run webserver \
  --image=nginx:1.14 \
  --port=80 \
  --dry-run=client \
  -o yaml > webserver-pod.yaml

생성된 파일을 검토하고 필요한 라벨, 환경 변수, 리소스 요청·제한 등을 추가한 뒤 리소스를 생성한다.

kubectl create -f webserver-pod.yaml

이미 존재하는 리소스의 선언을 반복 적용하고 변경 사항을 반영하는 작업에는 보통 다음 명령을 사용한다.

kubectl apply -f webserver-pod.yaml

실습을 마쳤다면 만든 리소스를 명시적으로 삭제한다.

kubectl delete pod webserver
kubectl delete deployment mainui

Deployment를 삭제하면 Deployment가 관리하던 ReplicaSet과 Pod도 함께 삭제된다. 삭제 전에 kubectl get pods와 kubectl get deployments로 대상을 다시 확인하는 습관이 중요하다.

8. 정리

kubectl은 Kubernetes 리소스를 조회하고 생성·수정·삭제하는 기본 도구다. get과 describe로 상태와 이벤트를 확인하고, logs, exec, port-forward로 실행 중인 애플리케이션을 진단할 수 있다.

간단한 실습은 kubectl run으로 Pod를 바로 생성할 수 있지만, 여러 Pod를 안정적으로 유지해야 하는 애플리케이션은 Deployment로 관리하는 것이 적합하다. 명령어로 빠르게 검증한 뒤에는 --dry-run=client -o yaml로 초안을 만들고, YAML 파일을 버전 관리하며 apply하는 흐름으로 발전시키면 재현 가능한 Kubernetes 환경을 만들 수 있다.

Kubernetes