このページは、まだ日本語ではご利用いただけません。翻訳中です。
旧バージョンのドキュメントを参照しています。 最新のドキュメントはこちらをご参照ください。
Using KongIngress resource
In this guide, we will learn how to use KongIngress resource to control proxy behavior.
Note: Many fields available on KongIngress are also available as annotations. 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 KongIngress.
Installation
Follow the deployment documentation to install the Kong Ingress Controller on the Kubernetes cluster.
Installing the Gateway APIs
If you wish to use the Gateway APIs examples, follow the supplemental Gateway APIs installation instructions.
Testing connectivity to Kong Gateway
Ensure that the PROXY_IP
environment variable is
set to contain the IP address or URL pointing to Kong Gateway.
The deployment guide that you used to install the Kong Ingress Controller on the Kubernetes cluster provides the instructions to configure this environment variable.
If everything is set correctly, a request to Kong Gateway returns
a HTTP 404 Not Found
status code:
curl -i $PROXY_IP
The results should look like this:
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Content-Length: 48
X-Kong-Response-Latency: 0
Server: kong/3.0.0
{"message":"no Route matched with those values"}
This is expected because Kong Gateway doesn’t know how to proxy the request yet.
Deploy an echo service
To proxy requests, you need an upstream application to send a request to. Deploying this echo server provides a simple application that returns information about the Pod it’s running in:
kubectl apply -f https://docs.jp.konghq.com/assets/kubernetes-ingress-controller/examples/echo-service.yaml
The results should look like this:
service/echo created
deployment.apps/echo created
Create a configuration group
Ingress and Gateway APIs controllers need a configuration that indicates which set of routing configuration they should recognize. This allows multiple controllers to coexist in the same cluster. Before creating individual routes, you need to create a class configuration to associate routes with:
Kong Ingress Controller recognizes the kong
IngressClass and
konghq.com/kic-gateway-controller
GatewayClass
by default. Setting the CONTROLLER_INGRESS_CLASS
or
CONTROLLER_GATEWAY_API_CONTROLLER_NAME
environment variable to
another value overrides these defaults.
Set up Ingress
Gateway APIs resources, such as HTTPRoute, do not support KongIngress, and must use annotations instead.
Let’s expose the echo service outside the Kubernetes cluster by defining an Ingress.
Let’s test:
Use KongIngress with a Service resource
By default, Kong will round-robin requests between upstream replicas. If you
run 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
using the konghq.com/override
annotation.
With consistent hashing and client IP fallback, sending repeated requests without any x-lb
header now sends them to the
same Pod:
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 replica:
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 Endpoints.
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 16
targets and four weight 8
targets). Scaling the
four-Endpoint Service to eight would halve the weight of its targets (two
weight 16
targets and eight weight 4
targets).
KongIngress can also configure upstream health checking behavior as well. See the KongIngress reference 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
Ingress annotation.
To start, create a copy of the Ingress you created earlier with a different name:
The controller creates this route, but it’s not immediately accessible. All
requests for /foo
will match the original demo
route.
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
using the konghq.com/override
annotation:
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:
Note that demo-copy
requires both headers, but matches any of the
individual values configured for a given header.