The following annotations are supported on Ingress resources:
This annotation sets the list of acceptable protocols for the all the rules defined in the Ingress resource. The protocols are used for communication between the Kong Gateway and the external client/user of the Service.
You usually want to set this annotation for the following two use cases:
- You want to redirect HTTP traffic to HTTPS, in which case you will use
konghq.com/protocols: "https"
- You want to define gRPC routing, in which case you should use
konghq.com/protocols: "grpc,grpcs"
This annotation can be applied to an Ingress resource and can take two values:
-
"true": If set to true, the host header of the request will be sent as is to the Service in Kubernetes.
-
"false": If set to false, the host header of the request is not preserved.
Note: The quotes (") around the boolean value are required.
Sample usage:
konghq.com/preserve-host: "true"
This annotation can be applied to an Ingress resource and can take two values:
-
"true": If set to true, the part of the path specified in the Ingress rule
will be stripped out before the request is sent to the Service.
For example, if the Ingress rule has a path of /foo and the HTTP request
that matches the Ingress rule has the path /foo/bar/something, then
the request sent to the Kubernetes service will have the path
/bar/something.
-
"false": If set to false, no path manipulation is performed.
All other values are ignored.
You must use quotes (") around the boolean value.
Sample usage:
konghq.com/strip-path: "true"
This annotation is used to enforce requests to be redirected to the SSL protocol (HTTPS or GRPCS). The default status code for requests that need to be redirected is 302. You can configure this code with the konghq.com/https-redirect-status-code annotation.
By default, Kong Gateway sends HTTP status code 426 for requests that need to be redirected to HTTPS. This can be changed using this annotation.
Acceptable values are:
Any other value will be ignored.
Sample usage:
konghq.com/https-redirect-status-code: "301"
Quotes (") are required around the integer value.
Sets the regex_priority setting to this value on the Kong Gateway Route associated with the Ingress resource. This controls the matching evaluation order for regex-based routes. It accepts any integer value. Routes are evaluated in order of highest priority to lowest.
Sample usage:
konghq.com/regex-priority: "10"
Note: The quotes (") around the integer value are required.
Sets the prefix of the regex matched path to be some string other than /~. In Kong Gateway 3.0 or later, paths with regex match must start with ~, so in ingresses, the /~ prefix is used by default to annotate that the path is using regex match. If the annotation is set, paths with the specified prefix are considered as paths with regex match and will be translated to a ~ started path in Kong Gateway. For example, if an ingress has an annotation of konghq.com/regex-prefix: "/@", paths started with /@ are considered as paths using regex match.
Sets the methods setting on the Kong Gateway Route associated with the Ingress resource. This controls which request methods will match the Route. Any uppercase alpha ASCII string is accepted, though most users will only use standard methods.
Sample usage:
konghq.com/methods: "GET,POST"
Sets the snis match criteria on the Kong Gateway Route associated with this Ingress. When using Route-attached plugins that execute during the certificate phase (for example, Mutual TLS Authentication), the snis annotation allows route matching based on the server name indication information sent in a client’s TLS handshake.
Sample usage:
konghq.com/snis: "foo.example.com, bar.example.com"
Enables or disables request buffering on the Kong Gateway Route associated with this Ingress.
Sample usage:
konghq.com/request-buffering: "false"
Enables or disables response buffering on the Kong Gateway Route associated with this Ingress.
Sample usage:
konghq.com/response-buffering: "false"
Sets additional hosts for Routes created from rules on this Ingress.
Sample usage:
konghq.com/host-aliases: "example.com,example.net"
This annotation applies to all rules equally. An Ingress like this:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: example-ingress
annotations:
konghq.com/host-aliases: "example.com,example.net"
spec:
rules:
- host: "foo.example"
http:
paths:
- pathType: Prefix
path: "/bar"
backend:
service:
name: service1
port:
number: 80
- host: "bar.example"
http:
paths:
- pathType: Prefix
path: "/bar"
backend:
service:
name: service2
port:
number: 80
Results in two Routes:
{"hosts":["foo.example", "example.com", "example.net"], "paths":["/foo"]}
{"hosts":["bar.example", "example.com", "example.net"], "paths":["/bar"]}
To avoid creating overlapping Routes, don’t reuse the same path in multiple rules.
Sets the path handling algorithm, which controls how Kong Gateway combines the Service and Route path fields (the Service’s path annotation value and Ingress rule’s path field) are combined into the path sent upstream.
Sets header values that are required for requests to match rules in an Ingress.
Unlike most annotations, konghq.com/headers.* includes part of the configuration in the annotation name. The string after the . in the annotation name is the header, and the value is a CSV of allowed header values.
For example, setting konghq.com/headers.x-routing: alpha,bravo will only match requests that include an x-routing header whose value is either alpha or bravo.
Sets the separator for the konghq.com/headers.* annotation to be something other than default ,. This is useful when the header values themselves contain commas. For example, setting konghq.com/headers-separator: ";" will allow header values to be separated by ; instead of ,.
Rewrite a URL path. This annotation is a shorthand method of applying a request-transformer plugin with a replace.uri action. It cannot be combined with a konghq.com/plugins annotation that applies a request-transformer plugin as such.
The annotation can rebuild URLs using segments captured from a regular expression path. A $n in the annotation path represents the nth capture group in the Ingress rule path, starting from 1. For example, combining an Ingress rule with path /~/v(.*)/(.*) and a konghq.com/rewrite: /api/$1/foo/svc_$2 would send an upstream request to /api/2/foo/svc_pricing upstream when an inbound request is made to /v2/pricing (the /~ prefix instructs Kong Gateway to treat the path as a regular expression, and isn’t used in the actual request).
Annotations apply at the Ingress level and don’t modify individual rules. As such, this annotation should only be used on Ingresses with a single rule, or on Ingresses whose rules paths all match the rewrite pattern.
Note that this annotation overrides strip_path and Service path annotations. The value of the konghq.com/rewrite annotation will be the entire path sent upstream. You must include path segments you would normally place in a Service konghq.com/path annotation at the start of your konghq.com/rewrite annotation.