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

Getting started with the Kong Ingress Controller

Installation

Please follow the deployment documentation to install the Kong Ingress Controller onto your Kubernetes cluster.

Testing connectivity to Kong

This guide assumes that PROXY_IP environment variable is set to contain the IP address or URL pointing to Kong. If you’ve not done so, please follow one of the deployment guides to configure this environment variable.

If everything is setup correctly, making a request to Kong should return back a HTTP 404 Not Found.

$ curl -i $PROXY_IP

Expected output:

HTTP/1.1 404 Not Found
Date: Fri, 21 Jun 2019 17:01:07 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Content-Length: 48
Server: kong/1.1.2

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

This is expected since Kong doesn’t know how to proxy the request yet.

Set up an echo-server

Setup an echo-server application to demonstrate how to use the Kong Ingress Controller:

$ kubectl apply -f https://bit.ly/echo-service

Expected output:

service/echo created
deployment.apps/echo created

This application just returns information about the pod and details from the HTTP request.

Basic proxy

Create an Ingress rule to proxy the echo-server created previously:

$ 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 -

Expected output:

ingress.extensions/demo created

Test the Ingress rule:

$ curl -i $PROXY_IP/foo

Expected output:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 21 Jun 2019 17:12:49 GMT
Server: echoserver
X-Kong-Upstream-Latency: 0
X-Kong-Proxy-Latency: 1
Via: kong/1.1.2



Hostname: echo-758859bbfb-txt52

Pod Information:
        node name:      minikube
        pod name:       echo-758859bbfb-txt52
        pod namespace:  default
        pod IP: 172.17.0.14
<-- clipped -->

If everything is deployed correctly, you should see the above response. This verifies that Kong can correctly route traffic to an application running inside Kubernetes.

Using plugins in Kong

Setup a KongPlugin resource:

$ echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: request-id
config:
  header_name: my-request-id
plugin: correlation-id
" | kubectl apply -f -

Expected output:

kongplugin.configuration.konghq.com/request-id created

Create a new Ingress resource which uses this plugin:

$ echo "
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: demo-example-com
  annotations:
    konghq.com/plugins: request-id
spec:
  ingressClassName: kong
  rules:
  - host: example.com
    http:
      paths:
      - path: /bar
        pathType: ImplementationSpecific
        backend:
          service:
            name: echo
            port:
              number: 80
" | kubectl apply -f -

Expected output:

ingress.extensions/demo-example-com created

The above resource directs Kong to execute the request-id plugin whenever a request is proxied matching any rule defined in the resource.

Send a request to Kong:

$ curl -i -H "Host: example.com" $PROXY_IP/bar/sample

Expected output:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 21 Jun 2019 18:09:02 GMT
Server: echoserver
X-Kong-Upstream-Latency: 1
X-Kong-Proxy-Latency: 1
Via: kong/1.1.2



Hostname: echo-758859bbfb-cnfmx

Pod Information:
        node name:      minikube
        pod name:       echo-758859bbfb-cnfmx
        pod namespace:  default
        pod IP: 172.17.0.9

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

Request Information:
        client_address=172.17.0.2
        method=GET
        real path=/bar/sample
        query=
        request_version=1.1
        request_scheme=http
        request_uri=http://example.com:8080/bar/sample

Request Headers:
        accept=*/*
        connection=keep-alive
        host=example.com
        my-request-id=7250803a-a85a-48da-94be-1aa342ca276f#6
        user-agent=curl/7.54.0
        x-forwarded-for=172.17.0.1
        x-forwarded-host=example.com
        x-forwarded-port=8000
        x-forwarded-proto=http
        x-real-ip=172.17.0.1

Request Body:
        -no body in request-

The my-request-id can be seen in the request received by echo-server. It is injected by Kong as the request matches one of the Ingress rules defined in demo-example-com resource.

Using plugins on Services

Kong Ingress allows plugins to be executed on a service level, meaning Kong will execute a plugin whenever a request is sent to a specific k8s service, no matter which Ingress path it came from.

Create a KongPlugin resource:

$ echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rl-by-ip
config:
  minute: 5
  limit_by: ip
  policy: local
plugin: rate-limiting
" | kubectl apply -f -

Expected output:

kongplugin.configuration.konghq.com/rl-by-ip created

Next, apply the konghq.com/plugins annotation on the Kubernetes Service that needs rate-limiting:

kubectl patch svc echo \
  -p '{"metadata":{"annotations":{"konghq.com/plugins": "rl-by-ip\n"}}}'

Now, any request sent to this service will be protected by a rate-limit enforced by Kong:

$ curl -I $PROXY_IP/foo

Expected output:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Connection: keep-alive
Date: Fri, 21 Jun 2019 18:25:49 GMT
Server: echoserver
X-RateLimit-Limit-minute: 5
X-RateLimit-Remaining-minute: 2
X-Kong-Upstream-Latency: 0
X-Kong-Proxy-Latency: 4
Via: kong/1.1.2

$ curl -I -H "Host: example.com" $PROXY_IP/bar/sample

Expected output:

HTTP/1.1 200 OK
Content-Type: text/plain; charset=UTF-8
Connection: keep-alive
Date: Fri, 21 Jun 2019 18:28:30 GMT
Server: echoserver
X-RateLimit-Limit-minute: 5
X-RateLimit-Remaining-minute: 4
X-Kong-Upstream-Latency: 1
X-Kong-Proxy-Latency: 2
Via: kong/1.1.2

Result

This guide sets up the following configuration:

HTTP requests with /foo -> Kong enforces rate-limit -> echo server

HTTP requests with /bar -> Kong enforces rate-limit +   -> echo-server
   on example.com          injects my-request-id header