kubernetes-ingress-controller

README

Kubernetes Ingress Controller for Kong

This repository contains an Ingress controller for Kubernetes that works by deploying Kong as a reverse proxy and load balancer.

Prerequisites

Tested with Kubernetes clusters running version 1.8 and later.

Get started

Please check the deployment documentation

How it works?

Using a standard Kubernetes deployment, the Ingress controller runs multiple containers in a single pod. This allows us to define in a unit containing an initContainer to run Kong migrations, one container for the Kong admin API in control-plane mode and one container for the ingress controller itself. With this approach we simplify the deploy of the required components without user intervention. Once the deployment passes the readiness and liveness probes it means the Kong migrations ran and ingress controller can communicate with the Kong admin API.

In a different deployment we run Kong in data-plane mode. This means the Kong instances only expose the proxy ports. By using this approach we can deploy and scale the data-plane with the requirements of your applications, i.e. using a daemonset, a deployment with affinity rules, etc.

The next diagram shows how the components interact:

Custom annotations

Please check the annotations document.

Annotation ingress.class

If you have multiple Ingress controllers in a single cluster, you can pick one by specifying the ingress.class annotation, eg creating an Ingress with an annotation like

metadata:
  name: foo
  annotations:
    kubernetes.io/ingress.class: "gce"

will target the GCE controller, forcing the ingress controller to ignore it, while an annotation like

metadata:
  name: foo
  annotations:
    kubernetes.io/ingress.class: "nginx"

will target the Kong Ingress controller, forcing the GCE controller to ignore it.

Note: Deploying multiple ingress controller and not specifying the annotation will cause both controllers fighting to satisfy the Ingress.

Custom Resource Definitions

Please check the custom types document.

Multiple ingress controllers

If you're running multiple ingress controllers, or running on a cloud provider that handles ingress, you need to specify the annotation kubernetes.io/ingress.class: "nginx" in all ingresses you would like this controller to claim. This mechanism also provides users the ability to run multiple Kong ingress controllers (e.g. one which serves public traffic, one which serves "internal" traffic). When using this functionality the option --ingress-class should set a value unique for the cluster. Here is a partial example:

spec:
  template:
     spec:
       containers:
         - name: kong-ingress-internal-controller
           args:
             - /kong-ingress-controller
             - '--election-id=ingress-controller-leader-internal'
             - '--ingress-class=kong-internal'

Not specifying the annotation will lead to multiple ingress controllers claiming the same ingress. Setting a value which does not match the class of any existing ingress controllers will cause all ingress controllers ignoring the ingress.

Why the default kubernetes.io/ingress.class is "nginx"?

This is to provide out of the box compatibility with tools like kube-lego

Why endpoints and not services

The Kong ingress controller does not use Services to route traffic to the pods. Instead it uses the Endpoints API to bypass kube-proxy to allow Kong features like session affinity and custom load balancing algorithms. It also removes overhead, such as conntrack entries for iptables DNAT.

Relation with ingress-nginx

This repository uses code from ingress-nginx as the base. Code like annotations are not present because some features are present as plugins.

Roadmap

Please check the roadmap document.