[Kubernetes] 🌐 Kong으로 TCP/TLS 서비스 외부 노출: LoadBalancer + SNI + Gateway API

Kubernetes에서 Redis·DB 같은 순수 TCP 서비스를 도메인으로 외부 노출하려면, Kong의 stream 리스너 + SNI를 쓰면 됩니다. 이 글에서는 LoadBalancer로 받은 포트 하나(예: 9443)에서 SNI(도메인)로 여러 TCP/TLS 백엔드를 분배하는 구성을, Helm values부터 Gateway API(TLSRoute) 매니페스트, 그리고 에러 메시지가 바뀌며 원인을 좁혀가는 디버깅 과정까지 실무 관점으로 다룹니다.

핵심 아이디어 한 줄: “포트 하나로 다 받고, SNI로 백엔드를 가른다.” LB에 노출된 포트가 몇 개뿐이어도 백엔드는 수십 개가 가능합니다.

1클라이언트 ──(TLS + SNI)──▶ LoadBalancer(외부 IP) ──▶ Kong(stream 리스너, ssl)
2                                                          └─(SNI로 분배)─▶ redis-a / redis-b / db-1 ...

🧭 무엇을 하려는가 #

목표는 “HTTP가 아닌 TCP 서비스"를 도메인 기반으로 외부에 여는 것입니다. Ingress·HTTPRoute는 HTTP(L7) 전용이라 Redis·PostgreSQL 같은 raw TCP에는 쓸 수 없습니다. 대신 Kong의 stream(L4) 리스너에 TLS를 얹고, TLS ClientHello의 SNI로 어느 백엔드인지 가릅니다.

• 입력: 클라이언트가 redis-a.example.com:9443으로 TLS 접속(SNI에 도메인 실림).
• Kong: 9443 stream 리스너에서 TLS를 처리하고, SNI를 보고 redis-a 서비스로 연결.
• 결과: LB 포트 하나(9443)로 여러 백엔드를 도메인별 분배.

💡 전제: 외부 IP를 자동 할당하는 LoadBalancer가 이미 제공되는 환경(클라우드 LB, MetalLB 등). 없으면 NodePort로도 되지만 이 글은 LoadBalancer 기준입니다.

🆚 tls 리스너 vs stream 리스너 (가장 헷갈리는 지점) #

Kong values에서 proxy.tls와 proxy.stream은 완전히 다른 계층입니다. 이걸 혼동하면 raw TCP를 HTTPS 리스너에 물리는 실수를 합니다.

Redis·DB를 외부로 낼 때 필요한 건 stream 쪽입니다. 그리고 stream 포트에 ssl을 얹어야 SNI 기반 TLS 스트림 라우팅이 됩니다.

HTTP(S) 서비스라면 이 글이 아니라 Ingress → Gateway API HTTPRoute 전환이나 Gateway API HTTP→HTTPS 리다이렉트를 참고하세요.

🔀 Gateway API 버전: TCPRoute·TLSRoute는 지금 어디에? #

이 영역은 빠르게 바뀝니다. L4 라우트(TLSRoute·TCPRoute·UDPRoute)는 오랫동안 experimental이었고, 최근에야 단계적으로 GA로 승격됐습니다.

⚠️ 핵심 함정: 업스트림 스펙이 GA여도 Kong(KIC)이 그 버전을 따라왔는지가 관건입니다. 현재 Kong Ingress Controller는 TLSRoute·TCPRoute·UDPRoute를 v1alpha2 API 그룹 + GatewayAlpha 피처 게이트 + experimental CRD로 다룹니다. 즉 스펙상 Standard여도 Kong에서는 여전히 experimental 채널이 필요할 수 있습니다.

지금 내 클러스터는 어떤 상태인가? (확인 명령) #

1# 설치된 Gateway API 번들 버전
2kubectl get crd gateways.gateway.networking.k8s.io \
3  -o jsonpath='{.metadata.annotations.gateway\.networking\.k8s\.io/bundle-version}'
4
5# TLSRoute/TCPRoute CRD가 제공하는 버전 (v1이 보이면 GA본, v1alpha2뿐이면 experimental)
6kubectl get crd tlsroutes.gateway.networking.k8s.io -o jsonpath='{.spec.versions[*].name}'
7kubectl get crd tcproutes.gateway.networking.k8s.io -o jsonpath='{.spec.versions[*].name}'

