NGINX Gateway Fabric 트래픽 라우팅: Redirect 및 Rewrite

이 포스트는 Kubernetes 클러스터에 배포된 NGINX Gateway Fabric 의 트래픽 라우팅 설정을 위해 redirect와 rewrite 옵션을 사용하는 방법에 관해 설명합니다. 트래픽 라우팅에 필요한 Gateway 리소스를 먼저 생성하고, HTTRoute 리소스에 redirect, rewrite 설정을 적용하여 트래픽을 라우팅하는 방법을 알아보겠습니다.

이 포스트는 NGINX Gateway Fabric의 설치 과정은 다루지 않습니다. 설치 방법은 NGINX Gateway Fabric 설치 혹은 NGINX Gateway Fabric Helm 설치 가이드를 참고하세요.

목차

1. NGINX Gateway Fabric이란?
2. 버전 정보
3. NGINX Gateway Fabric 트래픽 라우팅
 3-1. NGINX Gateway Fabric 트래픽 라우팅 – redirect
 3-2. NGINX Gateway Fabric 트래픽 라우팅 – rewrite
4. 결론

1. NGINX Gateway Fabric이란?

NGINX Gateway Fabric은 NGINX를 데이터플레인으로 사용하여 Kubernetes의 Gateway API를 구현하는 프로젝트입니다. Gateway API는 Kubernetes의 네트워크 트래픽을 관리하고 제어하기 위한 표준화된 인터페이스로, 기존의 Ingress API를 대체하거나 확장하는 데 목적을 두고 있습니다.

NGINX Gateway Fabric은 기본적으로 기존의 Ingress Controller와 같이 Kubernetes 클러스터 외부의 트래픽을 관리하는 역할을 하며, Gateway API 표준 리소스인 Gateway, HTTPRoute를 통해 복잡한 Annotation이나 Custom Resource를 사용하지 않고도 구성할 수 있습니다.

2. 버전 정보

  • Kubernetes : v1.30.3
  • NGINX Gateway Fabric : 1.6.0 (Stable release)

3. NGINX Gateway Fabric 트래픽 라우팅

예제를 위한 전체 리소스 구성은 아래와 같습니다.

NGINX Gateway Fabric 트래픽 라우팅 예제 구성

HTTPRoutes 리소스를 생성하여 트래픽 라우팅을 위한 redirect, rewrite 설정 방법을 알아보기 전에, NGINX Gateway Fabric을 통한 트래픽 라우팅 구성에 필수적인 Gateway 리소스를 생성하고, 트래픽이 라우팅 될 NGINX Demo Deployment, Service를 배포하도록 하겠습니다.

예제에 사용된 yaml 파일들은 NGINX STORE GitHub 리포지토리에서 확인하실 수 있습니다.

gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: default-gw
  namespace: nginx-gateway         # nginx-gateway 네임스페이스에 배포
spec:
  gatewayClassName: nginx          # NGINX Gateway Fabric 사용을 위한 Class 설정
  listeners:
  - name: http                     # listener 이름 지정
    hostname: "*.devopssong.com"   # listener의 hostname 설정
    port: 80
    protocol: HTTP
    allowedRoutes:                 # cross-namespace 설정
      namespaces:
        from: Selector             # selector 설정을 통해 해당하는 네임스페이스 허용
        selector:
          matchLabels:
            kubernetes.io/metadata.name: demo   # demo 네임스페이스의 Route 허용

클러스터에 들어오는 트래픽의 진입점이 되는 Gateway 리소스 구성입니다.”*.devopssong.com” 도메인의 HTTP 요청을 80번 포트로 수신하는 Gateway 구성입니다. hostname 설정은 필수가 아닌 선택 설정 항목으로, 이후에 구성할 HTTPRoute에서 구성될 수도 있습니다.
위 Gateway 리소스는 NGINX Gateway Fabric이 배포된 네임스페이스에 배포하였으나, NGINX Gateway Fabric이 배포되지 않은 다른 네임스페이스에 배포할 수도 있습니다.

기본적으로 Gateway 리소스는 같은 네임스페이스에 구성된 HTTPRoute 리소스만 연결될 수 있습니다. 하지만 위 구성처럼 allowedRoute 설정을 통해 다른 네임스페이스의 HTTPRoute 리소스가 해당 Gateway 리소스와 연결될 수 있도록 설정할 수 있습니다. 

    allowedRoutes:                 # cross-namespace 설정
      namespaces:
        from: Selector # | All | Same
        selector:
          matchLabels:
            kubernetes.io/metadata.name: demo   # demo 네임스페이스의 Route 연결 허용

