Migrate to NGF Gateway API

Step-by-step migration plan from NGINX Ingress Controller to NGINX Gateway Fabric (NGF) on cegedim.cloud clusters

Context

NGINX Ingress Controller (ingress-nginx) has reached end-of-life. The upstream project no longer receives feature development — security patches only, for a limited period. NGINX Gateway Fabric (NGF) is its replacement on cegedim.cloud, implementing the standard Kubernetes Gateway API.

This guide covers the migration of existing clusters from ingress-nginx to NGF.

Clusters provisioned with Traefik or Istio already support Gateway API natively — this migration plan applies only to clusters using NGINX Ingress Controller (ingress-nginx).

For a full explanation of Gateway API and NGF, see Gateway API.

RFC Process

Migration of existing clusters is handled via two RFCs — not one RFC per cluster:

RFC	Scope	Condition
RFC 1	All non-production clusters	Validates the procedure across all non-prod environments in a single coordinated operation
RFC 2	All production clusters	Applies the validated procedure to all prod clusters after successful non-prod RFC

Current State

Target State

Day 1 — Platform Migration (Zero Customer Impact)

Day 1 is performed by the cegedim.cloud platform team. No changes to F5, no changes to customer Ingress resources, no service interruption.

Traffic Flow During Day 1

Day 1 Steps

1. Deploy NGF via Helm into the nginx-gateway namespace (new namespace — no conflict with existing resources)

2. Create the internal-gateway and external-gateway Gateway resources

3. Create the ReferenceGrant allowing HTTPRoutes in nginx-gateway to target Services in ingress-nginx

4. nginx-int releases hostPorts 80/443 — internal-gateway DaemonSet takes them

5. nginx-ext releases hostPorts 8081/8443 — external-gateway DaemonSet takes them

6. Create catch-all HTTPRoutes: internal-gateway → nginx-int ClusterIP, external-gateway → nginx-ext ClusterIP

7. F5 config: no change. Customers: no impact. Traffic flows NGF → nginx-int/nginx-ext → backends, unchanged.

TLSRoute is not supported in NGF (experimental channel, CRD not installed). Customers whose F5 does not terminate SSL and require raw TLS passthrough should open an ITCare ticket to discuss their specific case before RFC 1.

Day 2+ — Application Migration Playbook

After Day 1, application teams can migrate their services independently, in any order, at their own pace. There is no deadline — legacy Ingress resources continue to work through the catch-all route until explicitly migrated.

Per-Service Migration Steps

For each service:

1. Create an HTTPRoute with the exact hostname pointing directly to the backend Service

2. Delete the corresponding Ingress resource

3. Verify — hostname specificity ensures the new route takes precedence over the catch-all automatically

Example: Simple Service Migration

# Before (Ingress)
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app1
  namespace: app1-ns
spec:
  rules:
  - host: app1.internal.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: app1-service
            port:
              number: 8080

# After (HTTPRoute)
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app1
  namespace: app1-ns
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - "app1.internal.example.com"       # exact match -> beats catch-all automatically
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: app1-service
      port: 8080

Example: Partial Path Migration

Migrate a subset of paths for one hostname while the rest still flows through nginx-int via the catch-all:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app1-partial
  namespace: app1-ns
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - "app1.internal.example.com"
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /api/v2                # migrated path -> new backend
    backendRefs:
    - name: app1-v2-service
      port: 8080
  # Other paths for app1.internal.example.com still fall through to nginx-int via catch-all

Annotation Migration Reference

NGINX Ingress Annotation	NGF Equivalent	Effort
rewrite-target: /$2 (prefix strip)	URLRewrite + ReplacePrefixMatch	Low
rewrite-target: /static-path	URLRewrite + ReplaceFullPath	Low
use-regex: "true"	path.type: RegularExpression	Low
server-snippet / configuration-snippet (headers)	ResponseHeaderModifier filter	Low
permanent-redirect	RequestRedirect filter (statusCode: 301)	Low
proxy-read/send/connect-timeout	UpstreamSettingsPolicy	Low
proxy-body-size	ClientSettingsPolicy	Low
x-forwarded-prefix	RequestHeaderModifier filter	Low
auth-type: basic	AuthenticationFilter (alpha)	Medium
whitelist-source-range	SnippetsFilter (alpha)	Medium
Rate limiting (limit-rps / limit-rpm)	RateLimitPolicy (alpha)	Medium
use-regex + capture group rewrite	SnippetsFilter (alpha) + rewrite directive	Medium

