How to Migrate from NGINX Ingress Controller to NGINX Gateway Fabric (Configmap)

[jinhee6930]

Hi, I’m planning to migrate from the NGINX Ingress Controller to NGINX Gateway Fabric.
When deploying the NGINX Ingress Controller, I previously used the following settings in the ConfigMap:

• allow-snippet-annotations: "true"
• keepalive-timeout: "600"
• ssl-redirect: "false"
• proxy-read-timeout: "600"
• proxy-send-timeout: "600"
• use-forwarded-headers: "true"

To apply equivalent behavior in NGINX Gateway Fabric, I believe the following approach makes sense:

1. allow-snippet-annotations: "true"
   Enable snippet filters when installing NGINX Gateway Fabric via Helm:

helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \
  --create-namespace -n nginx-gateway \
  --set nginxGateway.snippetsFilters.enable=true

2. keepalive-timeout: "600"
   Create a ClientSettingsPolicy and set targetRef to the Gateway.
   Any Routes attached to that Gateway should inherit these ClientSettingsPolicy settings.

spec.keepAlive.timeout.server = "600"

3. ssl-redirect: "false"
   Simply avoid using spec.rules.filters.requestRedirect in the HTTPRoute.

4. proxy-read-timeout: "600" and proxy-send-timeout: "600"
   I’m not sure how to configure equivalents for these timeouts in NGINX Gateway Fabric.
   Are there defaults for these settings in nginx gateway fabric?

5. use-forwarded-headers: "true"
   This is the part I’m most curious about.
   I want to know how to replicate the NGINX Ingress Controller’s use-forwarded-headers: "true" behavior in NGINX Gateway Fabric.
   I need to be able to determine the client's IP through that setting.

I’d appreciate it if someone could confirm whether my understanding of items 1–3 is correct, and also explain how to handle items 4 and 5.

For reference, I know that ClientSettingsPolicy currently supports the following fields:

body.maxSize
body.timeout
keepAlive.requests
keepAlive.time
keepAlive.timeout

Please note that sentences may be strange due to the use of a translator.
Thank you.

[salonichf5]

Hey @jinhee6930, thanks for your interest in NGF!

You’re correct about options 1–3. For option 4–style directives, you can use the snippetsFilter API today to set proxy-read-timeout and proxy-send-timeout.

I’m not sure what your exact header-forwarding use case is, but you might be able to achieve what you want with the XForwardedFor mode.

[jinhee6930]

https://nginxstore.com/blog/kubernetes/nginx-gateway-fabric-rate-limit-%EA%B5%AC%EC%84%B1/

[salonichf5]

@jinhee6930

The only downside is that I would prefer to apply this at the Gateway or GatewayClass level rather than on each HTTPRoute. However, based on the documentation, it seems that SnippetsFilter can only be applied at the HTTPRoute (or GRPCRoute) level.

Agreed — today SnippetsFilter is applied at the HTTPRoute/GRPCRoute level. We’re actively working on Gateway-level support via SnippetsPolicy
.

2. Attach NginxProxy at Gateway level

Yes — you can create an NginxProxy and attach it at the Gateway level. Example:

kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha2
kind: NginxProxy
metadata:
name: ngf-proxy-config-gateway
spec:
config:
rewriteClientIP:
mode: XForwardedFor
trustedAddresses:
- type: CIDR
value: "10.0.0.0/24"
EOF

This looks correct.

3. Gateway and HTTPRoutes in different namespaces

I will be creating only a single Gateway, and multiple applications will share this Gateway… Each HTTPRoute will be created in the application's namespace… I set:
allowedRoutes.namespaces.from: ALL
Do I still need a ReferenceGrant?

No — with allowedRoutes.namespaces.from: ALL, HTTPRoutes from other namespaces can attach to that listener without a ReferenceGrant. That configuration is sufficient.

4. SnippetsFilter example

kubectl apply -f - <<EOF
apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: sp
spec:
  snippets:
    - context: http.server.location
      value: |
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
EOF

This worked for me so hoping it did for you as well :)

Forwarded headers behavior (XForwardedFor)

Does XForwardedFor send X-Forwarded-Proto and X-Forwarded-Host headers “as-is” to pods?

You’re correct: XForwardedFor affects X-Forwarded-For. It does not preserve/forward X-Forwarded-Proto or X-Forwarded-Host “as-is”.

If you want the backend to receive the incoming X-Forwarded-Proto / X-Forwarded-Host values, you can explicitly pass them through via a SnippetsFilter, e.g.:

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: sf
spec:
  snippets:
    - context: http.server.location
      value: |
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        proxy_set_header X-Forwarded-Proto $http_x_forwarded_proto;
        proxy_set_header X-Forwarded-Host  $http_x_forwarded_host;

After applying this, a request like:

curl -v --resolve cafe.example.com:$GW_PORT:$GW_IP \
  -H 'X-Forwarded-For: 1.2.3.4' \
  -H 'X-Forwarded-Proto: https' \
  -H 'X-Forwarded-Host: original.example.com' \
  http://cafe.example.com:$GW_PORT/coffee