experimental 리소스를 쓰려면 experimental 번들 설치 + 컨트롤러 피처 게이트가 필요합니다.

1# experimental 채널 CRD 설치 (TCPRoute/UDPRoute/TLSRoute 포함)
2kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.6.0/experimental-install.yaml

1# KIC values 발췌 — 컨트롤러에 GatewayAlpha 피처 게이트 활성화
2controller:
3  ingressController:
4    env:
5      feature_gates: "GatewayAlpha=true"

⚠️ 업그레이드 주의: v1.4 이하의 experimental TLSRoute가 있는 상태에서 v1.5 standard를 덮어 설치하면, 기존 리소스가 v1alpha2로 저장돼 못 쓰게 될 수 있습니다. 기존 클러스터를 올릴 땐 마이그레이션 경로를 먼저 확인하세요.

Kong 설치 자체가 처음이라면 Kong Ingress Controller 설치 (Gateway API)를 먼저 보고 오세요.

🛠️ Kong 설치 (Helm): NodePort → LoadBalancer + stream 리스너 #

LoadBalancer 타입으로 바꾸고, stream 리스너를 추가하고, TLS 포트에 ssl을 얹는 것이 핵심입니다. 예전 NodePort 흔적(nodePort: 30054 등)은 걷어냅니다.

 1# kong values.yaml 발췌
 2proxy:
 3  type: LoadBalancer          # NodePort → LoadBalancer (외부 IP 자동 할당)
 4  http:
 5    enabled: true
 6    servicePort: 80
 7    containerPort: 8000
 8  tls:                        # = HTTPS(L7) 리스너
 9    enabled: true
10    servicePort: 443
11    containerPort: 8443
12  stream:                     # = raw TCP/TLS(L4) 스트림 리스너
13    - containerPort: 9000
14      servicePort: 9000
15      protocol: TCP           # 평문 TCP
16    - containerPort: 9443
17      servicePort: 9443
18      protocol: TCP
19      parameters:
20        - "ssl"               # ★ 이 포트를 TLS 리스너로 → SNI 라우팅의 필수 조건

포인트를 정리하면:

• nodePort 삭제 → LoadBalancer가 포트를 자동 할당. 클라이언트는 LB외부IP:9443으로 접속.
• servicePort = 외부 접속 포트. containerPort = Kong 파드 내부 포트.
• parameters: ["ssl"] = 그 stream 포트를 TLS로 처리(SNI를 읽을 수 있게 됨). 이게 빠지면 Kong이 그 포트를 평문 TCP로 취급해 TLS 클라이언트와 미스매치가 납니다.

💡 parameters에는 ssl 외에 proxy_protocol, reuseport, backlog=N 등도 넣을 수 있고, Kong 내부의 KONG_STREAM_LISTEN에 자동 반영됩니다. 환경변수를 kubectl set env로 직접 넣으면 다음 helm 배포 때 덮여 사라지므로, 반드시 values의 parameters를 쓰세요.

배포:

1helm upgrade --install kong kong/kong -n kong --create-namespace -f values.yaml

🚪 Gateway + TLSRoute로 SNI 분배 구성 #

Gateway에 stream 리스너를 선언하고, TLSRoute로 SNI(도메인) → 백엔드를 매핑합니다. 리스너 프로토콜은 TLS입니다.

1️⃣ GatewayClass & Gateway #

 1apiVersion: gateway.networking.k8s.io/v1
 2kind: Gateway
 3metadata:
 4  name: kong
 5  namespace: kong
 6spec:
 7  gatewayClassName: kong
 8  listeners:
 9    - name: stream9443           # ★ 이 이름이 Service 포트 이름과 정렬돼야 함(함정 ②)
10      port: 9443
11      protocol: TLS
12      hostname: "*.example.com"  # SNI 와일드카드
13      tls:
14        mode: Terminate          # Kong이 TLS 종료 후 SNI로 백엔드 분배
15        certificateRefs:
16          - kind: Secret
17            name: wildcard-example-com-tls
18      allowedRoutes:
19        kinds:
20          - kind: TLSRoute
21        namespaces:
22          from: All

