NGINX Gateway Fabric: 요청·응답 헤더 수정 가이드

NGINX Gateway Fabric에서는 Gateway API의 HTTPRoute Filter를 사용하여 애플리케이션으로 전달되는 요청 헤더와 클라이언트에 반환되는 응답 헤더를 제어할 수 있습니다.

RequestHeaderModifier는 Backend로 전달되기 전 요청 헤더를 수정하고, ResponseHeaderModifier는 Backend에서 반환된 응답이 클라이언트에 전달되기 전에 응답 헤더를 수정합니다. 이를 통해 애플리케이션 코드를 변경하지 않고도 헤더 추가, 변경, 삭제와 같은 처리를 Gateway 계층에서 수행할 수 있습니다.

이번 포스트에서는 NGINX Gateway Fabric 환경에서 RequestHeaderModifier와 ResponseHeaderModifier를 각각 HTTPRoute에 적용합니다.

먼저 요청 헤더에 대해 set, add, remove 동작을 구성하고 Backend 애플리케이션에서 실제로 전달된 헤더를 확인합니다. 이후 응답 헤더에도 동일한 방식으로 필터를 적용하여 클라이언트에 반환되는 헤더가 어떻게 변경되는지 검증합니다.

이를 통해 Kubernetes Gateway API 환경에서 애플리케이션과 트래픽 처리 정책을 분리하고, HTTPRoute를 기준으로 요청 및 응답 헤더를 제어하는 방법을 확인합니다.

목차

1. 환경 및 버전 정보
2. HTTP Header Modifier란?
3. NGINX Gateway Fabric에서 Header Modifier 구성 방법
4. 공통 Gateway 구성
5. RequestHeaderModifier 실제 구성 예시
5-1. 샘플 애플리케이션 배포
5-2. RequestHeaderModifier 설정
5-3. 테스트 및 결과 확인
6. ResponseHeaderModifier 실제 구성 예시
6-1. 샘플 애플리케이션 배포
6-2. ResponseHeaderModifier 설정
6-3. 테스트 및 결과 확인
7. 결론

1. 환경 및 버전 정보

이번 구성은 다음 환경을 기준으로 진행합니다.

이후 구성에서는 NGINX Gateway Fabric 2.5.0에서 제공하는 Gateway API 기반 RequestHeaderModifier와 ResponseHeaderModifier를 사용하여 HTTPRoute의 요청 및 응답 헤더를 제어합니다.

2. HTTP Header Modifier란?

HTTP Header Modifier는 HTTP 요청과 응답이 처리되는 과정에서 헤더 값을 추가하거나 변경하거나 제거하기 위해 사용하는 기능입니다.

NGINX Gateway Fabric에서 HTTPRoute의 Filter로 Header Modifier를 구성하며, 요청과 응답에 따라 다음 두 가지 방식으로 구분됩니다.

두 Modifier 모두 set, add, remove 동작을 사용할 수 있습니다.

예를 들어 RequestHeaderModifier를 사용하면 Backend 애플리케이션에 전달되기 전에 User-Agent 헤더를 제거하거나 별도의 식별 헤더를 추가할 수 있습니다.

반대로 ResponseHeaderModifier를 사용하면 Backend가 반환한 응답에서 특정 헤더를 제거하거나 클라이언트에 전달할 새로운 응답 헤더를 추가할 수 있습니다.

이러한 처리를 애플리케이션 코드가 아닌 HTTPRoute에서 구성할 수 있기 때문에, 애플리케이션 로직과 트래픽 처리 정책을 분리하여 관리할 수 있습니다.

3. NGINX Gateway Fabric에서 Header Modifier 구성 방법

NGINX Gateway Fabric에서 Header Modifier는 HTTPRoute의 filters 항목에 구성합니다. Gateway를 통해 유입된 요청이 HTTPRoute의 라우팅 규칙과 일치하면, 해당 Rule에 정의된 Header Modifier가 적용된 후 Backend Service로 전달됩니다.

Header Modifier 필터의 기본 개념과 사용 방법은 NGINX Gateway Fabric 공식 문서와 Gateway API 공식 가이드에서도 확인할 수 있습니다.

4. 공통 Gateway 구성

NGINX Gateway Fabric에서 Header Modifier를 적용하려면 먼저 공통 Gateway를 구성해야 합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway
spec:
  gatewayClassName: nginx
  listeners:
  - name: http
    port: 80
    protocol: HTTP

작성한 Manifest를 적용합니다.

$ kubectl apply -f gateway.yaml

Gateway가 정상적으로 생성되었는지 확인합니다.

$ kubectl describe gateways.gateway.networking.k8s.io gateway

정상적으로 처리된 경우 Status의 Conditions에서 Accepted=True와 Programmed=True를 확인할 수 있습니다.

Status:
  Conditions:
    Last Transition Time:  2026-04-02T07:15:18Z
    Message:               The Gateway is accepted
    Observed Generation:   1
    Reason:                Accepted
    Status:                True
    Type:                  Accepted
    Last Transition Time:  2026-04-02T07:15:18Z
    Message:               The Gateway is programmed
    Observed Generation:   1
    Reason:                Programmed
    Status:                True
    Type:                  Programmed

