NGINX Gateway Fabric: TCPRoute

이번 포스트에서는 NGINX Gateway Fabric(NGF)를 활용하여 Kubernetes Gateway API 환경에서 TCPRoute 구현 방법을 소개합니다.

NGINX Gateway Fabric 2.4.1이 이제 사용 가능하며, 이전 버전(1.x)에서 2.0으로 업그레이드하려면 이 지침을 따르세요. 1.x 문서의 경우 이전 버전 문서를 확인하세요.

이전 버전까지 TCPRoute를 지원하지 않았으나, 이제 NGINX Gateway Fabric 2.4.0부터 TCPRoute를 지원합니다! 이를 통해 NGINX Gateway Fabric과 백엔드 애플리케이션 간 TCP 연결을 쉽게 구성할 수 있습니다.

TCPRoute는 Gateway API 리소스로, TCP 연결 라우팅을 구성합니다. Gateway 리스너에 연결되면 리스너 포트에 도착한 연결을 하나 이상의 백엔드 서비스로 포워딩합니다.

이 기능을 통해 데이터베이스나 메시지 큐 같은 Non-HTTP 워크로드를 프록시할 수 있으며, 실제 예시로 Redis 연동을 통해 실전 적용 방안을 살펴보겠습니다. 추가로, TCPRoute의 활용성을 보여주기 위해 RedisInsight(Redis UI)를 배포하고 GUI를 통해 연결을 검증합니다.

목차

1. TCPRoute 개요
2. TCPRoute의 장점과 사용 사례
3. NGINX Gateway Fabric에서 TCPRoute 구성 방법
4. 실제 구성 예시
4-1. 매니페스트 파일 구성
4-2. 테스트와 결과 (Redis 연동 및 RedisInsight GUI 확인)
5. 결론

1. TCPRoute 개요

TCPRoute는 Kubernetes Gateway API의 v1alpha2 리소스로, TCP 기반 연결 라우팅을 정의합니다. Gateway 리스너에 연결되어 포트에 도착한 TCP 연결을 지정된 백엔드 서비스로 포워딩합니다.

NGINX Gateway Fabric 2.4.0부터 지원되며, HTTP/HTTPS 외에 Layer 4 트래픽을 처리할 수 있습니다. 이는 데이터베이스(MySQL, PostgreSQL, Redis), DNS 서버, 메시지 큐 등 Non-HTTP 워크로드를 Kubernetes에서 통합 관리할 수 있게 합니다.

예를 들어, Redis 같은 Key-value store를 TCPRoute로 프록시하면 외부 클라이언트가 Gateway를 통해 안전하게 접근할 수 있습니다. Gateway API의 확장 기능으로, 기본 설정 외에 NGINX의 고성능 프록시 기능을 활용합니다. 자세한 Gateway API 호환성은 공식 문서를 참조하세요.

TCPRoute는 단순 포워딩을 넘어, 다중 백엔드 지원과 함께 트래픽 부하를 고려한 설계가 가능하지만, 보안 및 모니터링을 위한 추가 정책 적용을 추천합니다.

2. TCPRoute 장점과 사용 사례

TCPRoute의 주요 장점은 다음과 같습니다:

  • Layer 4 트래픽 지원: HTTP 외에 TCP/UDP 기반 서비스를 Kubernetes Gateway로 통합 관리할 수 있습니다.
  • 쉬운 확장: Gateway API를 통해 선언적 구성으로 스케일링이 용이합니다.
  • 고성능: NGINX 기반으로 지연 없이 대량 트래픽 처리 가능합니다.

사용 사례로는 데이터베이스 프록시(Redis, MySQL), IoT 프로토콜, 또는 메시지 큐(Kafka) 연결이 적합합니다. 특히, multi-cloud 환경에서 TCPRoute를 활용해 통합 게이트웨이를 구축할 수 있습니다.

3. NGINX Gateway Fabric에서 TCPRoute 구성 방법

NGINX Gateway Fabric을 설치한 후, 백엔드 서비스(예: Redis)를 배포하고 Gateway 및 TCPRoute를 설정합니다. Redis 배포는 Redis Enterprise for Kubernetes 공식 가이드를 참조하세요. Gateway 리스너를 TCP 프로토콜로 정의하고, TCPRoute에서 백엔드 참조를 추가합니다.

테스트 시 redis-cli나 telnet으로 Gateway 외부 IP와 포트를 통해 연결을 검증합니다. 추가로, RedisInsight 배포를 통해 GUI 기반 확인이 가능합니다.

4. 실제 구성 예시

아래는 실제 환경에서 NGINX Gateway Fabric의 TCPRoute를 사용해 Redis를 연동한 예시입니다. Redis는 ho-redis 네임스페이스에 배포되었으며, TCPRoute를 통해 Gateway 포트(36379)로 연결됩니다.

