What Replaces rewrite-target in Envoy Gateway?

In ingress-nginx, nginx.ingress.kubernetes.io/rewrite-target changes the URL path that nginx sends to the backend Service. It does not decide which backend should receive the request; the Ingress path does that.

Path matching and path rewriting solve different problems. A match decides whether /files/hostname belongs to this route. A rewrite decides whether the backend receives /files/hostname, /hostname, /, or something else.

That distinction matters during migration because a route can match successfully and still send the wrong path to the application. An HTTP 200 from Envoy is not enough to prove the rewrite is correct. The backend may successfully answer the wrong path.

The examples reuse the setup from the ingress-nginx to Envoy Gateway migration. ingress-nginx is reachable on 127.0.0.1:18080, and Envoy Gateway is reachable on 127.0.0.1:19080.

The web Service returns the request path it receives as its response body. That makes a bad rewrite easy to see: if the backend receives /$2, the response body is literally /$2.

The generated Gateway is named nginx, but its gatewayClassName must be changed to eg before Envoy Gateway will manage it.

     Client requests /files/hostname
                    ↓
HTTPRoute match accepts or rejects the path
                    ↓
Rewrite sets the path the backend receives
                    ↓
       Service web returns that path

What rewrite-target sends to the backend

The two common rewrite patterns are a fixed target and a regex rewrite that keeps part of the original path. One sends /shop/... to /. The other sends /files/... to /.... The Ingress path decides whether the request matches this rule. rewrite-target decides which path is sent to the backend after that match.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: prefix-rewrite
  namespace: shop
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  ingressClassName: nginx
  rules:
  - host: shop.example.test
    http:
      paths:
      - path: /shop
        pathType: Prefix
        backend:
          service:
            name: web
            port:
              number: 8080
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: regex-rewrite
  namespace: shop
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: nginx
  rules:
  - host: files.example.test
    http:
      paths:
      - path: /files(/|$)(.*)
        pathType: ImplementationSpecific
        backend:
          service:
            name: web
            port:
              number: 8080

Request /shop/hostname on the prefix Ingress. The body is the path web received:

curl -sS --resolve shop.example.test:18080:127.0.0.1 http://shop.example.test:18080/shop/hostname

/

rewrite-target: / replaced the whole path. The suffix hostname is gone. From ingress-nginx 0.22 onward that is the normal behavior unless the target uses a capture group.

The regex Ingress keeps the part after /files/. /$2 puts that remainder back on a leading slash.

A capture group is the part of a regular expression enclosed in parentheses. nginx can reuse the text matched by those groups in rewrite-target as $1, $2, and so on:

• Group 1 is the slash, or the end of the path
• Group 2 is the remainder

curl -sS --resolve files.example.test:18080:127.0.0.1 http://files.example.test:18080/files/hostname

/hostname

Normally, a Kubernetes Prefix path /shop does not match /shopping. Prefix matching is element by element. /shop matches these paths:

• /shop
• /shop/
• /shop/hostname

It does not match /shopping, because shopping is not a child of shop. In this ingress-nginx configuration, rewrite-target causes the controller to render that host's paths as case-insensitive regular-expression locations. /shopping reaches this route for that reason, and the rewrite still replaces the entire path:

curl -sS --resolve shop.example.test:18080:127.0.0.1 http://shop.example.test:18080/shopping

/

The body is /, so /shopping was accepted by this route and then rewritten away.

These paths are also case-insensitive in this ingress-nginx configuration. If rewrite-target or use-regex is used for a host, ingress-nginx applies case-insensitive regex matching to all paths for that host:

• /Shop/hostname matches the same route as /shop/hostname
• /Files/hostname matches the same route as /files/hostname
• /other/hostname matches neither rule, so ingress-nginx returns its default-backend 404

A match is not a rewrite

Keep the two steps separate when you read a generated HTTPRoute.

• The route match decides which requests enter the rule. That includes the path type, the path value, and, for regular expressions, details such as case-insensitive matching with (?i).
• The rewrite runs only after a match. It sets the path the backend Service sees.
• A route can match and still send the wrong path. That is what a literal /$2 looks like.

Core Gateway API gives you two path rewrites on an HTTPRoute URLRewrite filter. For a request to /shop/hostname:

What each field does:

• ReplaceFullPath sets one fixed path. It does not expand $1 or $2.
• ReplacePrefixMatch replaces only the matched prefix and preserves the remaining path.
• Neither performs regex capture-group substitution. Capture groups need an Envoy Gateway HTTPRouteFilter.