from의 값에 따라 Gateway 리소스와 연결될 수 있는 네임스페이스의 범위가 설정됩니다.
기본값은 Same으로 같은 네임스페이스 내부의 HTTPRoute 리소스만 연결될 수 있으며, All의 경우 모든 네임스페이스에서 연결 가능합니다. Selector로 설정 시, selector.matchLabels 에 정의된 레이블이 존재하는 네임스페이스의 HTTPRoute 리소스가 연결될 수 있습니다.

예제에서 구성된 kubernetes.io/metadata.name 레이블은 네임스페이스를 생성하면 자동으로 생성되는 레이블로, 아래와 같이 사용자가 지정한 레이블로 구성할 수도 있습니다.

    allowedRoutes:             
      namespaces:
        from: Selector
        selector:
          matchLabels:
            default-gw-access: "true"

위와 같이 레이블을 구성하고, 아래와 같이 레이블을 네임스페이스에 추가할 수 있습니다.

$ kubectl label namespaces demo default-gw-access=true

namespace/demo labeled

$ kubectl get ns demo --show-labels

NAME   STATUS   AGE   LABELS
demo   Active   9d    default-gw-access=true,kubernetes.io/metadata.name=demo

NGINX Gateway Fabric을 통해 연결될 백엔드 Deployment/Service 구성입니다.

nginx-hello.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-hello
  namespace: demo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-hello
  template:
    metadata:
      labels:
        app: nginx-hello
    spec:
      containers:
      - name: nginx-hello
        image: nginxdemos/nginx-hello:plain-text
        ports:
        - containerPort: 80
nginx-hello-svc.yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx-hello-svc
  namespace: demo
spec:
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: nginx-hello
NGINX Gateway Fabric 트래픽 라우팅 테스트 Pod

해당 Pod는 위와 같이 요청을 수신하면 URI 정보를 포함한 응답을 반환하는 Pod입니다.
Deployment를 통해 배포하고 Service를 통해 연결할 수 있도록 구성했으며, 모두 demo 네임스페이스에 배포됩니다.

3-1. NGINX Gateway Fabric 트래픽 라우팅 – redirect

NGINX Gateway Fabric을 통해서 트래픽을 라우팅하려면, 앞서 구성한 Gateway 리소스와 연결될 HTTPRoutes 리소스 생성이 필요합니다.

NGINX Gateway Fabric 트래픽 라우팅 - redirect
redirect-route.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: redirect-route
  namespace: demo
spec:
  parentRefs:                       # 연결할 Gateway 리소스 정의
    - name: default-gw
      namespace: nginx-gateway
  hostnames:                        # hostname 설정
  - redirect.devopssong.com
  rules:                            # 라우팅 규칙 설정
  - matches:                        # 규칙1
    - path:                         
        type: PathPrefix
        value: /
    backendRefs:
    - name: nginx-hello-svc
      port: 80
  - matches:                        # 규칙2
    - path:
        type: PathPrefix
        value: /tom
    filters:
    - type: RequestRedirect
      requestRedirect:
        path:
          type: ReplaceFullPath
          replaceFullPath: /jerry
        statusCode: 301
  - matches:                        # 규칙3
    - path:                        
        type: PathPrefix
        value: /cat
    filters:
    - type: RequestRedirect        
      requestRedirect:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /dog
        statusCode: 302

위 HTTPRoute 리소스에는 3개의 라우팅 규칙이 정의되어 있습니다. 각 규칙에 대해 알아보겠습니다.

  - matches:
    - path:                         
        type: PathPrefix
        value: /
    backendRefs:
    - name: nginx-hello-svc
      port: 80

/로 시작하는 요청을 앞서 구성한 Service인 nginx-hello-svc의 80번 포트로 라우팅하는 규칙입니다.
matches.path.type을 exact로 변경 시 정확히 일치하는 경로만 라우팅합니다.

  - matches:
    - path:
        type: PathPrefix
        value: /tom
    filters:
    - type: RequestRedirect
      requestRedirect:
        path:
          type: ReplaceFullPath
          replaceFullPath: /jerry
        statusCode: 301

