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

Rewrite Annotation

Kong Ingress Controller provides the konghq.com/rewrite annotation to customize the request path before it is sent to the upstream service.

The annotation can be used on Ingress and HTTPRoute resources, and configures a request-transformer plugin within Kong when added to a route.

This definition creates a route that matches the path /users/(\w+) and rewrites it to /requests/users_svc/$1 before sending the request upstream.

Prerequisite

The RewriteURIs feature gate must be enabled.

Rewriting the path

echo "
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: user
  annotations:
    konghq.com/rewrite: '/requests/users_svc/$1'
    konghq.com/strip-path: 'true'
spec:
  parentRefs:
  - name: kong
  rules:
  - matches:
    - path:
        type: RegularExpression
        value: /users/(\w+)
    backendRefs:
    - name: users
      kind: Service
      port: 80
" | kubectl apply -f -

echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: user
  annotations:
    konghq.com/rewrite: '/requests/users_svc/$1'
    konghq.com/strip-path: 'true'
spec:
  ingressClassName: kong
  rules:
  - http:
      paths:
      - path: /~/users/(\w+)
        pathType: ImplementationSpecific
        backend:
          service:
            name: users
            port:
              number: 80
" | kubectl apply -f -

Alternatively, you can define this in a plugin configuration.

plugins:
- name: request-transformer
  service: SERVICE_NAME|ID
  config:
    replace:
      uri: "/requests/users_svc/$(uri_captures[1])"

The $1 in the annotation is expanded to $(uri_captures[1]) in the plugin configuration.

Up to nine capture groups are supported using the konghq.com/rewrite annotation. If you need more than 9 capture groups, create a KongPlugin resource to handle the transformation.