Accepted=True는 Gateway 구성이 NGINX Gateway Fabric에서 정상적으로 수락되었음을 의미하며, Programmed=True는 해당 Gateway 구성이 실제 데이터 플레인에 반영된 상태임을 의미합니다.

이후 RequestHeaderModifier와 ResponseHeaderModifier 예제에서는 모두 이 Gateway의 http Listener에 HTTPRoute를 연결하여 헤더 변경 동작을 확인합니다.

5. RequestHeaderModifier 실제 구성 예시

5-1. 샘플 애플리케이션 배포

RequestHeaderModifier 적용 결과를 확인하기 위해 요청 헤더를 응답 본문에 출력하는 샘플 애플리케이션을 배포합니다.

NGINX Gateway Fabric 2.5.0에서 제공하는 예제 Manifest를 사용합니다.

$ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v2.5.0/examples/http-request-header-filter/headers.yaml

리소스가 생성되었는지 확인합니다.

$ kubectl get pods,svc

정상적으로 배포된 경우 다음과 같이 headers Pod와 Service가 생성됩니다.

NAME                                 READY   STATUS    RESTARTS   AGE
pod/headers-749cbff676-6pxm2         1/1     Running   0          13s
NAME                    TYPE           CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
service/headers         ClusterIP      10.96.147.107   <none>        80/TCP         13s

headers 애플리케이션은 Backend까지 전달된 HTTP 요청 헤더를 응답으로 반환하므로, 이후 RequestHeaderModifier 적용 전후의 헤더 값을 비교하는 데 사용합니다.

5-2. RequestHeaderModifier 설정

앞에서 생성한 headers Service로 요청을 전달하는 HTTPRoute를 생성하고, RequestHeaderModifier Filter를 적용합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: headers
spec:
  parentRefs:
  - name: gateway
    sectionName: http
  hostnames:
  - "echo.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /headers
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        set:
        - name: My-Overwrite-Header
          value: this-is-the-only-value
        add:
        - name: Accept-Encoding
          value: compress
        - name: My-Cool-header
          value: this-is-an-appended-value
        remove:
        - User-Agent
    backendRefs:
    - name: headers
      port: 80

작성한 HTTPRoute를 적용합니다.

$ kubectl apply -f httproute.yaml

RequestHeaderModifier에서는 set, add, remove를 사용하여 요청 헤더를 각각 변경할 수 있습니다.

5-3. 테스트 및 결과 확인

curl을 사용해 Gateway로 요청을 전송하고, RequestHeaderModifier가 적용되기 전과 후의 요청 헤더를 비교합니다.

먼저 다음과 같이 My-Overwrite-Header에 임의의 값을 포함하여 요청을 전송합니다.

$ curl --resolve echo.example.com:30361:172.18.0.2 \
  http://echo.example.com:30361/headers \
  -H "My-Overwrite-Header:dont-see-this"

필터 적용 전에는 Backend에서 다음과 같이 클라이언트가 전달한 헤더를 그대로 확인할 수 있습니다.

Headers:
  header 'Host' is 'echo.example.com:30361'
  header 'X-Forwarded-For' is '172.18.0.1'
  header 'X-Real-IP' is '172.18.0.1'
  header 'X-Forwarded-Proto' is 'http'
  header 'X-Forwarded-Host' is 'echo.example.com'
  header 'X-Forwarded-Port' is '80'
  header 'User-Agent' is 'curl/8.5.0'
  header 'Accept' is '*/*'
  header 'My-Overwrite-Header' is 'dont-see-this'

RequestHeaderModifier를 적용한 뒤 동일한 요청을 전송하면 다음과 같이 헤더가 변경됩니다.

Headers:
  header 'Accept-Encoding' is 'compress'
  header 'My-Cool-header' is 'this-is-an-appended-value'
  header 'My-Overwrite-Header' is 'this-is-the-only-value'
  header 'Host' is 'echo.example.com:30361'
  header 'X-Forwarded-For' is '172.18.0.1'
  header 'X-Real-IP' is '172.18.0.1'
  header 'X-Forwarded-Proto' is 'http'
  header 'X-Forwarded-Host' is 'echo.example.com'
  header 'X-Forwarded-Port' is '80'
  header 'Accept' is '*/*'

변경 결과를 정리하면 다음과 같습니다.

이를 통해 RequestHeaderModifier가 HTTPRoute에서 지정한 set, add, remove 동작에 따라 Backend로 전달되는 요청 헤더를 변경하는 것을 확인할 수 있습니다.

6. ResponseHeaderModifier 실제 구성 예시

6-1. 샘플 애플리케이션 배포

ResponseHeaderModifier 적용 결과를 확인하기 위해 응답 헤더를 반환하는 샘플 애플리케이션을 배포합니다.

NGINX Gateway Fabric 2.5.0에서 제공하는 예제 Manifest를 사용합니다.