/tom으로 시작하는 요청을 301 응답 코드와 함께 /jerry 경로로 리다이렉트 합니다. filters.requestRedirect.path.type 설정이 ReplaceFullPath이므로, /tom의 하위 경로가 제거되고 /jerry 값으로 대체됩니다.
응답 코드는 301, 302를 사용할 수 있습니다.

  - matches:
    - path:
        type: PathPrefix
        value: /cat
    filters:
    - type: RequestRedirect
      requestRedirect:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /dog
        statusCode: 302

/cat으로 시작하는 요청을 302 응답 코드와 함께 /dog 경로로 리다이렉트 합니다. filters.requestRedirect.path.type 설정이 ReplacePrefixMatch이므로, /cat의 하위 경로는 유지되며 /cat 값은 /dog 값으로 대체됩니다.
응답 코드는 301, 302를 사용할 수 있습니다.

더욱 자세한 규칙은 아래 이미지를 참고하세요.

NGINX Gateway Fabric 트래픽 라우팅 규칙
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPPathModifier

작성한 yaml 파일을 통해 HTTPRoute 리소스를 생성하고, 요청을 전송해 결과를 확인해 보겠습니다.

$ kubectl apply -f redirect-route.yaml -n demo

httproute.gateway.networking.k8s.io/redirect-route created


$ kubectl get httproutes.gateway.networking.k8s.io -n demo

NAME             HOSTNAMES                     AGE
redirect-route   ["redirect.devopssong.com"]   21s
/tom/cat 요청
$ curl redirect.devopssong.com/tom/cat -L -i

HTTP/1.1 301 Moved Permanently
Server: nginx
Date: Thu, 23 Jan 2025 08:31:25 GMT
Content-Type: text/html
Content-Length: 162
Connection: keep-alive
Location: http://redirect.devopssong.com:80/jerry

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 23 Jan 2025 08:31:25 GMT
Content-Type: text/plain
Content-Length: 165
Connection: keep-alive
Expires: Thu, 23 Jan 2025 08:31:24 GMT
Cache-Control: no-cache

Server address: 10.244.1.6:8080
Server name: nginx-hello-5979b5bb97-bsv5t
Date: 23/Jan/2025:08:31:25 +0000
URI: /jerry
Request ID: 8c0def9a8b1c98785ffe5f45acd5bb27

설정에 따라 /tom으로 시작하는 경로의 요청은 하위 경로가 제거되고 301 응답 코드와 함께 /jerry로 변경되어 리다이렉트 됩니다.

/cat/meow 요청
$ curl redirect.devopssong.com/cat/meow -L -i

HTTP/1.1 302 Moved Temporarily
Server: nginx
Date: Thu, 23 Jan 2025 08:37:44 GMT
Content-Type: text/html
Content-Length: 138
Connection: keep-alive
Location: http://redirect.devopssong.com:80/dog/meow

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 23 Jan 2025 08:37:44 GMT
Content-Type: text/plain
Content-Length: 168
Connection: keep-alive
Expires: Thu, 23 Jan 2025 08:37:43 GMT
Cache-Control: no-cache

Server address: 10.244.1.6:8080
Server name: nginx-hello-5979b5bb97-bsv5t
Date: 23/Jan/2025:08:37:44 +0000
URI: /dog/meow
Request ID: effda0f940d055fa02f806090478a71e

설정에 따라 /cat으로 시작하는 경로의 요청은 하위 경로가 유지되면서 302 응답 코드와 함께 /dog로 변경되어 리다이렉트 됩니다.

3-2. NGINX Gateway Fabric 트래픽 라우팅 – rewrite

NGINX Gateway Fabric 트래픽 라우팅 rewrite
rewrite-route.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rewrite-route
  namespace: demo
spec:
  parentRefs:                            # 연결할 Gateway 리소스 정의
    - name: default-gw
      namespace: nginx-gateway
  hostnames:
  - rewrite.devopssong.com               # hostname 설정
  rules:
  - matches:                             # 규칙 1
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: nginx-hello-svc
      port: 80
  - matches:                             # 규칙 2
    - path:
        type: PathPrefix
        value: /delete
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplaceFullPath
          replaceFullPath: /
    backendRefs:
    - name: nginx-hello-svc
      port: 80
  - matches:                             # 규칙 3
    - path:
        type: PathPrefix
        value: /hello
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /annyeong
    backendRefs:
    - name: nginx-hello-svc
      port: 80