* Added cafe.example.com:8080:127.0.0.1 to DNS cache
* Hostname cafe.example.com was found in DNS cache
*   Trying 127.0.0.1:8080...
* Connected to cafe.example.com (127.0.0.1) port 8080
> GET /coffee HTTP/1.1
> Host: cafe.example.com:8080
> User-Agent: curl/8.7.1
Handling connection for 8080
> Accept: */*
> X-Forwarded-For: 1.2.3.4
> X-Forwarded-Proto: https
> X-Forwarded-Host: original.example.com
>
* Request completely sent off
< HTTP/1.1 200 OK
< Server: nginx
< Date: Thu, 18 Dec 2025 21:40:17 GMT
< Content-Type: text/plain
< Content-Length: 195
< Connection: keep-alive
<
remote_addr=10.244.0.33
scheme=http
host=cafe.example.com

http_x_forwarded_for=1.2.3.4, 127.0.0.1
http_x_forwarded_proto=https, http
http_x_forwarded_host=original.example.com, cafe.example.com
* Connection #0 to host cafe.example.com left intact

The snippet above attempts to pass through the incoming X-Forwarded-Proto and X-Forwarded-Host values. Are you trying to achieve that?

[jinhee6930]

I have an additional question regarding point #4.

According to the following documentation:
https://docs.nginx.com/nginx-gateway-fabric/reference/api/#gateway.nginx.org%2fv1alpha1.NginxContext
the snippet context only mentions ngx_http_core_module.
The referenced NGINX documentation is also limited to the core module contexts:
https://nginx.org/en/docs/http/ngx_http_core_module.html#http
https://nginx.org/en/docs/http/ngx_http_core_module.html#server
https://nginx.org/en/docs/http/ngx_http_core_module.html#location

However, the module I want to use is ngx_http_proxy_module.
https://nginx.org/en/docs/http/ngx_http_proxy_module.html

When I apply the SnippetsFilter, I get a 500 error.
If I do not apply the SnippetsFilter, access works correctly.
Does this mean that directives from the ngx_http_proxy_module are not supported in SnippetsFilter?

Using filters

nginx -T

server {
    listen 80;
    listen [::]:80;

    server_name sample-web.xxx.com;
    include /etc/nginx/includes/ClientSettingsPolicy_nginx-gateway_ngf-csp-gateway.conf;
    set_real_ip_from 192.168.0.0/16;
    real_ip_header X-Forwarded-For;

    location ^~ /tea/ {
        return 500 "";
        proxy_http_version 1.1;
    }
    location = /tea {
        return 500 "";
        proxy_http_version 1.1;
    }
    location = / {
        return 404 "";
        proxy_http_version 1.1;
    }
}

Not using filters

nginx -T

server {
    listen 80;
    listen [::]:80;

    server_name sample-web.xxx.com;
    include /etc/nginx/includes/ClientSettingsPolicy_nginx-gateway_ngf-csp-gateway.conf;
    set_real_ip_from 192.168.0.0/16;
    real_ip_header X-Forwarded-For;

    location ^~ /tea/ {
        proxy_http_version 1.1;
        proxy_set_header Host "$gw_api_compliant_host";
        proxy_set_header X-Forwarded-For "$proxy_add_x_forwarded_for";
        proxy_set_header X-Real-IP "$remote_addr";
        proxy_set_header X-Forwarded-Proto "$scheme";
        proxy_set_header X-Forwarded-Host "$host";
        proxy_set_header X-Forwarded-Port "$server_port";
        proxy_set_header Upgrade "$http_upgrade";
        proxy_set_header Connection "$connection_upgrade";
        proxy_pass http://sample-web_svc-coffee_80$request_uri;
    }
    location = /tea {
        proxy_http_version 1.1;
        proxy_set_header Host "$gw_api_compliant_host";
        proxy_set_header X-Forwarded-For "$proxy_add_x_forwarded_for";
        proxy_set_header X-Real-IP "$remote_addr";
        proxy_set_header X-Forwarded-Proto "$scheme";
        proxy_set_header X-Forwarded-Host "$host";
        proxy_set_header X-Forwarded-Port "$server_port";
        proxy_set_header Upgrade "$http_upgrade";
        proxy_set_header Connection "$connection_upgrade";
        proxy_pass http://sample-web_svc-coffee_80$request_uri;
    }
    location = / {
        return 404 "";
        proxy_http_version 1.1;
    }
}

[sjberman]

@jinhee6930 In nginx, directives apply to contexts, which are main, http, http.server, and http.server.location. These are what are specified in the context field, and it's "where" the directives are applied, not "what" directives are applied. Directives from the proxy module are supported, you just have specify those as the value in whichever context they apply, which is probably http.server.location in your case.

[jinhee6930]

@sjberman
Thank you.
Trusting your statement that it should work, I looked for other possible issues.
Upon reviewing it again, I realized that I had not specified a namespace for the SnippetsFilter.
As a result, the SnippetsFilter and the HTTPRoute were in different namespaces,
and I was able to see logs indicating that the SnippetsFilter could not be found from the HTTPRoute.
It seems that the SnippetsFilter and the HTTPRoute need to be in the same namespace.