나만의 클러스터 만들기 – Spring Boot 앱을 로컬 이미지로 빌드하고 k3s에 Pull 없이 배포하기

🎯 이번 단계의 목적

 

최종 목표는 Helm 패키징이다.

 

하지만 Helm으로 배포하기 전에 반드시 검증해야 할 것이 있다.

 

내가 만든 애플리케이션 이미지가

클러스터 노드에서 정상적으로 실행되는가?

 

이번 글은 그 기초를 다지는 단계다.

 

---

 

1️⃣ Spring Boot 최소 앱 구성

 

 

기능 요구사항

 

• / → APP_MESSAGE (APP_VERSION) 반환
• /actuator/health → UP

 

 

Controller

@RestController
public class HelloController {

    @Value("${APP_MESSAGE:hello}")
    private String message;

    @Value("${APP_VERSION:dev}")
    private String version;

    @GetMapping("/")
    public String root() {
        return message + " (" + version + ")";
    }
}

 

application.properties

management.endpoints.web.exposure.include=health
management.endpoint.health.show-details=never

 

---

 

2️⃣ Docker 이미지 생성

 

멀티스테이지 빌드로 구성.

# ---- build stage ----
FROM eclipse-temurin:21-jdk AS build
WORKDIR /app

# Gradle wrapper 먼저 복사 (캐시 효율)
COPY gradlew .
COPY gradle gradle
COPY build.gradle settings.gradle ./

# 의존성 캐시
RUN chmod +x gradlew && ./gradlew --no-daemon -q dependencies

# 소스 복사 후 빌드
COPY src src
RUN ./gradlew --no-daemon clean bootJar -x test

# ---- runtime stage ----
FROM eclipse-temurin:21-jre
WORKDIR /app

# 빌드 결과 jar 복사 (bootJar 결과)
COPY --from=build /app/build/libs/*.jar app.jar

EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

이미지 빌드:

docker build -t mycluster:dev .

 

---

 

3️⃣ k3s는 Docker를 보지 않는다

 

여기서 중요한 개념 하나.

 

• Mac의 Docker 이미지
• k3s VM의 containerd 이미지

 

이 둘은 완전히 다른 스토리지다.

 

따라서 반드시 k3s 노드 내부로 이미지를 import해야 한다.

 

---

 

4️⃣ Multipass VM으로 이미지 전달

 

 

1) tar 생성 (Mac)

docker save mycluster:dev -o mycluster_dev.tar

 

2) VM으로 전송

multipass transfer mycluster_dev.tar k3svm:/tmp/mycluster_dev.tar

 

3) VM 내부에서 import

multipass shell k3svm
sudo k3s ctr images import /tmp/mycluster_dev.tar
sudo k3s ctr images list | grep mycluster

여기서 mycluster:dev가 보이면 성공.

 

---

 

5️⃣ Pull 없이 실행 확인

kubectl run imgtest \
  --image=mycluster:dev \
  --restart=Never \
  --image-pull-policy=Never \
  --port=8080

확인:

kubectl get pod imgtest -w

 

체크 포인트

 

• Pulling 이벤트가 없어야 한다
• Pod가 Running 상태여야 한다

 

---

 

🧠 오늘의 핵심 정리

 

1. Docker 이미지와 k3s containerd는 별개다.
2. k3s는 k3s ctr로 containerd에 접근한다.
3. imagePullPolicy=Never는 로컬 이미지 검증에 유용하다.
4. Helm 이전에 “이미지 → 노드 → 실행” 흐름을 이해해야 한다.

 

---

 

🔜 다음 단계

 

이제 Helm으로 가기 전 단계:

 

• Pod → Deployment로 전환
• Service 연결
• 환경변수 values.yaml 구조 설계

 

Helm은 단순히 템플릿 엔진이 아니다.

 

이미 동작하는 Kubernetes 리소스를

재현 가능하게 패키징하는 도구다.

 

Day 1 완료.

이제 클러스터를 내 것으로 만드는 여정이 시작됐다.