You are browsing documentation for an outdated version. See the
latest documentation here.
Using KongIngress resource
In this guide, we will learn how to use KongIngress resource to control
Note: Many fields available on KongIngress are also available as
You can add these annotations directly to Service and Ingress resources
without creating a separate KongIngress resource. When an annotation is
available, it is the preferred means of configuring that setting, and the
annotation value will take precedence over a KongIngress value if both set
the same setting. This guide focuses on settings that can only be set using
Please follow the deployment documentation to install
the Kubernetes Ingress Controller onto your Kubernetes cluster.
Testing connectivity to Kong
This guide assumes that the
PROXY_IP environment variable is
set to contain the IP address or URL pointing to Kong.
Please follow one of the
deployment guides to configure this environment variable.
If everything is setup correctly, making a request to Kong should return
HTTP 404 Not Found.
This is expected as Kong does not yet know how to proxy the request.
Install a dummy service
We will start by installing the echo service and increasing its replica count:
Let’s expose the echo service outside the Kubernetes cluster
by defining an Ingress.
Use KongIngress with a Service resource
By default, Kong will round-robin requests between upstream replicas. If you
curl -s $PROXY_IP/foo | grep "pod name:" repeatedly, you should see the
reported Pod name alternate between two values.
You can configure the Kong upstream associated with the Service to use a
different load balancing strategy,
such as consistently sending requests to the same upstream based on a header
value. This and other fields available on the Kong upstream resource can’t be
configured using annotations, only using KongIngress.
To modify these behaviours, let’s first create a KongIngress resource
defining the new behaviour:
Now, let’s associate this KongIngress resource with our Service resource
With consistent hashing and client IP fallback, sending repeated requests without any
x-lb header now sends them to the
If you add the header, Kong hashes its value and distributes it to the
same replica when using the same value:
Increasing the replicas redistributes some subsequent requests onto the new
Kong’s load balancer doesn’t directly distribute requests to each of the
Service’s Endpoints. It first distributes them evenly across a number of
equal-size buckets. These buckets are then distributed across the available
Endpoints according to their weight. For Ingresses, however, there is only one
Service, and the controller assigns each Endpoint (represented by a Kong
upstream target) equal weight. In this case, requests are evenly hashed across all
Gateway API HTTPRoute rules support distributing traffic across multiple
Services. The rule can assign weights to the Services to change the proportion
of requests an individual Service receives. In Kong’s implementation, all
Endpoints of a Service have the same weight. Kong calculates a per-Endpoint
upstream target weight such that the aggregate target weight of the Endpoints
is equal to the proportion indicated by the HTTPRoute weight.
For example, say you have two Services with the following configuration:
- One Service has four Endpoints
- The other Service has two Endpoints
- Each Service has weight
50 in the HTTPRoute
The targets created for the two-Endpoint Service have double the
weight of the targets created for the four-Endpoint Service (two weight
targets and four weight
8 targets). Scaling the
four-Endpoint Service to eight would halve the weight of its targets (two
16 targets and eight weight
KongIngress can also configure upstream health checking behavior as well. See the
for the health check fields.
Use KongIngress with Ingress resource
Kong can match routes based on request headers. For example, you can have two
separate routes for
/foo, one that matches requests which include an
x-split: alpha, and another that matches requests with
x-split: bravo or
x-legacy: charlie. Configuring this using the ingress controller requires
attaching a KongIngress to an Ingress resource. It is not available via an
To start, create a copy of the Ingress you created earlier with a different
The controller creates this route, but it’s not immediately accessible. All
/foo will match the original
When two routes have
identical matching criteria, Kong uses their creation time as a tiebreaker, defaulting to the route created first. You may see the matched route flipped if you restart the container when
using DB-less mode, as both routes are then re-added at the same time.
To fix this, create KongIngresses that differentiate the routes via headers:
Now, you can associate these KongIngress resources with your Ingress resources
Now, neither of the routes will match:
Add headers to your requests to make your requests match routes again.
You’ll be able to access both routes depending on which header you use:
demo-copy requires both headers, but matches any of the
individual values configured for a given header.