[K3s + Docker] K3s 기반 서버 배포 (1)

이번 포스트에서는 K3s 클러스터 위에 앱 서버를 배포하는 첫 번째 과정을 작성해 보겠다.

사실 K3s로 서버를 배포하는 게 과제였는데.. 처음이라 K3s에 대해 공부하고 배포 과정을 거쳤다.

나 같은 초보들을 위해 K3s에 대해 짤막하게 소개해보겠다.!!

K3s란?

K3s는 Rancher Labs(현 SUSE)가 만든 경량화된 쿠버네티스 배포판이다. K3s도 K8s(Kubernetes)보다 절반 정도 가볍다는 의미에서 붙여진 이름이다.

IoT, 에지 컴퓨팅, 개발/테스트 환경, 소규모 서버처럼 리소스가 제한된 환경에서 쿠버네티스를 쉽고 가볍게 돌리기 위해 설계되었다. 단일 바이너리(<100MB)로 배포되며, 설치도 한 줄 명령어로 완료할 수 있다.

 

항목	K8s	K3s
목적	대규모 프로덕션	경량/소규모 환경
설치 난이도	복잡	한 줄 명령어
최소 메모리	~2GB	~512MB
기본 DB	etcd	SQLite
Ingress/LB	별도 설치	내장 (Traefik/ServiceLB)
K8s API 호환	표준	완전 호환

 

우선 필자는 AWS EC2 인스턴스 2대와 Amazon RDS PostgreSQL를 준비했고, K3s(경량 Kubernetes) 클러스터 위에 NestJS 백엔드 서비스, Prisma ORM 마이그레이션, Redis 캐시 서버를 배포하였다.

 

인프라 아키텍처 구성

Docker 이미지 빌드

NestJS는를 사용하여 이미지를 생성한다. 빌드 단계와 실행 단계를 분리하여 최종 이미지 크기를 최소화하자.

 

<Dockerfile>

# 1단계 - 빌드
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
COPY prisma ./prisma

RUN npm ci
RUN npx prisma generate

COPY . .

RUN npm run build

# 2단계 - 실행
FROM node:20-alpine AS runner

WORKDIR /app

COPY --from=builder /app/package*.json ./
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/prisma ./prisma
COPY --from=builder /app/node_modules ./node_modules

EXPOSE 8080
CMD ["node", "dist/main.js"]

 

node:20-alpine 기반으로 의존성 설치하고, Prisma 클라이언트 생성 후 TypeScript 컴파일 수행한다. Prisma 스키마 기반으로 타입 안전한 DB 클라이언트 코드를 빌드 시점에 생성한다(npx prisma generate). 빌드 결과물(dist/, node_modules, prisma/)만 복사하여 경량 실행 이미지를 구성하였고, 서버 내부 포트는 8080이다.

 

# 이미지 빌드
docker build -t <Dodcker Hub user><image name>:<tag> .

# Docker Hub 푸시
docker push <Dodcker Hub user><image name>:<tag>

 

빌드된 이미지는 Docker Hub에 푸시하여 K3s 클러스터에서 Pull 한다.

 

K3s 구성

마스터 노드

우선 마스터 EC2 서버에 ssh로 접속하여 K3s 서버 노드를 설치해 보자.

curl -sfL https://get.k3s.io | sh -

 

다음 명령어로 서비스 상태를 확인할 수 있다.

sudo systemctl status k3s

 

이제 워커 노드를 연결할 때 필요한 마스터 노드 토큰을 확인해야 한다.

sudo cat /var/lib/rancher/k3s/server/node-token

 

다음 명령어를 실행했을 때 나오는 토큰을 복사한다.

 

워커 노드

워커 노드에 접속하여 아까 복사했던 토큰을 활용해 K3s 노드를 설치해 보자. 그전에 EC2 보안 그룹에 6443 포트 관련 규칙이 없다면 추가해줘야 한다. 마스터 노드와 외부를 연결하기 위해 내 IP, 마스터 노드와 내부 워커 노드를 연결하기 위해 워커 노드의 보안 그룹 ID를 소스로 추가해 준다.

curl -sfL https://get.k3s.io | \
  K3S_URL=https://<마스터_퍼블릭_IP>:6443 \
  K3S_TOKEN=<NODE_TOKEN> sh -

 

 

클러스터 노드 확인

kubectl get nodes

 

다음 명령어를 실행하면 Status 가 Ready인 노드 2개가 출력될 것이다.

 

Kubernetes Secret 구성

NestJS에서. env로 환경변수를 관리하듯, Kubrnetes Secret을 생성하여 환경 변수를 관리한다.

 

kubectl create secret generic project-secret
  --from-literal=DATABASE_URL="postgresql://user:password@<RDS_ENDPOINT>:5432/dbname" \
  --from-literal=REDIS_HOST="redis-service" \
  --from-literal=REDIS_PORT="6379" \
  --from-literal=NODE_ENV="prod"

 

PostgreSQL과 Redis 연동 정보를 작성해 줬다.

 

 

다음 포스트에서는 Redis 배포, Prisma 마이그레이션 적용, NestJS 앱 배포에 대해 다루겠다.

 

 

감사합니다 ♪(´▽｀)