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 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 upstream HTTP application

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:

echo "
apiVersion: v1
kind: Service
metadata:
  labels:
    app: echo
  name: echo
spec:
  ports:
  - port: 1025
    name: tcp
    protocol: TCP
    targetPort: 1025
  - port: 1026
    name: udp
    protocol: TCP
    targetPort: 1026
  - port: 1027
    name: http
    protocol: TCP
    targetPort: 1027
  selector:
    app: echo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: echo
  name: echo
spec:
  replicas: 1
  selector:
    matchLabels:
      app: echo
  strategy: {}
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: echo
    spec:
      containers:
      - image: kong/go-echo:latest
        name: echo
        ports:
        - containerPort: 1027
        env:
          - name: NODE_NAME
            valueFrom:
              fieldRef:
                fieldPath: spec.nodeName
          - name: POD_NAME
            valueFrom:
              fieldRef:
                fieldPath: metadata.name
          - name: POD_NAMESPACE
            valueFrom:
              fieldRef:
                fieldPath: metadata.namespace
          - name: POD_IP
            valueFrom:
              fieldRef:
                fieldPath: status.podIP
        resources: {}
" | kubectl apply -f -

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:

Ingress

Gateway APIs

Official distributions of Kong Ingress Controller come with a kong IngressClass by default. If kubectl get ingressclass kong does not return a not found error, you can skip this command.

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

The results should look like this:

ingressclass.networking.k8s.io/kong configured

echo "
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: GatewayClass
metadata:
  name: kong
spec:
  controllerName: konghq.com/kic-gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: Gateway
metadata:
  name: kong
  annotations:
    konghq.com/gateway-unmanaged: kong/kong-proxy

spec:
  gatewayClassName: kong
  listeners:
  - name: proxy
    port: 80
    protocol: HTTP
" | kubectl apply -f -

The results should look like this:

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

After the controller has acknowledged the Gateway, it shows the proxy IP and its status:

kubectl get gateway kong

The results should look like this:

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.

      Command
    

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

      Command
    

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

      Command
    

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

      Command
    
      Response
    
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:

      Command
    

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

      Command
    

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

      Command
    
      Response
    
kubectl patch deploy echo --patch '{"spec": {"replicas": 3}}'
deployment.apps/echo patched

      Command
    

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

      Command
    

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

      Command
    

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

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

      Command
    
      Response
    
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:

      Command
    
      Response
    
$ 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:

      Command
    
      Response
    
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

      Command
    
      Response
    
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

      Command
    
      Response
    
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.