HTTPRouteFilter is an Envoy Gateway-specific extension, not a core Gateway API resource. An HTTPRoute attaches it through an ExtensionRef filter.

ReplacePrefixMatch / on /shop/hostname works like this:

   /shop/hostname
          ↓
ReplacePrefixMatch: /
          ↓
      /hostname

What ingress2gateway prints for these paths

Confirm the binary before you read the YAML. The 1.0.0 release I used still prints dev:

ingress2gateway version

ingress2gateway version: dev
Built with Go version: go1.25.8

Print the Gateway API objects for the shop namespace. The important part is the generated rewrite for the regex Ingress. Instead of expanding $2, ingress2gateway 1.0.0 writes it as a fixed ReplaceFullPath value. Warnings go to stderr:

ingress2gateway print --providers=ingress-nginx --namespace=shop --no-color

┌─ WARN  ────────────────────────────────────────
│  Ingress NGINX serves TLS traffic for host "files.example.test" with a self-signed certificate. This behavior will not be translated and the host will not be accessible via HTTPS.
│  source: INGRESS-NGINX
└─
┌─ WARN  ────────────────────────────────────────
│  Ingress NGINX serves TLS traffic for host "shop.example.test" with a self-signed certificate. This behavior will not be translated and the host will not be accessible via HTTPS.
│  source: INGRESS-NGINX
└─
┌─ INFO  ────────────────────────────────────────
│  Using case-insensitive regex path matches. You may want to change this.
│  source: INGRESS-NGINX
│  object: HTTPRoute: shop/regex-rewrite-files-example-test
└─
┌─ INFO  ────────────────────────────────────────
│  Using case-insensitive regex path matches. You may want to change this.
│  source: INGRESS-NGINX
│  object: HTTPRoute: shop/prefix-rewrite-shop-example-test
└─
┌─ WARN  ────────────────────────────────────────
│  Gateway API does not support configuring URL normalization (RFC 3986, Section 6). Please check if this matters for your use case and consult implementation-specific details.
│  source: STANDARD_EMITTER
└─

Do not ignore these messages. They reveal behavior that may change during the migration.

• The TLS warning appears even though these Ingresses have no tls block. ingress-nginx can still serve its default certificate. This page stays on HTTP.
• Both routes, including the prefix that never set use-regex, are case-insensitive regular expressions. The INFO line is telling you to review that.
• Nothing in this report mentions $2.

There is an important difference between the documented behavior and the 1.0.0 release binary:

• The provider documentation says capture-group references such as $2 are unsupported and should be reported.
• In this test, 1.0.0 generated replaceFullPath: /$2 without a capture-group warning.

Verify the generated route itself, not only the warning report.

This exact warning behavior is specific to the 1.0.0 binary I tested. ingress2gateway 1.2.0 includes a fix for regex-rewrite warnings, so newer versions may report this case differently. The provider documentation still says capture-group references should be flagged. Review the warnings from the version you run.

I also ran the same print with --emitter=envoy-gateway. The HTTPRoutes were identical. The Envoy emitter did not add an HTTPRouteFilter.

The generated Gateway uses gatewayClassName: nginx. Change that to eg or Envoy will not program the routes. These are the two HTTPRoutes, with the empty status blocks removed:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-dev
  name: prefix-rewrite-shop-example-test
  namespace: shop
spec:
  hostnames:
  - shop.example.test
  parentRefs:
  - name: nginx
  rules:
  - backendRefs:
    - name: web
      port: 8080
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          replaceFullPath: /
          type: ReplaceFullPath
    matches:
    - path:
        type: RegularExpression
        value: (?i)/shop.*
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  annotations:
    gateway.networking.k8s.io/generator: ingress2gateway-dev
  name: regex-rewrite-files-example-test
  namespace: shop
spec:
  hostnames:
  - files.example.test
  parentRefs:
  - name: nginx
  rules:
  - backendRefs:
    - name: web
      port: 8080
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          replaceFullPath: /$2
          type: ReplaceFullPath
    matches:
    - path:
        type: RegularExpression
        value: (?i)/files(/|$)(.*).*

The fixed rewrite preserves the original nginx behavior. /shop/hostname still arrives as /. The capture-group rewrite does not: ingress2gateway generated ReplaceFullPath: /$2, so Envoy sends the literal string /$2 upstream. Request that URL through Envoy while the generated route is in place:

curl -sS --resolve files.example.test:19080:127.0.0.1 http://files.example.test:19080/files/hostname

/$2

The status is 200. The backend received the characters $2, not the captured suffix. ReplaceFullPath is a fixed string. Envoy does not treat $2 as an nginx capture.

