FROM THE FIELDKubernetes / k3d

개요

Mac 로컬 환경에서 k3d를 이용해 Kubernetes 클러스터를 만들고, Spring Boot 애플리케이션과 PostgreSQL을 배포해 외부에서 접근 가능하도록 구성


전체 아키텍처

전체 아키텍처

[브라우저 192.168.0.31:30001]
        ↓ 요청
[Mac Host - Docker (k3d)]
        ↓ 포트 매핑 (30001:30001@loadbalancer)
[k3d LoadBalancer]
        ↓
[kube-proxy]
        ↓
[spring-hello-svc NodePort:30001]
        ↓ 로드밸런싱
[spring-hello Pod 1/2/3 :8080]
        ↓ DB 쿼리
[postgres-svc ClusterIP:5432]
        ↓
[postgres Pod :5432]

1. k3d 클러스터 생성

k3d는 노드가 Docker 컨테이너 안에서 실행된다. 일반 AWS EC2 환경과 달리 노드 IP(172.21.0.x)가 Docker 내부 가상 네트워크에 갇혀있어 Mac 밖에서 접근이 불가능하다.

그래서 클러스터 생성 시 반드시 --port 옵션으로 포트 매핑을 해줘야 한다.

k3d cluster create my-cluster \
  --port "30001:30001@loadbalancer" \
  -a 2
  • --port "30001:30001@loadbalancer": Mac 호스트 30001 → k3d LoadBalancer 30001 포트 매핑
  • -a 2: Worker Node 2개 생성 (agent = Worker Node)
# 생성 확인
k3d cluster list
kubectl get nodes
docker ps  # 0.0.0.0:30001->30001/tcp 확인

2. Docker 이미지 빌드 & 푸시

Kubernetes는 Pod를 생성할 때 Docker Hub에서 이미지를 가져다 쓴다. 그래서 배포 전에 이미지를 빌드하고 Docker Hub에 푸시해야 한다.

cd ~/dev/k8s-assignment/spring-app

docker build -t jaehyuksssss/spring-hello-world:1.1 .
docker push jaehyuksssss/spring-hello-world:1.1

deployment.yaml에서 이 이미지를 참조한다:

image: jaehyuksssss/spring-hello-world:1.1

3. Kubernetes에 배포

Kubernetes 내부 배포 흐름

kubectl apply 명령어를 실행하면 아래 흐름으로 Pod가 생성된다:

kubectl apply
→ API Server (요청 수신)
→ etcd (원하는 상태 저장)
→ Controller Manager (Pod 필요 감지)
→ Scheduler (Worker Node 배치 결정)
→ Kubelet (Pod 실행)
→ Pod 생성 완료

배포 명령어

PostgreSQL을 먼저 배포하는 이유는 Spring Boot 앱이 시작할 때 DB 연결을 시도하기 때문이다.

kubectl apply -f ~/dev/k8s-assignment/session2/k8s/postgres.yaml
kubectl apply -f ~/dev/k8s-assignment/session2/k8s/deployment.yaml

# 확인
kubectl get pods
kubectl get deployment
kubectl get rs   # ReplicaSet 확인

4. Service 구성

NodePort (외부 접근용)

spring-hello-svc는 NodePort 타입으로 외부에서 30001 포트로 접근 가능하다.

spec:
  type: NodePort
  selector:
    app: spring-hello
  ports:
    - port: 80
      targetPort: 8080
      nodePort: 30001

ClusterIP (내부 통신 전용)

postgres-svc는 ClusterIP 타입으로 클러스터 내부에서만 접근 가능하다. DB를 외부에 노출하지 않는 안전한 구조다.

Spring Boot 앱은 Pod IP가 아닌 Service 이름으로 DB에 접근한다:

env:
  - name: DB_HOST
    value: postgres-svc # Service 이름으로 접근

이렇게 하면 PostgreSQL Pod가 재시작되어 IP가 바뀌어도 안정적으로 DB에 접근할 수 있다.

# 서비스 확인
kubectl get svc
# spring-hello-svc → NodePort  80:30001/TCP
# postgres-svc     → ClusterIP 5432/TCP

5. 동작 확인

# 브라우저에서 접속
# http://192.168.0.31:30001        → Spring Boot 메인
# http://192.168.0.31:30001/items  → DB 연동 확인

6. 수평 스케일 아웃 (Horizontal Scale Out)

Pod를 1개에서 3개로 늘려 로드밸런싱 구조를 만든다. spring-hello-svc가 3개의 Pod로 트래픽을 분산한다.

kubectl scale deployment spring-hello --replicas=3
kubectl get pods
spring-hello-svc
→ spring-hello Pod 1 :8080
→ spring-hello Pod 2 :8080
→ spring-hello Pod 3 :8080
(트래픽 분산)

Kubernetes 주요 컴포넌트 정리

Master Node (Control Plane)

컴포넌트역할
API Server모든 요청의 관문. kubectl 명령어가 여기로 전달됨
etcd클러스터 상태 저장소
Controller Manager원하는 상태 유지 (Pod 수 감시 및 복구)
Scheduler새 Pod를 어느 Worker Node에 배치할지 결정

Worker Node

컴포넌트역할
KubeletPod가 정상 실행되도록 관리
Kube-proxyService로 들어온 트래픽을 Pod로 전달
Container Runtime실제 컨테이너를 실행하는 엔진 (containerd)

핵심 정리

  • k3d는 노드가 Docker 컨테이너 안에 있어서 클러스터 생성 시 포트 매핑 필수
  • NodePort: 외부 접근용 / ClusterIP: 내부 통신 전용
  • Service를 사용하는 이유: Pod IP는 재시작 시 바뀌기 때문에 고정 엔드포인트 필요
  • Deployment로 배포하면 Pod가 죽어도 자동으로 재생성됨
읽어주셔서 감사합니다.

틀린 내용이나 궁금한 점은 댓글로 남겨주세요.

Comments.

댓글 불러오는 중…