Alpha features (AuthenticationFilter, RateLimitPolicy, SnippetsFilter) are functional but carry API stability risk on NGF upgrades. SnippetsFilter is disabled by default and must be enabled by the platform team. Contact ITCare if your application uses these patterns.

Use Case Examples

The following 15 use cases were validated on cegedim.cloud clusters. Each shows the original NGINX Ingress resource and its NGF equivalent.

Use cases marked (alpha) rely on NGF-specific resources (SnippetsFilter, AuthenticationFilter, RateLimitPolicy, ClientSettingsPolicy) whose API may change on NGF upgrades. SnippetsFilter is disabled by default — open an ITCare ticket to request it.

01 — Prefix strip

Strip a path prefix before forwarding to the backend (e.g. /myapp/hello → /hello).

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: prefix-rewrite
  annotations:
    nginx.ingress.kubernetes.io/use-regex: "true"
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /myapp(/|$)(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: prefix-rewrite
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /myapp
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /
    backendRefs:
    - name: my-service
      port: 80

02 — Static path rewrite

Replace the entire request path with a fixed value (/probe → /health).

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: static-rewrite
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /health
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /probe
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: static-rewrite
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /probe
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplaceFullPath
          replaceFullPath: /health
    backendRefs:
    - name: my-service
      port: 80

03 — Regex path match

Match paths using a regular expression (e.g. /api/v1/resource and /api/v42/resource match; /api/vX/resource does not).

RegularExpression is a Gateway API extended feature. When used with NGF, add sectionName: http to the parentRef to avoid an InvalidListener condition on the HTTPS listener.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: regex-match
  annotations:
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /api/v[0-9]+/resource
        pathType: ImplementationSpecific
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: regex-match
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
    sectionName: http
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: RegularExpression
        value: "/api/v[0-9]+/resource"
    backendRefs:
    - name: my-service
      port: 80

04 — Security response headers

Inject standard security headers (Content-Security-Policy, X-Content-Type-Options, X-XSS-Protection) on every response.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: security-headers
  annotations:
    nginx.ingress.kubernetes.io/server-snippet: |
      add_header Content-Security-Policy "default-src 'self'" always;
      add_header X-Content-Type-Options "nosniff" always;
      add_header X-XSS-Protection "1; mode=block" always;
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: security-headers
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: ResponseHeaderModifier
      responseHeaderModifier:
        set:
        - name: Content-Security-Policy
          value: "default-src 'self'"
        - name: X-Content-Type-Options
          value: nosniff
        - name: X-XSS-Protection
          value: "1; mode=block"
    backendRefs:
    - name: my-service
      port: 80

05 — Basic authentication (alpha)

Protect a route with HTTP Basic Auth backed by an htpasswd secret.

The NGF secret type is nginx.org/htpasswd, different from the standard Opaque secret used by NGINX Ingress Controller.

kubectl create secret generic basic-auth-secret \
  --type=nginx.org/htpasswd \
  --from-literal=auth=$(htpasswd -nb admin password) \
 

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: basic-auth
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: basic-auth-secret
    nginx.ingress.kubernetes.io/auth-realm: "Protected Area"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.nginx.org/v1alpha1
kind: AuthenticationFilter
metadata:
  name: basic-auth
spec:
  type: Basic
  basic:
    realm: "Protected Area"
    secretRef:
      name: basic-auth-secret
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: basic-auth
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: ExtensionRef
      extensionRef:
        group: gateway.nginx.org
        kind: AuthenticationFilter
        name: basic-auth
    backendRefs:
    - name: my-service
      port: 80

06 — IP allowlist (alpha)

Allow requests only from specific CIDR ranges; deny all others with 403.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ip-allowlist
  annotations:
    nginx.ingress.kubernetes.io/whitelist-source-range: "10.26.0.0/16,192.168.0.0/16"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: ip-allowlist
spec:
  snippets:
  - context: http.server.location
    value: |
      allow 10.26.0.0/16;
      allow 192.168.0.0/16;
      deny all;
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ip-allowlist
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: ExtensionRef
      extensionRef:
        group: gateway.nginx.org
        kind: SnippetsFilter
        name: ip-allowlist
    backendRefs:
    - name: my-service
      port: 80

07 — Permanent redirect

Redirect a path to a different host and/or path with HTTP 301.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: redirect
  annotations:
    nginx.ingress.kubernetes.io/permanent-redirect: "https://new.example.com/landing"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /old-path
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: redirect
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /old-path
    filters:
    - type: RequestRedirect
      requestRedirect:
        scheme: https
        hostname: new.example.com
        path:
          type: ReplaceFullPath
          replaceFullPath: /landing
        statusCode: 301

08 — Proxy timeouts (alpha)

Set NGINX proxy timeouts per route: connect, send, and read.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: timeouts
  annotations:
    nginx.ingress.kubernetes.io/proxy-connect-timeout: "10"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "60"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: timeouts
spec:
  snippets:
  - context: http.server.location
    value: |
      proxy_connect_timeout 10s;
      proxy_send_timeout    60s;
      proxy_read_timeout    120s;
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: timeouts
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: ExtensionRef
      extensionRef:
        group: gateway.nginx.org
        kind: SnippetsFilter
        name: timeouts
    backendRefs:
    - name: my-service
      port: 80

09 — Request body size limit (alpha)

Limit the maximum request body size (e.g. reject uploads above 700 KB with 413).

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: body-size
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "700k"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /upload
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: body-size
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /upload
    backendRefs:
    - name: my-service
      port: 80
---
apiVersion: gateway.nginx.org/v1alpha1
kind: ClientSettingsPolicy
metadata:
  name: body-size
spec:
  targetRef:
    group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: body-size
  body:
    maxSize: 700k

10 — Rate limiting (alpha)

Limit requests per client IP. The NGF RateLimitPolicy uses NGINX limit_req semantics — the reject code is configurable (503 on ingress-nginx by default, 429 with NGF).

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: rate-limit
  annotations:
    nginx.ingress.kubernetes.io/limit-rps: "1"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.nginx.org/v1alpha1
kind: RateLimitPolicy
metadata:
  name: rate-limit
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: HTTPRoute
    name: rate-limit
  rateLimit:
    local:
      rules:
      - zoneSize: 10m
        key: "$binary_remote_addr"
        rate: 1r/s
    rejectCode: 429
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: rate-limit
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: my-service
      port: 80

11 — Regex capture group rewrite (alpha)

Reorder path segments using regex capture groups (e.g. /foo/status/bar → /bar/foo). There is no standard Gateway API equivalent — SnippetsFilter is required.

This is the most complex migration case. The SnippetsFilter injects a location ~ /status/ block into the NGINX server context. The HTTPRoute must use path.type: RegularExpression (not PathPrefix /) to avoid a location ^~ block that would prevent the injected regex location from matching. Replace my-app_my-service_80 with the actual NGF upstream name: {namespace}_{service-name}_{port}.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: regex-capture-rewrite
  annotations:
    nginx.ingress.kubernetes.io/use-regex: "true"
    nginx.ingress.kubernetes.io/rewrite-target: /$2/$1
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /(.+)/status/(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: regex-swap-rewrite
spec:
  snippets:
  - context: http.server
    value: |
      location ~ /status/ {
          rewrite ^/(.+)/status/(.*)$ /$2/$1 break;
          return 400;
          proxy_pass http://my-app_my-service_80;
      }
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: regex-swap-rewrite
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
    sectionName: http
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: RegularExpression
        value: /.*
    filters:
    - type: ExtensionRef
      extensionRef:
        group: gateway.nginx.org
        kind: SnippetsFilter
        name: regex-swap-rewrite
    backendRefs:
    - name: my-service
      port: 80

12 — Dynamic headers via NGINX variables (alpha)

Inject headers using NGINX runtime variables ($host, $request_id, etc.) in responses to the client or in requests to the backend. The standard ResponseHeaderModifier and RequestHeaderModifier filters only support static values — use SnippetsFilter for dynamic ones.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: escape-hatch
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      add_header X-Custom-Host $host always;
      add_header X-Custom-RequestID $request_id always;
      proxy_set_header X-Custom-Host $host;
      proxy_set_header X-Custom-RequestID $request_id;
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: escape-hatch
spec:
  snippets:
  - context: http.server.location
    value: |
      add_header X-Custom-Host $host always;
      add_header X-Custom-RequestID $request_id always;
      proxy_set_header X-Custom-Host $host;
      proxy_set_header X-Custom-RequestID $request_id;
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: escape-hatch
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: ExtensionRef
      extensionRef:
        group: gateway.nginx.org
        kind: SnippetsFilter
        name: escape-hatch
    backendRefs:
    - name: my-service
      port: 80

13 — Retry on upstream failure (alpha)

Transparently retry failed requests on another pod before returning an error to the client. Prevents a single unhealthy pod from causing 502 errors when healthy replicas are available.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: next-upstream
  annotations:
    nginx.ingress.kubernetes.io/proxy-next-upstream: "error timeout"
    nginx.ingress.kubernetes.io/proxy-next-upstream-tries: "3"
    nginx.ingress.kubernetes.io/proxy-next-upstream-timeout: "0"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: next-upstream
spec:
  snippets:
  - context: http.server.location
    value: |
      proxy_next_upstream error timeout;
      proxy_next_upstream_tries 3;
      proxy_next_upstream_timeout 0;
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: next-upstream
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: ExtensionRef
      extensionRef:
        group: gateway.nginx.org
        kind: SnippetsFilter
        name: next-upstream
    backendRefs:
    - name: my-service
      port: 80

14 — X-Forwarded-Prefix

Inform the backend of the public path prefix under which it is mounted. Required when the gateway strips a prefix and the backend generates absolute URLs or redirects (Spring Boot, Django, etc.).

The nginx.ingress.kubernetes.io/x-forwarded-prefix annotation is unreliable since ingress-nginx v1.12+. Use configuration-snippet with proxy_set_header directly, as shown below.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: x-forwarded-prefix
  annotations:
    nginx.ingress.kubernetes.io/configuration-snippet: |
      proxy_set_header X-Forwarded-Prefix "/myapp";
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /myapp
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: x-forwarded-prefix
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /myapp
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        set:
        - name: X-Forwarded-Prefix
          value: /myapp
    backendRefs:
    - name: my-service
      port: 80

15 — Real client IP from F5 (alpha)

Restore the actual client IP from the X-Forwarded-For header set by the F5 load balancer. Without this, backends see F5's IP on every request.

As an alternative to SnippetsFilter (per-route scope), the platform team can configure real IP rewriting globally for all routes via an NginxProxy resource. Contact ITCare if a cluster-wide configuration is preferable.

NGINX Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: use-forwarded-headers
  annotations:
    nginx.ingress.kubernetes.io/use-forwarded-headers: "true"
    nginx.ingress.kubernetes.io/proxy-real-ip-cidr: "10.0.0.0/8"
spec:
  ingressClassName: nginx
  rules:
  - host: myapp.mycluster.ccs.cegedim.cloud
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-service
            port:
              number: 80

NGF (HTTPRoute)

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: use-forwarded-headers
spec:
  snippets:
  - context: http.server
    value: |
      real_ip_header X-Forwarded-For;
      real_ip_recursive on;
      set_real_ip_from 10.0.0.0/8;
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: use-forwarded-headers
spec:
  parentRefs:
  - name: internal-gateway
    namespace: nginx-gateway
  hostnames:
  - myapp.mycluster.ccs.cegedim.cloud
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /
    filters:
    - type: ExtensionRef
      extensionRef:
        group: gateway.nginx.org
        kind: SnippetsFilter
        name: use-forwarded-headers
    backendRefs:
    - name: my-service
      port: 80

Summary Timeline

Phase	Who	Description
Day 1	Platform team	NGF deployed; nginx-int/nginx-ext release hostPorts; catch-all HTTPRoutes created; F5 unchanged; zero customer impact
Day 2+	Application teams	Teams migrate Ingress resources to HTTPRoutes, service by service, in any order
Day N	Platform team	nginx-int decommissioned once all internal traffic is fully migrated to NGF HTTPRoutes
Day M	Platform team	nginx-ext decommissioned once all external traffic is fully migrated to NGF HTTPRoutes

Support

To request migration assistance or report a compatibility issue, open a ticket via ITCare with the label Gateway API Migration.

For annotation-by-annotation migration guidance beyond the table above, refer to the full NGINX Gateway Fabric migration documentation:

https://docs.nginx.com/nginx-gateway-fabric/how-to/migrate-from-nginx-ingress/docs.nginx.com