• mode: Terminate — Kong이 TLS를 풀고(인증서 필요) SNI로 백엔드를 고른 뒤 평문으로 전달.
• mode: Passthrough — Kong은 복호화하지 않고 SNI만 보고 그대로 백엔드로 흘림(백엔드가 TLS를 직접 처리). 백엔드 TLS를 유지해야 하면 이쪽.
• 인증서 Secret은 cert-manager로 발급·관리하면 편합니다.

2️⃣ TLSRoute (SNI → 백엔드) #

 1apiVersion: gateway.networking.k8s.io/v1alpha2   # Kong은 아직 v1alpha2 (버전 확인!)
 2kind: TLSRoute
 3metadata:
 4  name: redis-a
 5  namespace: kong
 6spec:
 7  parentRefs:
 8    - name: kong
 9      sectionName: stream9443     # 위 Gateway 리스너 이름과 일치
10  hostnames:
11    - "redis-a.example.com"       # 이 SNI로 온 트래픽만
12  rules:
13    - backendRefs:
14        - name: redis-a           # 대상 Service
15          port: 6379

백엔드를 하나 더 늘리려면 TLSRoute만 추가하면 됩니다(같은 리스너에 redis-b.example.com → redis-b:6379). 포트는 그대로 9443 하나입니다.

평문 TCP(포트별 분배, SNI 불필요)만 필요하면 protocol: TCP 리스너 + TCPRoute를 씁니다. 이땐 도메인이 아니라 포트로만 구분됩니다.

⚠️ 핵심 함정 3가지 (직접 겪은 것) #

① stream 리스너에 ssl이 없으면 → TLS 미스매치 #

클라이언트는 TLS로 접속하는데 Kong이 그 포트를 평문으로 받으면, “봉투를 엽서로 읽으려다” 깨집니다. 대표 증상은 ssl: packet length too long. → stream 리스너에 parameters: ["ssl"] 로 해결.

② Gateway 리스너 이름 ↔ Service 포트 이름 불일치 #

• Gateway listener 이름: stream9443
• Helm이 만든 Service 포트 이름: stream-9443

이 둘이 어긋나면 Gateway가 리스너를 실제 포트에 못 묶어 연결이 성립하지 않습니다. 이름을 맞춰야 합니다(필요 시 Service/Deployment를 patch해 포트 이름 정렬).

1# Service의 실제 포트 이름 확인
2kubectl get svc -n kong kong-kong-proxy -o jsonpath='{.spec.ports[*].name}'; echo

③ LoadBalancer IP 접속은 방화벽/보안그룹을 넘어야 함 #

포트포워딩(Pod 직접)은 되는데 LB IP로만 안 되면, 십중팔구 경로상의 방화벽입니다. 해당 포트(9443)의 인바운드 허용을 확인하세요. (실제 사례의 최종 원인이 이것이었습니다.)

🔎 디버깅: 에러가 바뀌면 한 단계 전진한 것 #

이 문제의 핵심 교훈은 “에러 메시지가 바뀐다는 건 한 홉 앞으로 갔다는 신호” 라는 점입니다. 실제로 겪은 순서:

홉 단위로 격리해 좁히기 #

“어느 홉에서 깨졌나"를 격리로 좁히는 것이 가장 빠릅니다.

 1# (1) Kong 자체가 정상인지 — LB를 건너뛰고 Pod에 직접
 2kubectl port-forward -n kong <kong-pod> 9443:9443
 3openssl s_client -connect 127.0.0.1:9443 -servername redis-a.example.com
 4#  → 되면 Kong은 정상, 문제는 LB 경로
 5
 6# (2) LB IP로 TCP부터 (TLS 이전 단계)
 7nc -vz <LB_IP> 9443
 8#  → 안 되면 방화벽/포트 미노출, 되면 TLS 단계 문제
 9
10# (3) LB IP로 TLS 핸드셰이크 + SNI
11openssl s_client -connect <LB_IP>:9443 -servername redis-a.example.com

포트포워딩은 되는데 LB만 안 되면, 문제는 항상 LB ↔ Kong 사이(방화벽 / 포트 이름 / PROXY protocol)로 좁혀집니다.

