Route annotations

Related Documentation
Minimum Version
Kong Operator - 2.4

Kong Operator supports a set of konghq.com/* annotations on HTTPRoute and GRPCRoute resources. Kong Operator propagates these annotations to the Kong Gateway Route that it generates for the resource.

For example:

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: my-route
  namespace: kong
  annotations:
    konghq.com/strip-path: "true"
    konghq.com/request-buffering: "false"
    konghq.com/https-redirect-status-code: "301"
spec:
  parentRefs:
    - name: kong
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /api
      backendRefs:
        - name: my-service
          port: 80

Note: Annotations that configure the upstream connection, such as timeouts and retries, are set on the Service instead. See the Service annotations reference.

Available annotations

Annotation

HTTPRoute

GRPCRoute

Description

konghq.com/strip-path Yes No Strip the matched path prefix from the request before forwarding it upstream
konghq.com/preserve-host Yes Yes Send the client Host header to the upstream service
konghq.com/request-buffering Yes Yes Buffer the request body before proxying it upstream
konghq.com/response-buffering Yes Yes Buffer the response body before sending it to the client
konghq.com/https-redirect-status-code Yes Yes Status code returned when redirecting HTTP requests to HTTPS
konghq.com/path-handling Yes Yes Algorithm used to build the upstream request path

Annotations are optional. A malformed value sets the KongConfigurationValid condition to False on the route, and Kong Operator doesn’t program the route in Kong Gateway.

konghq.com/strip-path

Strips the matched path prefix from the request before forwarding it to the upstream service. For example, if the route matches the /httpbin prefix and the annotation is set to "true", a request to /httpbin/get reaches the upstream service as /get.

Accepted values:

  • "true"
  • "false"

Defaults to "false".

This annotation has no effect on GRPCRoute resources, because Kong Gateway doesn’t accept strip_path on grpc and grpcs Routes.

Sample usage:

konghq.com/strip-path: "true"

konghq.com/preserve-host

Controls whether Kong Gateway sends the Host header of the client request to the upstream service. When set to "false", Kong Gateway sets the Host header to the upstream target, or to the value of the konghq.com/host-header Service annotation.

Accepted values:

  • "true"
  • "false"

Defaults:

  • HTTPRoute: "true"
  • GRPCRoute: the Kong Gateway default, which is false. Kong Operator only sets the field when the annotation is present, so existing routes keep their behavior.

Sample usage:

konghq.com/preserve-host: "false"

konghq.com/request-buffering

Controls whether Kong Gateway buffers the request body before proxying it to the upstream service. Disable buffering to stream large or long-lived request bodies to the upstream service as they arrive.

Accepted values:

  • "true"
  • "false"

Defaults to true.

Sample usage:

konghq.com/request-buffering: "false"

konghq.com/response-buffering

Controls whether Kong Gateway buffers the response body before sending it to the client. Disable buffering to stream large or long-lived responses to the client as they arrive.

Accepted values:

  • "true"
  • "false"

Defaults to true.

Sample usage:

konghq.com/response-buffering: "false"

konghq.com/https-redirect-status-code

Sets the HTTP status code that Kong Gateway returns when a client sends a plain HTTP request that matches a Route that only accepts HTTPS. Attach the route to an HTTPS listener only, for example with sectionName in parentRefs, for the redirect to apply.

Accepted values:

  • "301"
  • "302"
  • "307"
  • "308"
  • "426"

Defaults to 426.

Sample usage:

konghq.com/https-redirect-status-code: "301"

konghq.com/path-handling

Sets the path handling algorithm, which controls how Kong Gateway combines the Service path and the Route path into the path sent upstream.

Accepted values:

  • v0
  • v1

If the annotation isn’t set, Kong Gateway uses its default.

Sample usage:

konghq.com/path-handling: "v1"

Unsupported annotations

Kong Operator doesn’t support the following Route annotations on HTTPRoute and GRPCRoute resources:

  • konghq.com/methods
  • konghq.com/headers.*
  • konghq.com/host-aliases
  • konghq.com/regex-priority
  • konghq.com/protocols
  • konghq.com/snis

Configure the equivalent behavior with Gateway API fields or the Gateway listener instead.

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!