서진호

3 분 소요

이번에는 단순한 HTTP Load Balancer를 통해 vLLM 배포에 외부 접근을 제공하도록 NGINX Ingress Controller를 구성한다. 이 방식은 vLLM API Endpoint에 대한 간단한 외부 접근을 제공한다.

1. 사전 요구 사항

이전 섹션을 완료했으며 vLLM Deployment가 default Namespace에서 실행 중인지 확인한다. 다음 항목이 준비되어 있어야 한다.

  • vLLM Deployment가 실행 중인 EKS 클러스터
  • 8080 포트에 노출된 vLLM Service
  • 시스템에 설치된 Helm

2. 환경변수 설정

export AWS_REGION=us-west-2
export CLUSTER_NAME=vllm-trn1-eks-cluster

# Set namespace to default (matching the actual pod/service deployment)
kubectl config set-context --current --namespace=default

3. NGINX Ingress Controller 설치

Helm을 사용해 NGINX Ingress Controller를 설치한다.

# Add NGINX Ingress Controller Helm repository
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx

# Install NGINX Ingress Controller
helm upgrade --install ingress-nginx ingress-nginx \
--repo https://kubernetes.github.io/ingress-nginx \
--namespace ingress-nginx \
--create-namespace

# Wait for the ingress controller to be ready
kubectl wait --namespace ingress-nginx \
  --for=condition=ready pod \
  --selector=app.kubernetes.io/component=controller \
  --timeout=90s

4. 단순 HTTP Ingress 생성

vLLM을 위한 단순한 Ingress 구성을 생성한다.

cat > vllm-ingress-simple.yaml <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: vllm-ingress-simple
  namespace: default
  annotations:
    # NGINX Ingress Controller annotations
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: vllm-service
            port:
              number: 8080
EOF

# Apply the ingress configuration
kubectl apply -f vllm-ingress-simple.yaml

5. Ingress 생성 상태 모니터링

Ingress Deployment의 상태를 확인한다.

echo "Checking ingress status..."
kubectl get ingress -A

# Wait for ingress to get external address using Kubernetes API
echo "Waiting for ingress to get external address..."
kubectl wait --for=jsonpath='{.status.loadBalancer.ingress[0].hostname}' ingress/vllm-ingress-simple --timeout=300s

# Check ingress details
kubectl describe ingress vllm-ingress-simple

# Get and display the external endpoint
VLLM_ENDPOINT=$(kubectl get ingress vllm-ingress-simple -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
echo "vLLM Ingress Endpoint: http://$VLLM_ENDPOINT"

6. curl로 Ingress Endpoint 테스트

Ingress Endpoint를 통해 vLLM API를 테스트한다.

# Get the ingress endpoint
export VLLM_ENDPOINT="http://$(kubectl get ingress vllm-ingress-simple -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')"

echo "Testing vLLM API with curl..."
curl -X POST "$VLLM_ENDPOINT/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tinyLlama/TinyLlama-1.1B-Chat-v1.0",
    "messages": [{"role": "user", "content": "Hello, how are you?"}],
    "max_tokens": 100,
    "temperature": 0.7
  }' | jq -r '.choices[0].message.content'

echo -e "\n\nBasic API tests completed!"

7. Python Client를 사용한 대화형 테스트

대화형 Python Test Client를 실행한다.

echo "Running interactive test client..."
python3 test-vllm-pod.py

8. Ingress 상태 모니터링

Ingress Deployment를 모니터링하고 필요한 경우 문제를 해결한다.

echo "=== Ingress Status ==="
kubectl get ingress vllm-ingress-simple -o wide

echo -e "\n=== Ingress Description ==="
kubectl describe ingress vllm-ingress-simple

echo -e "\n=== NGINX Ingress Controller Pods ==="
kubectl get pods -n ingress-nginx

echo -e "\n=== NGINX Ingress Controller Logs ==="
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller --tail=50

9. Ingress 문제 해결

NGINX Ingress에서 일반적으로 사용하는 문제 해결 명령어는 다음과 같다.

# Check if ingress controller is running
kubectl get pods -n ingress-nginx

# Check ingress controller logs
kubectl logs -n ingress-nginx deployment/ingress-nginx-controller

# Check ingress events
kubectl get events --sort-by=.metadata.creationTimestamp | grep -i ingress

# Verify service endpoints
kubectl get endpoints vllm-service

# Test connectivity from within cluster
kubectl run test-pod --image=curlimages/curl:latest -it --rm --restart=Never -- /bin/sh
# Inside the pod, test: curl http://vllm-service:8080/health

# Check LoadBalancer service for ingress controller
kubectl get svc -n ingress-nginx

# Get detailed ingress configuration
kubectl get ingress vllm-ingress-simple -o yaml

10. Ingress 아키텍처 요약

NGINX Ingress 구성은 다음 기능을 제공한다.

  1. NGINX Ingress Controller: 단순한 HTTP Load Balancing과 Routing을 제공한다.
  2. 외부 접근: vLLM API를 위한 Public Endpoint를 제공한다.
  3. 경로 기반 Routing: 모든 트래픽을 8080 포트의 vLLM Service로 전달한다.
  4. 단순한 구성: 개발과 테스트를 위한 최소 구성을 제공한다.
  5. 표준 HTTP: curl 및 HTTP Client로 쉽게 테스트할 수 있다.

11. 다음 단계

Ingress 구성이 완료되어 vLLM Deployment에 외부에서 접근할 수 있다. 다음 작업을 수행할 수 있다.

  • 제공된 curl 명령어를 사용해 API를 테스트한다.
  • Python Script를 사용해 대화형 테스트를 수행한다.
  • External Endpoint를 사용해 다른 애플리케이션과 통합한다.
  • 모니터링과 Logging을 위해 Observability 섹션으로 이동한다.

12. 참고자료

댓글남기기