The generated shop expression (?i)/shop.* also matches /shopping and replaces the whole path, so Envoy returns / for that URL, the same body ingress-nginx returned.

Keep the path suffix with ReplacePrefixMatch

Do not use ReplacePrefixMatch merely because you are migrating rewrite-target: /. It changes the behavior.

The difference is easiest to see with the same request, /shop/hostname:

• Original rewrite-target: / sends /
• ReplacePrefixMatch: / sends /hostname

Use ReplacePrefixMatch when the application expects that suffix. Use ReplaceFullPath / when you want the original rewrite-target: / result.

Gateway API PathPrefix matches element by element. /shop matches /shop and /shop/hostname. It does not match /shopping.

Replace the generated shop route with this HTTPRoute. Apply it in the next section, then run the shop checks. That file contains:

• this prefix HTTPRoute
• the capture-group HTTPRouteFilter
• the files HTTPRoute

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: prefix-rewrite-shop-example-test
  namespace: shop
spec:
  hostnames:
  - shop.example.test
  parentRefs:
  - name: nginx
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /shop
    filters:
    - type: URLRewrite
      urlRewrite:
        path:
          type: ReplacePrefixMatch
          replacePrefixMatch: /
    backendRefs:
    - name: web
      port: 8080

Expand capture groups with an Envoy filter

Core Gateway API URLRewrite supports ReplaceFullPath and ReplacePrefixMatch, but it does not support regex capture-group substitution. Envoy Gateway adds that capability through HTTPRouteFilter and ReplaceRegexMatch:

• Core fields: ReplaceFullPath and ReplacePrefixMatch
• Envoy extension: ReplaceRegexMatch on HTTPRouteFilter (gateway.envoyproxy.io/v1alpha1)
• Pattern language: RE2

         ingress-nginx rewrite-target: /$2
                         ↓
HTTPRouteFilter ReplaceRegexMatch, substitution /\1

The two regex patterns use different capture groups, so the group number changes:

• In the original nginx regex, group 1 is (/|$), the slash or the end of the path
• In the original nginx regex, group 2 is the remainder, so the target is $2
• In the new Envoy regex, only the remainder is captured, so it is group 1 and the substitution is \1
• That is not a rule that nginx $2 always becomes Envoy \1

(?i) keeps the case-insensitive match from the INFO line above.

apiVersion: gateway.envoyproxy.io/v1alpha1
kind: HTTPRouteFilter
metadata:
  name: files-capture-rewrite
  namespace: shop
spec:
  urlRewrite:
    path:
      type: ReplaceRegexMatch
      replaceRegexMatch:
        pattern: '(?i)^/files(?:/|$)(.*)$'
        substitution: '/\1'
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: regex-rewrite-files-example-test
  namespace: shop
spec:
  hostnames:
  - files.example.test
  parentRefs:
  - name: nginx
  rules:
  - matches:
    - path:
        type: RegularExpression
        value: (?i)/files(/|$)(.*)
    filters:
    - type: ExtensionRef
      extensionRef:
        group: gateway.envoyproxy.io
        kind: HTTPRouteFilter
        name: files-capture-rewrite
    backendRefs:
    - name: web
      port: 8080

ExtensionRef tells the HTTPRoute to run an implementation-specific filter. Here it points to the Envoy Gateway HTTPRouteFilter named files-capture-rewrite.

ReplaceRegexMatch rewrites the part of the path matched by the regex. Anchoring the pattern with ^ and $ makes this example operate on the whole request path.

Apply the prefix route from the previous section together with this filter and route. The HTTPRoutes already exist, so apply reports configured. The filter is new:

kubectl apply -f shop-rewrite-fix.yaml

httproute.gateway.networking.k8s.io/prefix-rewrite-shop-example-test configured
httproutefilter.gateway.envoyproxy.io/files-capture-rewrite created
httproute.gateway.networking.k8s.io/regex-rewrite-files-example-test configured

Both routes should be accepted, and the references on each route should resolve. Select the conditions by type so the columns do not depend on list order:

kubectl -n shop get httproute -o \
  custom-columns='NAME:.metadata.name,ACCEPTED:.status.parents[*].conditions[?(@.type=="Accepted")].status,RESOLVED:.status.parents[*].conditions[?(@.type=="ResolvedRefs")].status'

NAME                               ACCEPTED   RESOLVED
prefix-rewrite-shop-example-test   True       True
regex-rewrite-files-example-test   True       True

Read the two columns separately:

