Node.js 애플리케이션을 Kubernetes에 Ingress로 배포하는 전략

by

Kubernetes에 Node.js 백엔드 애플리케이션을 배포할 때, 단순히 서비스(Service)와 디플로이먼트(Deployment)만 구성해서는 외부에서 접근하기 어렵습니다. 특히 프로덕션 환경에서는 Ingress Controller를 활용해 도메인 기반 라우팅, TLS 인증서 연동, 접근 제어까지 구성하는 것이 일반적입니다.

이번 글에서는 Helm으로 Ingress-NGINX를 설치하고, Node.js 애플리케이션을 Ingress 리소스를 통해 외부 노출하는 전략을 단계별로 소개합니다. 외부에서는 NGINX로 들어온 요청이 Kubernetes의 Ingress를 거쳐 NodePort에 연결되는 구조이며, 이 구성을 통해 안정적인 API 배포 환경을 구축할 수 있습니다.

1. Ingress-NGINX 설치하기 (Helm 기반)

먼저 Ingress 컨트롤러로 사용할 ingress-nginx를 Helm을 통해 설치합니다.

helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.type=NodePort \
  --set controller.service.nodePorts.http=30080 \
  --set controller.service.nodePorts.https=30443

위 명령은 다음을 의미합니다:

  • NodePort 방식으로 외부 연결 지원
  • HTTP는 30080 포트, HTTPS는 30443 포트로 노출

이제 클러스터 외부에서 30080 포트를 통해 Ingress에 접근할 수 있는 상태가 됩니다.

2. 외부 NGINX와 Kubernetes 연동 구조 이해

외부에 설치된 NGINX가 Kubernetes Node에 포워딩해주는 구조는 다음과 같습니다:

[클라이언트]
     |
     v
[ 외부 NGINX (21080) ]
     |
     v
[ k8s 노드:30080 (Ingress) ]
     |
     v
[ Ingress Controller ]
     |
     v
[ Node.js 서비스 (ClusterIP) ]

즉, NGINX는 포트 21080으로 들어온 트래픽을 Kubernetes Ingress의 NodePort (예: 30080)로 전달합니다. Ingress Controller는 설정된 규칙에 따라 적절한 서비스로 트래픽을 라우팅합니다.

외부 NGINX 설정 예시

stream {
  log_format proxy '$remote_addr [$time_local] '
                   '$protocol $status $bytes_sent $bytes_received '
                   '$session_time "$upstream_addr"';

  access_log /etc/nginx/logs/nodejs-access.log proxy;
  error_log  /etc/nginx/logs/nodejs-error.log;

  upstream ingress_k8s {
      server 192.168.0.101:30080;
      server 192.168.0.102:30080;
      server 192.168.0.103:30080;
  }

  server {
      listen 21080;
      proxy_pass ingress_k8s;
  }
}

위 구성에서 NGINX는 round-robin으로 Kubernetes 노드의 Ingress NodePort에 요청을 전달합니다.

3. Node.js 애플리케이션 배포

간단한 Node.js 애플리케이션을 배포한다고 가정해 보겠습니다. (이미 Docker 이미지가 빌드되어 있다고 가정)

Deployment 예시

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nodejs-app
  namespace: demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nodejs
  template:
    metadata:
      labels:
        app: nodejs
    spec:
      containers:
      - name: app
        image: your-docker-repo/nodejs-app:latest
        ports:
        - containerPort: 3000

Service 예시

apiVersion: v1
kind: Service
metadata:
  name: nodejs-service
  namespace: demo
spec:
  type: ClusterIP
  selector:
    app: nodejs
  ports:
  - port: 80
    targetPort: 3000

4. Ingress 리소스 구성

Node.js 서비스에 대해 Ingress 리소스를 설정해 줍니다:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: nodejs-ingress
  namespace: demo
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: node.demo.local
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: nodejs-service
            port:
              number: 80

Ingress는 node.demo.local 도메인으로 접근 시, nodejs-service로 트래픽을 전달하도록 설정합니다.

⚠️ /etc/hosts 파일에 도메인을 수동으로 매핑해야 테스트가 가능합니다:

echo "<외부-NGINX-IP> node.demo.local" | sudo tee -a /etc/hosts

5. 브라우저에서 접속 테스트

브라우저에서 다음 주소로 접속해보세요:

http://node.demo.local:21080

요청은 외부 NGINX → k8s NodePort (30080) → Ingress → Node.js 서비스 순으로 전달됩니다.

6. 마무리하며

이번 글에서는 Helm Chart를 이용한 ingress-nginx 설치부터 Node.js 앱 Ingress 연동, 외부 NGINX를 통한 프록시 구성까지 전체적인 흐름을 정리해봤습니다. 이 구조는 프로덕션 환경에서도 잘 활용할 수 있으며, SSL 인증서(TLS), 인증(Auth), CORS, Rate Limiting 같은 기능도 Ingress에 추가로 연동 가능합니다.

다음 글에서는 TLS 인증서를 Let’s Encrypt와 자동 연동하여 HTTPS 기반 배포를 구축하는 방법을 다뤄보겠습니다. 감사합니다 🙌

Leave a Comment