4-1. 매니페스트 파일 구성

Redis 배포 상태 (ho-redis 네임스페이스):

kubectl get po,svc -n ho-redis
NAME          READY   STATUS    RESTARTS   AGE
pod/redis-0   1/1     Running   0          4d18h
NAME            TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
service/redis   ClusterIP   10.110.173.139   <none>        6379/TCP   4d18h

TCPRoute 및 Gateway 구성:

apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: redis-tcp-route
  namespace: ho-ngf
spec:
  parentRefs:
  - name: tcp-redis-gateway
    namespace: ho-ngf
    sectionName: redis
  rules:
  - backendRefs:
    - name: redis
      namespace: ho-redis
      port: 6379
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: tcp-redis-gateway
  namespace: ho-ngf
spec:
  gatewayClassName: nginx
  listeners:
  - name: redis
    port: 36379
    protocol: TCP
    allowedRoutes:
      kinds:
      - kind: TCPRoute

배포된 리소스 상태 (ho-ngf 네임스페이스):

root@master:~# kubectl get po,svc,tcproute,gateway -n ho-ngf
NAME                                           READY   STATUS    RESTARTS   AGE
pod/tcp-redis-gateway-nginx-86787b7444-4wd49   1/1     Running   0          6m9s
NAME                              TYPE           CLUSTER-IP      EXTERNAL-IP     PORT(S)           AGE
service/tcp-redis-gateway-nginx   LoadBalancer   10.111.217.87   192.168.40.75   36379:31240/TCP   4d20h
NAME                                                 AGE
tcproute.gateway.networking.k8s.io/redis-tcp-route   4d20h
NAME                                                  CLASS   ADDRESS         PROGRAMMED   AGE
gateway.gateway.networking.k8s.io/tcp-redis-gateway   nginx   192.168.40.75   True         4d20h

4-2. 테스트와 결과 (Redis 연동 및 RedisInsight GUI 확인)

Redis 연동 테스트: Gateway 외부 IP(192.168.40.75)와 포트(36379)를 통해 redis-cli로 연결합니다.

root@master:~# redis-cli -h 192.168.40.75 -p {Port}
192.168.40.75:36379> AUTH default hh123
OK
192.168.40.75:36379> SET testkey "Hello TCPRoute"
OK
192.168.40.75:36379> GET testkey
"Hello TCPRoute"

이 명령어로 TCPRoute를 통해 Redis에 데이터 저장/조회가 성공적으로 이루어집니다.

RedisInsight(Redis UI) 배포 상태 (redis-ui 네임스페이스):

root@master:~# k get po,svc -n redis-ui -o wide
NAME                                READY   STATUS    RESTARTS   AGE     IP            NODE          NOMINATED NODE   READINESS GATES
pod/redisinsight-6b49b5b556-hvpnt   1/1     Running   0          4d18h   10.0.123.62   workernode1   <none>           <none>
NAME                   TYPE       CLUSTER-IP     EXTERNAL-IP   PORT(S)          AGE     SELECTOR
service/redisinsight   NodePort   10.97.199.85   <none>        5540:30540/TCP   4d18h   app=redisinsight

RedisInsight 배포는 공식 문서를 참조하세요. 브라우저에서 NodePort(예: http://<node-ip&gt;:30540/)로 접근한 후, Redis 연결 설정에서 호스트를 Gateway 외부 IP(192.168.40.75), 포트 36379로 입력합니다.

GUI에서 데이터베이스를 불러오면 TCPRoute가 정상 작동하는 것을 확인할 수 있습니다. 이는 실제 운영 환경에서 TCPRoute를 활용한 모니터링/관리 유즈케이스를 보여줍니다.

+ Connect existing database를 클릭합니다.

배포된 Redis 데이터베이스 정보를 입력 후 Test Connection 버튼을 클릭하여 데이터베이스와 연결이 되는지 확인합니다. 우측 하단의 Connection is succesesful이 나타나면 Add Redis Database 버튼을 클릭하여 Database를 추가합니다.

위의 연동 확인 부분에서 CLI로 입력한 데이터 값도 포함되어 연동이 잘 된것을 확인할 수 있습니다.

5. 결론

NGINX Gateway Fabric의 TCPRoute는 Kubernetes에서 TCP 기반 서비스를 효과적으로 라우팅합니다. Redis 연동 예시처럼 데이터베이스 프록시나 GUI 도구(RedisInsight)와 결합해 활용하세요. 그러나 트래픽 모니터링과 보안 정책(예: TLS)을 추가로 적용하는 것이 중요합니다.

NGINX STORE에 문의하여 더 자세한 정보를 확인하세요.

NGINX STORE를 통한 솔루션 도입 및 기술지원 무료 상담 신청

* indicates required