• Accepted=True means Envoy accepted the HTTPRoute
• ResolvedRefs=True means the references on the route resolved, including the web Service and, on the regex route, the HTTPRouteFilter

/shop/hostname now keeps the suffix. This is ReplacePrefixMatch, not the original rewrite-target: / behavior:

curl -sS --resolve shop.example.test:19080:127.0.0.1 http://shop.example.test:19080/shop/hostname

/hostname

/shopping no longer matches, so Envoy returns an empty 404 instead of the / that ingress-nginx sent:

curl -sS -D - -o /dev/null --resolve shop.example.test:19080:127.0.0.1 http://shop.example.test:19080/shopping

HTTP/1.1 404 Not Found
content-length: 0

/Shop/hostname is a separate miss. PathPrefix is case-sensitive, and this route no longer has the (?i) expression the converter printed. The response is again 404 with content-length: 0.

/files/hostname now matches the nginx result:

curl -sS --resolve files.example.test:19080:127.0.0.1 http://files.example.test:19080/files/hostname

/hostname

/files with nothing after it leaves the capture empty, so the upstream path is /. That is the same body ingress-nginx returned for rewrite-target: /$2 on this URL:

curl -sS --resolve files.example.test:19080:127.0.0.1 http://files.example.test:19080/files

/

/Files/hostname still works because both the match and the filter pattern use (?i):

curl -sS --resolve files.example.test:19080:127.0.0.1 http://files.example.test:19080/Files/hostname

/hostname

Case and path boundaries

The converter kept ingress-nginx's case-insensitive locations by printing (?i). Remove (?i) from the files match, leaving /files(/|$)(.*), and the capital path misses. The body was empty:

curl -sS -w '\n%{http_code}\n' \
  --resolve files.example.test:19080:127.0.0.1 \
  http://files.example.test:19080/Files/hostname

404

The blank line is the empty body, and 404 is the status. Put (?i) back on that match so /Files/hostname returns /hostname again.

Once you replace those ingress-nginx regex locations, these matching differences become important:

• PathPrefix /shop does not match /shopping. The generated expression (?i)/shop.* does. ingress-nginx also matched /shopping in this example because rewrite-target caused the host's paths to be rendered as case-insensitive regex locations.
• PathPrefix and a regular expression without (?i) are case-sensitive. /Shop/hostname then misses.
• A body of / or /$2 with HTTP 200 means the route matched and the rewrite sent that path. The proxy did not miss the request.

The URL-normalization warning is separate. Gateway API does not copy nginx's RFC 3986 normalization. If the app depends on encoded dots or slashes being merged before the rewrite, check those URLs on both controllers. These examples use plain paths only.

Compare ingress-nginx and Envoy rewrite behavior

The edited routes solve two different problems:

• Shop rows use ReplacePrefixMatch, which keeps the suffix. That is not a copy of rewrite-target: /.
• Files rows use ReplaceRegexMatch. That is the copy of rewrite-target: /$2.

An unmatched path on ingress-nginx is the default backend page:

curl -sS -D - --resolve files.example.test:18080:127.0.0.1 http://files.example.test:18080/other/hostname

HTTP/1.1 404 Not Found
Content-Type: text/html
Content-Length: 146

ingress-nginx returns its default HTML 404 page. The same URL on Envoy is an empty 404, because no route matched:

curl -sS -D - -o /dev/null \
  --resolve files.example.test:19080:127.0.0.1 \
  http://files.example.test:19080/other/hostname

HTTP/1.1 404 Not Found
content-length: 0

Troubleshooting

Summary

rewrite-target: / replaces the entire upstream path. For that behavior, ReplaceFullPath: / is the direct Gateway API equivalent. Use ReplacePrefixMatch only when you intentionally want to preserve the suffix.

A target such as /$2 is different because it depends on a regex capture group. Core Gateway API cannot expand that capture. On Envoy Gateway, use an HTTPRouteFilter with ReplaceRegexMatch and a substitution that matches the capture groups in your new regex.

Compare the path the backend actually receives. A 200 response only proves that the route matched and the backend answered. It does not prove the rewrite is correct. Case sensitivity and path-boundary behavior can also change when you replace ingress-nginx regex locations with PathPrefix.

References

• ingress-nginx rewrite-target: community ingress-nginx annotation
• Gateway API HTTP redirects and rewrites: ReplaceFullPath and ReplacePrefixMatch
• Envoy Gateway HTTP URL rewrite (v1.9): HTTPRouteFilter ReplaceRegexMatch
• ingress2gateway ingress-nginx provider (v1.0.0): which annotations the converter translates