Rewriting paths

Users have the following options to modify the default path handling behavior:

• Remove the path prefix using strip-path
• v3.2+ Rewrite using Gateway API’s URLRewrite filter
• Rewrite using regular expressions
• Add a path prefix using the path annotation

Strip the path

This is the default behavior of Kong Ingress Controller. Set konghq.com/strip-path="false" to disable this behavior

Add the konghq.com/strip-path annotation to your Ingress, which strips the path component of the Route/Ingress, leaving the remainder of the path at the root:

kubectl patch httproute NAME --type merge \
  -p '{"metadata":{"annotations":{"konghq.com/strip-path":"true"}}}'

kubectl patch ingress NAME --type merge \
  -p '{"metadata":{"annotations":{"konghq.com/strip-path":"true"}}}'

If your routing rule contains path: /user, a request to GET /user/details will have the routing rule path stripped leaving GET /details in the request to the upstream.

Rewriting the path

In many cases, stripping the path prefix is not enough. Internal systems contain URLs that are not suitable for external publication. Kong Ingress Controller can transparently rewrite the URLs to provide a user friendly interface to external consumers.

Using the konghq.com/rewrite annotation

This feature requires the RewriteURIs feature gate to be activated and only works with Ingress resources

Add the konghq.com/rewrite annotation to your Ingress, which allows you set a specific path for the upstream request. Any regex matches defined in your Route definition are usable (see the annotation documentation for more information):

kubectl patch ingress NAME --type merge \
  -p '{"metadata":{"annotations":{"konghq.com/rewrite":"/hello/world"}}}'

Any query string parameters in the incoming request are left untouched.

You can use the konghq.com/rewrite annotation with regular expressions to capture input parameters and pass them to the upstream. See the rewriting paths with the konghq.com/rewrite annotation how-to for more details.

Using Gateway API filters

You can replace the full path for a request by adding the URLRewrite filter with path.replaceFullPath to your HTTPRoute.

...
filters:
- type: URLRewrite
  urlRewrite:
    path:
      type: ReplaceFullPath
      replaceFullPath: /rewritten-path

Alternatively, you can add the URLRewrite filter with path.replacePrefixMatch to your HTTPRoute rule to rewrite the path prefix.

See the URLRewrite filter documentation for more information.

...
rules:
  - matches:
      - path:
          type: PathPrefix # Only PathPrefix path type is supported with URLRewrite filter using path.type == ReplacePrefixMatch.
          value: /old-prefix
    filters:
     - type: URLRewrite
       urlRewrite:
         path:
           type: ReplacePrefixMatch
           replacePrefixMatch: /new-prefix

Prepend a path

Add the konghq.com/path annotation to your Service, which prepends that value to the upstream path:

kubectl patch service NAME -p '{"metadata":{"annotations":{"konghq.com/path":"/api"}}}'