You are browsing unreleased documentation. See the latest documentation here.

Rewrite Host and Paths

This guide demonstrates host and path rewrites using Ingress and Service configuration.

Deploy an echo service

To proxy requests, you need an upstream application to send a request to. Deploying this echo server provides a simple application that returns information about the Pod it’s running in:

kubectl apply -f https://docs.konghq.com/assets/kubernetes-ingress-controller/examples/echo-service.yaml

The results should look like this:

service/echo created
deployment.apps/echo created

Add routing configuration

Create routing configuration to proxy /echo requests to the echo server:

echo "
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: echo
  annotations:
    konghq.com/strip-path: 'true'
spec:
  parentRefs:
  - name: kong
  hostnames:
  - 'kong.example'
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /echo
    backendRefs:
    - name: echo
      kind: Service
      port: 1027
" | kubectl apply -f -

echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: echo
  annotations:
    konghq.com/strip-path: 'true'
spec:
  ingressClassName: kong
  rules:
  - host: kong.example
    http:
      paths:
      - path: /echo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 1027
" | kubectl apply -f -

The results should look like this:

httproute.gateway.networking.k8s.io/echo created

ingress.networking.k8s.io/echo created

Test the routing rule:

curl -i -H 'Host:kong.example' $PROXY_IP/echo

The results should look like this:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Content-Length: 140
Connection: keep-alive
Date: Fri, 21 Apr 2023 12:24:55 GMT
X-Kong-Upstream-Latency: 0
X-Kong-Proxy-Latency: 1
Via: kong/3.2.2

Welcome, you are connected to node docker-desktop.
Running on Pod echo-7f87468b8c-tzzv6.
In namespace default.
With IP address 10.1.0.237.
...

If everything is deployed correctly, you should see the above response. This verifies that Kong Gateway can correctly route traffic to an application running inside Kubernetes.

Host manipulation

Kong Ingress Controller provides two annotations for manipulating the Host header. These annotations allow for three different behaviours:

• Preserve the user-provided Host header
• Default to the Host of the upstream service
• Explicitly set the Host header to a known value

Preserve the Host header

Kong Ingress Controller preserves the hostname in the request by default.

$ curl -H 'Host:kong.example' "$PROXY_IP/echo?details=true"

HTTP request details
---------------------
Protocol: HTTP/1.1
Host: kong.example
Method: GET
URL: /?details=true

The Host header in the response matches the Host header in the request.

Use the upstream Host name

You can disable preserve-host if you want the Host header to contain the upstream hostname of your service.

Add the konghq.com/preserve-host annotation to your route:

kubectl patch httproute echo --type merge -p '{"metadata":{"annotations":{"konghq.com/preserve-host":"false"}}}'

kubectl patch ingress echo -p '{"metadata":{"annotations":{"konghq.com/preserve-host":"false"}}}'

The Host header in the response now contains the upstream Host and Port.

HTTP request details
---------------------
Protocol: HTTP/1.1
Host: 192.168.194.11:1027
Method: GET
URL: /?details=true

Set the Host header explicitly

Using Gateway API

You can set the Host header explicitly when using Gateway API’s HTTPRoute with URLRewrite filter’s hostname field. You only need to add a URLRewrite filter to your HTTPRoute rule.

...
filters:
- type: URLRewrite
  urlRewrite:
    hostname: internal.myapp.example.com

Using the konghq.com/host-header annotation

You can set the Host header explicitly if needed by disabling konghq.com/preserve-host and setting the konghq.com/host-header annotation.

1. Add the konghq.com/preserve-host annotation to your Ingress, to disable preserve-host and send the hostname provided in the host-header annotation:

   Gateway API

   Ingress

   kubectl patch httproute echo --type merge -p '{"metadata":{"annotations":{"konghq.com/preserve-host":"false"}}}'

   kubectl patch ingress echo -p '{"metadata":{"annotations":{"konghq.com/preserve-host":"false"}}}'

2. Add the konghq.com/host-header annotation to your Service, which sets the Host header directly:

     $ kubectl patch service echo -p '{"metadata":{"annotations":{"konghq.com/host-header":"internal.myapp.example.com"}}}'
   

3. Make a curl request with a Host header:

    curl -H 'Host:kong.example' "$PROXY_IP/echo?details=true"
   

   The request upstream now uses the header from the host-header annotation:

    HTTP request details
    ---------------------
    Protocol: HTTP/1.1
    Host: internal.myapp.example.com:1027
    Method: GET
    URL: /?details=true
   

Path manipulation

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

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

Rewriting the path

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

...
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

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

HTTP request details
---------------------
Protocol: HTTP/1.1
Host: kong.example
Method: GET
URL: /hello/world?details=true

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 echo --type merge -p '{"metadata":{"annotations":{"konghq.com/strip-path":"true"}}}'

$ kubectl patch ingress echo -p '{"metadata":{"annotations":{"konghq.com/strip-path":"true"}}}'

The request upstream now only contains the path components not in the Ingress rule:

HTTP request details
---------------------
Protocol: HTTP/1.1
Host: kong.example
Method: GET
URL: /?details=true

Prepend a path

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

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

The request upstream now contains a leading /api:

HTTP request details
---------------------
Protocol: HTTP/1.1
Host: kong.example
Method: GET
URL: /api?details=true

strip-path and path can be combined together, with the path component coming first. Adding both annotations send requests for /api/echo.