💡 클라이언트가 SNI를 못 보내는 도구라면(일부 DB 클라이언트), 로컬에 stunnel 등을 두고 SNI를 부여해 Kong으로 보낼 수 있습니다.

✅ 검증 체크리스트 #

1# 외부 IP·포트가 제대로 노출됐는지 (EXTERNAL-IP 실제 값, PORT(S)에 9443)
2kubectl get svc -n kong
3
4# 백엔드 Pod가 실제로 잡혀 있는지 (비어 있으면 timeout의 흔한 원인)
5kubectl get endpoints -n kong
6
7# 리스너 반영됐는지 (patch 후 롤아웃)
8kubectl rollout status deploy/kong-kong -n kong

• proxy.type: LoadBalancer, nodePort 제거, servicePort 지정
• stream 리스너에 parameters: ["ssl"] (SNI용 TLS)
• Gateway 리스너 이름 ↔ Service 포트 이름 일치
• LB IP의 해당 포트 방화벽 인바운드 허용
• (클라이언트가 SNI 못 보내면) stunnel 등으로 SNI 부여
• Gateway API CRD 채널/버전과 Kong 지원 버전(GatewayAlpha·v1alpha2) 확인

📐 규모별 변형 #

규모에 따라 달라지는 지점만 모으면 다음과 같습니다. 기본 전제는 LoadBalancer가 제공되는 환경입니다.

💡 소규모에서 백엔드가 2~3개뿐이고 도메인 구분이 필요 없으면, SNI 없이 포트별 TCPRoute가 더 단순합니다. SNI 분배는 “포트는 아끼고 백엔드는 많이"가 필요할 때 빛납니다.

🤔 언제 무엇을 쓰나 #

“HTTP냐 아니냐”, “도메인으로 가르냐 포트로 가르냐” 두 축으로 결정됩니다.

❓ 자주 묻는 질문 #

Q. Ingress로 Redis·DB를 외부에 못 여나요? Ingress·HTTPRoute는 HTTP(L7) 전용이라 raw TCP는 안 됩니다. TCP는 stream 리스너 + TCPRoute/TLSRoute를 써야 합니다.

Q. packet length too long 에러는 왜 나나요? 클라이언트는 TLS인데 Kong stream 포트가 평문(ssl 없음)이라 생기는 프로토콜 미스매치입니다. parameters: ["ssl"]을 추가하세요.

Q. 포트포워딩은 되는데 LB IP로만 안 됩니다. 문제는 LB↔Kong 사이입니다. 대개 방화벽/보안그룹 인바운드(해당 포트 미개방)나 포트 이름 불일치입니다.

Q. 왜 포트 하나(9443)에서 여러 백엔드가 되나요? TLS ClientHello의 SNI(도메인) 로 Kong이 백엔드를 고르기 때문입니다. 백엔드를 늘려도 LB 포트는 그대로입니다.

Q. Terminate와 Passthrough 중 뭘 쓰나요? Kong에서 TLS를 풀고 평문으로 전달하면 Terminate, 백엔드까지 암호화를 유지하려면 Passthrough입니다.

Q. TLSRoute를 apply했는데 인식이 안 됩니다. Kong은 아직 v1alpha2 + GatewayAlpha 피처 게이트 + experimental CRD가 필요할 수 있습니다. CRD 버전과 컨트롤러 피처 게이트를 확인하세요.

Q. 클라이언트가 SNI를 못 보냅니다. 로컬에 stunnel 등을 두고 SNI를 부여해 Kong으로 전달하면 됩니다.

📚 참고 #

• Kong 차트 values.yaml (stream[].parameters)
• Kong Ingress Controller — Gateway API
• Kong Gateway 설정 레퍼런스 (stream_listen)
• Gateway API — Getting started (릴리스 채널)
• Gateway API v1.5: Moving features to Stable (TLSRoute → Standard)
• Gateway API — TCP routing 가이드
• 관련 글: Kong Ingress Controller 설치 (Gateway API)
• 관련 글: Ingress → Gateway API HTTPRoute 전환
• 관련 글: Gateway API로 HTTP→HTTPS 리다이렉트
• 관련 글: Kubernetes cert-manager로 PKI·TLS 인증서 관리