Kubernetes에 Node.js 배포와 HPA 설정

소개

이 글은 Kubernetes 환경에 Node.js 애플리케이션을 배포하고 Horizontal Pod Autoscaler(HPA)를 설정하는 과정을 쉽게 풀어 설명한다. 초보자도 따라할 수 있도록 Docker 이미지 제작부터 Deployment 구성, Service 노출, HPA 적용, 그리고 Helm 차트를 통한 반복 배포 예제까지 포함한다. 핵심은 실무에서 바로 적용 가능한 구성 예제와 함께 개념을 이해하는 것이다.

사전 준비

필수 요소

• kubectl 접근 가능한 Kubernetes 클러스터
• Docker(또는 컨테이너 레지스트리) 계정
• Node.js 애플리케이션 소스 코드
• metrics-server가 클러스터에 설치되어 있어야 HPA가 정상 동작

1. Node.js 애플리케이션 컨테이너화

간단한 Express 앱을 기준으로 Dockerfile을 만든다. 이미지가 작고 실행이 빠른 베이스 이미지를 사용하는 것이 좋다.

FROM node:18-alpine
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "index.js"]

2. Deployment와 Service 작성

Deployment는 애플리케이션 복제본과 업데이트 전략을 정의한다. Service는 클러스터 내부 또는 외부에서 접근할 수 있게 한다.

Deployment 예제

apiVersion: apps/v1
kind: Deployment
metadata:
  name: node-app-deployment
spec:
  replicas: 2
  selector:
    matchLabels:
      app: node-app
  template:
    metadata:
      labels:
        app: node-app
    spec:
      containers:
      - name: node-app
        image: your-registry/node-app:1.0.0
        ports:
        - containerPort: 3000
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "500m"
            memory: "256Mi"

Service 예제 (ClusterIP -> LoadBalancer로 변경 가능)

apiVersion: v1
kind: Service
metadata:
  name: node-app-service
spec:
  selector:
    app: node-app
  ports:
  - protocol: TCP
    port: 80
    targetPort: 3000
  type: ClusterIP

3. HPA 설정

HPA는 CPU 또는 커스텀 메트릭을 기준으로 Pod 수를 자동으로 조절한다. metrics-server가 필요하며, 최소 및 최대 파드를 지정한다.

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: node-app-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: node-app-deployment
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60

위 설정은 평균 CPU 사용률이 60%를 넘으면 자동으로 스케일 아웃한다. 필요하면 메모리나 커스텀 메트릭을 사용해 더 정교하게 조절할 수 있다.

4. 롤링 업데이트 전략

Deployment의 업데이트 전략을 통해 다운타임 없이 새 버전으로 전환한다. 기본 설정으로도 롤링 업데이트가 적용되지만, maxSurge와 maxUnavailable 값을 조절해 가용성을 확보할 수 있다.

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 25%
    maxUnavailable: 25%

5. Helm 차트로 배포 자동화

Helm을 사용하면 반복 배포를 간편하게 관리할 수 있다. values.yaml에서 이미지, 리플리카 수, 리소스 요청값, HPA 설정을 파라미터화한다.

# values.yaml (일부 발췌)
image:
  repository: your-registry/node-app
  tag: 1.0.0
replicaCount: 2
resources:
  requests:
    cpu: "100m"
    memory: "128Mi"
hpa:
  enabled: true
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilizationPercentage: 60

이 구성은 CI/CD 파이프라인과 결합해 무중단 배포, 버전 롤백, 환경별 설정을 쉽게 처리할 수 있게 한다. Node 애플리케이션 Helm 차트 를 활용하면 환경별 차이를 values로 관리할 수 있다.

6. 모니터링과 테스트

HPA 동작을 검증하려면 부하를 발생시켜 CPU 사용률을 올려 본다. 아래 예시는 간단한 부하 생성 방법이다.

# 예: curl을 이용한 단시간 부하
for i in {1..1000}; do curl -s http:/// > /dev/null & done

Prometheus와 Grafana를 함께 쓰면 리소스 사용량과 HPA 확장 이벤트를 시각적으로 확인할 수 있다. 로그는 Fluentd 또는 Loki로 중앙집중화하면 문제 원인 파악에 유리하다.

결론

이 글은 Kubernetes Node.js 배포 예제와 K8s HPA Node.js 설정을 중심으로 Deployment부터 HPA, Helm 차트 적용까지 전반적 흐름을 설명했다. 핵심은 컨테이너 이미지의 안정성, 리소스 요청·제한 설정, 그리고 metrics-server 기반의 HPA 구성이다. 이를 기반으로 운영 환경에 맞는 세부 조정을 추가하면 안정적이고 자동 확장되는 Node.js 서비스 운영이 가능하다.