3개의 라우팅 규칙이 정의된 HTTPRoute 리소스입니다. redirect 예제와 같이 ReplaceFullPath, ReplacePrefixMatch를 포함한 3개의 규칙이 정의되어 있습니다.

  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: nginx-hello-svc
      port: 80

/로 시작하는 요청을 nginx-hello-svc의 80번 포트로 라우팅하는 규칙입니다.
matches.path.type을 exact로 변경 시 정확히 일치하는 경로만 라우팅하도록 구성할 수 있습니다.

  - matches:
    - path:
        type: PathPrefix
        value: /delete
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplaceFullPath
          replaceFullPath: /
    backendRefs:
    - name: nginx-hello-svc
      port: 80

/delete로 시작하는 요청을 재작성하여 nginx-hello-svc의 80번 포트로 라우팅하는 규칙입니다.
ReplaceFullPath 설정으로 인해 /delete를 포함한 모든 하위 경로가 /로 재작성됩니다.

  - matches:
    - path:
        type: PathPrefix
        value: /hello
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /annyeong
    backendRefs:
    - name: nginx-hello-svc
      port: 80

/hello로 시작하는 요청을 재작성하여 nginx-hello-svc의 80번 포트로 라우팅하는 규칙입니다.
ReplacePrefixMatch 설정으로 인해 /hello의 하위 경로는 유지하고, /hello는 /annyeong으로 대체됩니다.

더욱 자세한 규칙은 아래 이미지를 참고하세요.

https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPPathModifier

작성한 yaml 파일을 통해 HTTPRoute 리소스를 생성하고, 요청을 전송해 결과를 확인해 보겠습니다.

$ kubectl apply -f rewrite-route.yaml -n demo

httproute.gateway.networking.k8s.io/rewrite-route created


$ kubectl get httproutes.gateway.networking.k8s.io -n demo

NAME             HOSTNAMES                     AGE
rewrite-route    ["rewrite.devopssong.com"]    35s
/delete/all 요청
$ curl rewrite.devopssong.com/delete/all

Server address: 10.244.1.6:8080
Server name: nginx-hello-5979b5bb97-bsv5t
Date: 24/Jan/2025:00:59:41 +0000
URI: /
Request ID: 49e9ea7c2e0fb4782357721b141d82fe

설정에 따라 /delete로 시작하는 경로의 요청은 하위 경로가 제거되고 /로 재작성되어 전달됩니다.

/hello/world 요청
$ curl rewrite.devopssong.com/hello/world

Server address: 10.244.1.6:8080
Server name: nginx-hello-5979b5bb97-bsv5t
Date: 24/Jan/2025:01:00:04 +0000
URI: /annyeong/world
Request ID: 0b19f87a4b1f184cb9d0533a649b3baa

설정에 따라 /hello로 시작하는 경로의 요청은 하위 경로가 유지되면서 /hello가 /annyeong으로 재작성되어 전달됩니다.

4. 결론

이번 포스트에서는 NGINX Gateway Fabric 트래픽 라우팅 설정 중 rewrite, redirect 설정을 알아봤습니다. 먼저 클러스터의 진입점이 되는 Gateway 리소스를 생성하고, Gateway 리소스와 연결되는 라우팅 규칙이 정의된 HTTPRoutes 리소스를 구성했습니다. 각각 rewrite와 redirect 설정을 적용한 HTTPRoute 리소스를 통해 라우팅 규칙을 정의하고, 실제 요청을 전송해 동작을 확인했습니다.

NGINX Gateway Fabric은 Ingress Controller와 유사하게 클러스터 외부의 트래픽을 효과적으로 관리할 수 있는 도구입니다. 특히, NGINX Gateway Fabric은 별도의 Annotation이나 Custom Resource 없이도 Kubernetes Gateway API의 표준 리소스인 Gateway와 HTTPRoute를 사용해 다양한 라우팅 규칙을 손쉽게 구성할 수 있습니다.

NGINX Gateway Fabric에서도 사용할 수 있는 NGINX Plus 전용의 풍부한 메트릭, 실시간 모니터링 대시보드, 그리고 동적 업스트림 구성을 체험해 보고 싶으시다면 NGINX STORE를 통해 문의해 무료로 상업용 NGINX 구독을 체험해 보세요.

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

* indicates required