$ kubectl apply -f https://raw.githubusercontent.com/nginx/nginx-gateway-fabric/v2.5.0/examples/http-response-header-filter/headers.yaml

리소스가 생성되었는지 확인합니다.

$ kubectl get pods,svc

정상적으로 배포된 경우 headers Pod와 Service가 생성됩니다.

NAME                                 READY   STATUS    RESTARTS   AGE
pod/headers-596c6fd6b-rcvng          1/1     Running   0          6s
NAME                    TYPE           CLUSTER-IP     EXTERNAL-IP   PORT(S)        AGE
service/headers         ClusterIP      10.96.64.37    <none>        80/TCP         6s

해당 애플리케이션은 다음과 같은 응답 헤더를 반환하므로, 이후 ResponseHeaderModifier 적용 전후의 헤더 값을 비교하는 데 사용합니다.

6-2. ResponseHeaderModifier 설정

앞에서 배포한 headers Service로 요청을 전달하는 HTTPRoute를 생성하고, 응답 헤더를 변경하기 위한 ResponseHeaderModifier Filter를 적용합니다.

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: headers
spec:
 parentRefs:
 - name: gateway
   sectionName: http
 hostnames:
 - "cafe.example.com"
 rules:
 - matches:
   - path:
       type: PathPrefix
       value: /headers
   filters:
   - type: ResponseHeaderModifier
     responseHeaderModifier:
       set:
       - name: X-Header-Set
         value: overwritten-value
       add:
       - name: X-Header-Add
         value: this-is-the-appended-value
       remove:
       - X-Header-Remove
   backendRefs:
   - name: headers
     port: 80

작성한 HTTPRoute를 적용합니다.

$ kubectl apply -f httproute.yaml

ResponseHeaderModifier에서는 Backend 애플리케이션이 반환한 응답 헤더에 대해 set, add, remove 동작을 적용할 수 있습니다.

다음 단계에서는 실제 요청을 전송하여 ResponseHeaderModifier 적용 전후의 응답 헤더를 비교합니다.

6-3. 테스트 및 결과 확인

curl을 사용하여 Gateway로 요청을 전송하고, ResponseHeaderModifier 적용 전후의 응답 헤더를 비교합니다.

응답 헤더를 함께 확인하기 위해 -i 옵션을 사용합니다.

$ curl -i --resolve cafe.example.com:30361:172.18.0.2 \
  http://cafe.example.com:30361/headers

필터 적용 전에는 Backend 애플리케이션이 반환한 헤더를 그대로 확인할 수 있습니다.

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 02 Apr 2026 07:38:40 GMT
Content-Type: text/plain
Content-Length: 2
Connection: keep-alive
X-Header-Unmodified: unmodified
X-Header-Add: add-to
X-Header-Set: overwrite
X-Header-Remove: remove
ok

ResponseHeaderModifier를 적용한 뒤 동일한 요청을 전송하면 다음과 같이 응답 헤더가 변경됩니다.

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 02 Apr 2026 07:39:55 GMT
Content-Type: text/plain
Content-Length: 2
Connection: keep-alive
X-Header-Unmodified: unmodified
X-Header-Add: add-to                    
X-Header-Add: this-is-the-appended-value
X-Header-Set: overwritten-value
ok

변경 결과는 다음과 같습니다.

특히 add는 기존 헤더 값을 덮어쓰지 않고 새로운 값을 추가하므로, X-Header-Add가 두 개의 헤더 값으로 반환되는 것을 확인할 수 있습니다.

이를 통해 ResponseHeaderModifier가 Backend에서 반환된 응답을 클라이언트로 전달하기 전에 set, add, remove 설정에 따라 응답 헤더를 변경하는 것을 확인할 수 있습니다.

7. 결론

이번 구성에서는 NGINX Gateway Fabric의 RequestHeaderModifier와 ResponseHeaderModifier를 사용하여 HTTPRoute에서 요청 및 응답 헤더를 제어하는 방법을 확인했습니다.

RequestHeaderModifier를 통해 Backend로 전달되기 전 요청 헤더에 대해 set, add, remove 동작을 적용할 수 있었으며, ResponseHeaderModifier를 통해 Backend가 반환한 응답 헤더도 동일한 방식으로 변경할 수 있었습니다.

이러한 구성을 활용하면 애플리케이션 코드를 직접 수정하지 않고도 Gateway 계층에서 공통 헤더 정책을 적용할 수 있습니다. 예를 들어 내부 식별 헤더 추가, 불필요한 요청 헤더 제거, 응답 헤더 재정의와 같은 처리를 HTTPRoute 설정만으로 관리할 수 있습니다.

특히 여러 애플리케이션에 동일한 헤더 정책을 적용하거나 서비스별로 서로 다른 트래픽 처리 기준이 필요한 환경에서는 애플리케이션 로직과 네트워크 정책을 분리하여 관리할 수 있어 운영 복잡도를 줄이고 정책 일관성을 유지하는 데 유용합니다.

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