You are browsing documentation for an older version. See the latest documentation here.

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

Rewriting the host

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 ingress echo -p '{"metadata":{"annotations":{"konghq.com/preserve-host":"false"}}}'

kubectl patch httproute echo --type merge -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

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:

   Ingress

   Gateway API

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

   kubectl patch httproute echo --type merge -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
   

Rewriting the path

There are three options to rewrite the default path handling behavior:

• Rewrite using regular expressions
• Remove the path prefix using strip-path
• Add a path prefix using the path annotation

Rewrite using regular expressions

This feature is available from Kong Ingress Controller 2.12 and requires the RewriteURIs feature gate to be activated.

Add the konghq.com/rewrite annotation to your Ingress, 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 echo -p '{"metadata":{"annotations":{"konghq.com/rewrite":"/hello/world"}}}'

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

The request upstream now contains the value of the rewrite annotation:

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

$ kubectl patch httproute echo --type merge -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.