このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Kong Ingress Controller annotations
The Kong Ingress Controller supports the following annotations on various resources:
Ingress resource
Following annotations are supported on Ingress resources:
Annotation name | Description |
---|---|
REQUIRED kubernetes.io/ingress.class
|
Restrict the Ingress rules that Kong should satisfy |
konghq.com/plugins |
Run plugins for specific Ingress |
konghq.com/protocols |
Set protocols to handle for each Ingress resource |
konghq.com/preserve-host |
Pass the host header as is to the upstream service |
konghq.com/strip-path |
Strip the path defined in Ingress resource and then forward the request to the upstream service |
ingress.kubernetes.io/force-ssl-redirect |
Force non-SSL requests to be redirected to SSL. |
konghq.com/https-redirect-status-code |
Set the HTTPS redirect status code to use when an HTTP request is received |
konghq.com/regex-priority |
Set the route’s regex priority |
konghq.com/regex-prefix |
Prefix of path to annotate that the path is a regex match, other than default /~
|
konghq.com/methods |
Set methods matched by this Ingress |
konghq.com/snis |
Set SNI criteria for routes created from this Ingress |
konghq.com/request-buffering |
Set request buffering on routes created from this Ingress |
konghq.com/response-buffering |
Set response buffering on routes created from this Ingress |
konghq.com/host-aliases |
Additional hosts for routes created from this Ingress’s rules |
konghq.com/override |
(Deprecated, replace with per-setting annotations) Control other routing attributes with a KongIngress resource |
konghq.com/path-handling |
Sets the path handling algorithm |
konghq.com/headers.* |
Set header values required to match rules in this Ingress |
kubernetes.io/ingress.class
is normally required, and its value should match
the value of the --ingress-class
controller argument (kong
by default).
Service resource
Following annotations are supported on Service resources:
Annotation name | Description |
---|---|
konghq.com/plugins |
Run plugins for a specific Service |
konghq.com/protocol |
Set protocol Kong should use to talk to a Kubernetes service |
konghq.com/path |
HTTP Path that is always prepended to each request that is forwarded to a Kubernetes service |
konghq.com/client-cert |
Client certificate and key pair Kong should use to authenticate itself to a specific Kubernetes service |
konghq.com/host-header |
Set the value sent in the Host header when proxying requests upstream |
ingress.kubernetes.io/service-upstream |
Offload load-balancing to kube-proxy or sidecar |
konghq.com/override |
(Deprecated for non-upstream fields, replace with per-setting annotations) Control load balancing behavior with a KongIngress resource |
konghq.com/connect-timeout |
Set the timeout for completing a TCP connection |
konghq.com/read-timeout |
Set the timeout for receiving an HTTP response after sending a request |
konghq.com/write-timeout |
Set the timeout for writing data |
konghq.com/retries |
Set the number of times to retry requests that failed |
KongConsumer resource
Following annotations are supported on KongConsumer resources:
Annotation name | Description |
---|---|
REQUIRED kubernetes.io/ingress.class
|
Restrict the KongConsumers that a controller should satisfy |
konghq.com/plugins |
Run plugins for a specific consumer |
kubernetes.io/ingress.class
is normally required, and its value should match
the value of the --ingress-class
controller argument (kong
by default).
Setting the --process-classless-kong-consumer
controller flag removes that requirement:
when enabled, the controller will process KongConsumers with no
kubernetes.io/ingress.class
annotation. Recommended best practice is to set
the annotation and leave this flag disabled; the flag is primarily intended for
older configurations, as controller versions prior to 0.10 processed classless
KongConsumer resources by default.
Annotations
kubernetes.io/ingress.class
Kubernetes versions after 1.18 introduced the new
ingressClassName
field to the Ingress spec and deprecated thekubernetes.io/ingress.class
annotation. Ingress resources should now use theingressClassName
field. Kong resources (KongConsumer, TCPIngress, etc.) still use thekubernetes.io/ingress.class
annotation.
If you have multiple Ingress controllers in a single cluster,
you can pick one by specifying the ingress.class
annotation.
Following is an example of
creating an Ingress with an annotation:
apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
name: test-1
annotations:
kubernetes.io/ingress.class: "gce"
spec:
rules:
- host: example.com
http:
paths:
- path: /test1
backend:
serviceName: echo
servicePort: 80
This will target the GCE controller, forcing the Kong Ingress Controller to ignore it.
On the other hand, an annotation such as
metadata:
name: test-1
annotations:
kubernetes.io/ingress.class: "kong"
will target the Kong Ingress Controller, forcing the GCE controller to ignore it.
With the ingressClassName
field instead of the annotation:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: test-1
spec:
ingressClassName: kong
rules:
- host: example.com
http:
paths:
- path: /test1
backend:
serviceName: echo
servicePort: 80
The following resources require this annotation by default:
- Ingress
- KongConsumer
- TCPIngress
- UDPIngress
- KongClusterPlugin
- Secret resources with the
ca-cert
label
The ingress class used by the Kong Ingress Controller to filter Ingress
resources can be changed using the CONTROLLER_INGRESS_CLASS
environment variable.
spec:
template:
spec:
containers:
- name: kong-ingress-internal-controller
env:
- name: CONTROLLER_INGRESS_CLASS
value: kong-internal
Multiple unrelated Kong Ingress Controllers
In some deployments, one might use multiple Kong Ingress Controllers
in the same Kubernetes cluster
(e.g. one which serves public traffic, one which serves “internal” traffic).
For such deployments, please ensure that in addition to different
ingress-class
, the --election-id
is also different.
In such deployments, kubernetes.io/ingress.class
annotation can be used on the
following custom resources as well:
- KongPlugin: To configure (global) plugins only in one of the Kong clusters.
- KongConsumer: To create different consumers in different Kong clusters.
konghq.com/plugins
Available since controller 0.8
Kong’s power comes from its plugin architecture, where plugins can modify the request and response or impose certain policies on the requests as they are proxied to your service.
With the Kong Ingress Controller, plugins can be configured by creating KongPlugin Custom Resources and then associating them with an Ingress, Service, KongConsumer or a combination of those.
Following is an example of how to use the annotation:
konghq.com/plugins: high-rate-limit, docs-site-cors
Here, high-rate-limit
and docs-site-cors
are the names of the KongPlugin resources which
should be to be applied to the Ingress rules defined in the
Ingress resource on which the annotation is being applied.
This annotation can also be applied to a Service resource in Kubernetes, which will result in the plugin being executed at Service-level in Kong, meaning the plugin will be executed for every request that is proxied, no matter which Route it came from.
This annotation can also be applied to a KongConsumer resource, which results in plugin being executed whenever the specific consumer is accessing any of the defined APIs.
Finally, this annotation can also be applied on a combination of the following resources:
-
Ingress and KongConsumer
If an Ingress resource and a KongConsumer resource share a plugin in the
konghq.com/plugins
annotation then the plugin will be created for the combination of those to resources in Kong. - Service and KongConsumer Same as the above case, if you would like to give a specific consumer or client of your service some special treatment, you can do so by applying the same annotation to both of the resources.
Please follow the Using the KongPlugin resource guide for details on how this annotation can be used.
konghq.com/path
Available since controller 0.8
This annotation can be used on a Service resource only. This annotation can be used to prepend an HTTP path of a request, before the request is forwarded.
For example, if the annotation konghq.com/path: "/baz"
is applied to a
Kubernetes Service billings
, then any request that is routed to the
billings
service will be prepended with /baz
HTTP path. If the
request contains /foo/something
as the path, then the service will
receive an HTTP request with path set as /baz/foo/something
.
konghq.com/strip-path
Available since controller 0.8
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.
Please note the quotes ("
) around the boolean value.
Sample usage:
konghq.com/strip-path: "true"
konghq.com/preserve-host
Available since controller 0.8
This annotation can be applied to an Ingress resource and can take two values:
-
"true"
: If set to true, thehost
header of the request will be sent as is to the Service in Kubernetes. -
"false"
: If set to false, thehost
header of the request is not preserved.
Please note the quotes ("
) around the boolean value.
Sample usage:
konghq.com/preserve-host: "true"
ingress.kubernetes.io/force-ssl-redirect
Available since controller 0.10
This annotation is used to enforce requests to be redirected to SSL protocol
(HTTPS or GRPCS). The default status code for requests that need to be
redirected is 302. This code can be configured by annotation konghq.com/https-redirect-status-code
[#konghqcomhttps-redirect-status-code].
konghq.com/https-redirect-status-code
Available since controller 0.8
By default, Kong sends HTTP Status Code 426 for requests that need to be redirected to HTTPS. This can be changed using this annotations. Acceptable values are:
- 301
- 302
- 307
- 308
- 426
Any other value will be ignored.
Sample usage:
konghq.com/https-redirect-status-code: "301"
Please note the quotes ("
) around the integer value.
konghq.com/regex-priority
Available since controller 0.9
Sets the regex_priority
setting to this value on the Kong 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"
Please note the quotes ("
) around the integer value.
konghq.com/methods
Available since controller 0.9
Sets the methods
setting on the Kong 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 use only
standard methods.
Sample usage:
konghq.com/methods: "GET,POST"
konghq.com/snis
Available since controller 1.1
Sets the snis
match criteria on the Kong 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"
konghq.com/request-buffering
Available since controller 1.2
Enables or disables request buffering on the Kong route associated with this Ingress.
Sample usage:
konghq.com/request-buffering: "false"
konghq.com/response-buffering
Available since controller 1.2
Enables or disables response buffering on the Kong route associated with this Ingress.
Sample usage:
konghq.com/response-buffering: "false"
konghq.com/host-aliases
Available since controller 1.3
Set 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.
konghq.com/override
Available since controller 0.8
As of version 2.8, KongIngress sections other than
upstream
are deprecated. All settings in theproxy
androute
sections are now available with dedicated annotations, and these annotations will become the only means of configuring those settings in a future release. For example, if you had setproxy.connect_timeout: 30000
in a KongIngress and applied ankonghq.com/override
annotation for that KongIngress to a Service, you will need to instead apply akonghq.com/connect-timeout: 30000
annotation to the Service.The
upstream
section of KongIngress will be replaced with a new resource, but this is still in development andupstream
is not officially deprecated yet.
This annotation can associate a KongIngress resource with an Ingress or a Service resource. It serves as a way to bridge the gap between a sparse Ingress API in Kubernetes with fine-grained controlled using the properties of Service, Route and Upstream entities in Kong.
Please follow the Using the KongIngress resource guide for details on how to use this annotation.
konghq.com/protocol
Available since controller 0.8
This annotation can be set on a Kubernetes Service resource and indicates the protocol that should be used by Kong to communicate with the service. In other words, the protocol is used for communication between a Kong Service and a Kubernetes Service, internally in the Kubernetes cluster.
Accepted values are:
http
https
grpc
grpcs
tcp
tls
konghq.com/protocols
Available since controller 0.8
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 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"
konghq.com/client-cert
Available since controller 0.8
This annotation sets the certificate and key-pair Kong should use to authenticate itself against the upstream service, if the upstream service is performing mutual-TLS (mTLS) authentication.
The value of this annotation should be the name of the Kubernetes TLS Secret resource which contains the TLS cert and key pair.
Under the hood, the controller creates a Certificate in Kong and then
sets the
service.client_certificate
for the service.
konghq.com/host-header
Available since controller 0.9
Sets the host_header
setting on the Kong upstream created to represent a
Kubernetes Service. By default, Kong upstreams set Host
to the hostname or IP
address of an individual target (the Pod IP for controller-managed
configuration). This annotation overrides the default behavior and sends
the annotation value as the Host
header value.
If konghq.com/preserve-host: true
is present on an Ingress (or
route.preserve_host: true
is present in a linked KongIngress), it will take
precedence over this annotation, and requests to the application will use the
hostname in the Ingress rule.
Sample usage:
konghq.com/host-header: "test.example.com"
ingress.kubernetes.io/service-upstream
Available since controller 0.6
By default, the Kong Ingress Controller distributes traffic amongst all the Pods of a Kubernetes Service by forwarding the requests directly to Pod IP addresses. One can choose the load-balancing strategy to use by specifying a KongIngress resource.
However, in some use-cases, the load-balancing should be left up
to kube-proxy
, or a sidecar component in the case of Service Mesh deployments.
Setting this annotation to a Service resource in Kubernetes will configure the Kong Ingress Controller to directly forward the traffic outbound for this Service to the IP address of the service (usually the ClusterIP).
kube-proxy
can then decide how it wants to handle the request and route the
traffic accordingly. If a sidecar intercepts the traffic from the controller,
it can also route traffic as it sees fit in this case.
Following is an example snippet you can use to configure this annotation
on a Service resource in Kubernetes, (please note the quotes around true
):
annotations:
ingress.kubernetes.io/service-upstream: "true"
konghq.com/regex-prefix
Available since controller 2.7
Sets the prefix of regex matched path to be some string other than /~
. In
Kong 3.0 and later, paths with regex match must start with ~
, so in
ingresses, /~
prefix used by default to annotate that the path is using
regex match. If the annotation is set, paths with the specified prefix is
considered as paths with regex match and will be translated to ~
started
path in Kong. For example, if an ingress has annotation
konghq.com/regex-prefix: "/@"
, paths started with /@
are considered as
paths using regex match. See: upgrade-to-kong-3x
konghq.com/path-handling
Available since controller 2.8
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.
konghq.com/headers.*
Available since controller 2.8
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
.
konghq.com/connect-timeout
Available since controller 2.8
Sets the connect timeout, in milliseconds. For example, setting this annotation
to 60000
will instruct the proxy to wait up to 60 seconds to complete the
initial TCP connection to the upstream service.
konghq.com/read-timeout
Available since controller 2.8
Sets the read timeout, in milliseconds. For example, setting this annotation
to 60000
will instruct the proxy to wait up to 60 seconds after sending a
request before timing out and returning a 504 response to the client.
konghq.com/write-timeout
Available since controller 2.8
Sets the write timeout, in milliseconds. For example, setting this annotation
to 60000
will instruct the proxy to wait up to 60 seconds without writing
data before closing a kept-alive connection.
konghq.com/retries
Available since controller 2.8
Sets the max retries on a request. For example, setting this annotation to 3
will re-send the request up to three times if it encounters a failure, such as
a timeout.