You are browsing documentation for an older version. See the latest documentation here.

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.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:

echo "
---

apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: kong
  annotations:
    konghq.com/gatewayclass-unmanaged: 'true'
spec:
  controllerName: konghq.com/kic-gateway-controller
---

apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: kong
spec:
  gatewayClassName: kong
  listeners:
  - name: proxy
    port: 80
    protocol: HTTP
" | kubectl apply -f -

gatewayclass.gateway.networking.k8s.io/kong created
gateway.gateway.networking.k8s.io/kong created

echo "
apiVersion: networking.k8s.io/v1
kind: IngressClass
metadata:
  name: kong
spec:
  controller: ingress-controllers.konghq.com/kong
" | kubectl apply -f -

ingressclass.networking.k8s.io/kong configured

kubectl get gateway kong

NAME   CLASS   ADDRESS        READY   AGE
kong   kong    203.0.113.42   True    4m46s

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.

echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo
spec:
  ingressClassName: kong
  rules:
  - http:
      paths:
      - path: /foo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 80
" | kubectl apply -f -

ingress.extensions/demo created

Let’s test:

curl -i $PROXY_IP/foo

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: echoserver
X-Kong-Upstream-Latency: 2
X-Kong-Proxy-Latency: 1
Via: kong/3.1.1

Hostname: echo-d778ffcd8-n9bss

Pod Information:
  node name:	gke-harry-k8s-dev-default-pool-bb23a167-8pgh
  pod name:	echo-d778ffcd8-n9bss
  pod namespace:	default
  pod IP:	10.60.0.4

Server values:
  server_version=nginx: 1.12.2 - lua: 10010

Request Information:
  client_address=10.60.1.10
  method=GET
  real path=/foo
  query=
  request_version=1.1
  request_scheme=http
  request_uri=http://35.233.170.67:8080/foo

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:

echo "apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
  name: sample-customization
upstream:
  hash_on: header
  hash_on_header: x-lb
  hash_fallback: ip
  algorithm: consistent-hashing" | kubectl apply -f -

kongingress.configuration.konghq.com/test created

Now, let’s associate this KongIngress resource with our Service resource using the konghq.com/override annotation.

kubectl patch service echo -p '{"metadata":{"annotations":{"konghq.com/override":"sample-customization"}}}'

service/echo patched

With consistent hashing and client IP fallback, sending repeated requests without any x-lb header now sends them to the same Pod:

for n in {1..5}; do curl -s $PROXY_IP/foo | grep "pod name:"; done

	pod name:	echo-588c888c78-6jrmn
	pod name:	echo-588c888c78-6jrmn
	pod name:	echo-588c888c78-6jrmn
	pod name:	echo-588c888c78-6jrmn
	pod name:	echo-588c888c78-6jrmn

If you add the header, Kong hashes its value and distributes it to the same replica when using the same value:

for n in {1..3}; do
  curl -s $PROXY_IP/foo -H "x-lb: foo" | grep "pod name:";
  curl -s $PROXY_IP/foo -H "x-lb: bar" | grep "pod name:";
  curl -s $PROXY_IP/foo -H "x-lb: baz" | grep "pod name:";
done

	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-6jrmn
	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-6jrmn
	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-6jrmn

Increasing the replicas redistributes some subsequent requests onto the new replica:

kubectl patch deploy echo --patch '{"spec": {"replicas": 3}}'

deployment.apps/echo patched

for n in {1..3}; do
  curl -s $PROXY_IP/foo -H "x-lb: foo" | grep "pod name:";
  curl -s $PROXY_IP/foo -H "x-lb: bar" | grep "pod name:";
  curl -s $PROXY_IP/foo -H "x-lb: baz" | grep "pod name:";
done

	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-d477r
	pod name:	echo-588c888c78-6jrmn
	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-d477r
	pod name:	echo-588c888c78-6jrmn
	pod name:	echo-588c888c78-nk4jc
	pod name:	echo-588c888c78-d477r
	pod name:	echo-588c888c78-6jrmn

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:

echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-copy
spec:
  ingressClassName: kong
  rules:
  - http:
      paths:
      - path: /foo
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 1027
" | kubectl apply -f -

ingress.extensions/demo-copy created

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:

echo "
---
apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
  name: header-alpha
route:
  headers:
    x-split:
	- alpha
---
apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
  name: header-bravo
route:
  headers:
    x-split:
	- bravo
	- charlie
    x-legacy:
	- enabled
  " | kubectl apply -f -

kongingress.configuration.konghq.com/header-alpha created
kongingress.configuration.konghq.com/header-bravo created

Now, you can associate these KongIngress resources with your Ingress resources using the konghq.com/override annotation:

kubectl patch ingress demo -p '{"metadata":{"annotations":{"konghq.com/override":"header-alpha"}}}'

ingress.extensions/demo patched

kubectl patch ingress demo-copy -p '{"metadata":{"annotations":{"konghq.com/override":"header-bravo"}}}'

ingress.extensions/demo-copy patched

Now, neither of the routes will match:

$ curl -s $PROXY_IP/foo

{"message":"no Route matched with those values"}

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:

curl -sv $PROXY_IP/foo -H "kong-debug: 1" -H "x-split: alpha" 2>&1 | grep -i kong-route-name

< Kong-Route-Name: default.demo.00

curl -sv $PROXY_IP/foo -H "kong-debug: 1" -H "x-split: bravo" -H "x-legacy: enabled"  2>&1 | grep -i kong-route-name

< Kong-Route-Name: default.demo-copy.00

curl -sv $PROXY_IP/foo -H "kong-debug: 1" -H "x-split: charlie" -H "x-legacy: enabled"  2>&1 | grep -i kong-route-name

< Kong-Route-Name: default.demo-copy.00

Note that demo-copy requires both headers, but matches any of the individual values configured for a given header.