You are browsing documentation for an outdated version. See the latest documentation here.
Getting started with the Kubernetes Ingress Controller
Installation
Please follow the deployment documentation to install the Kubernetes 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 Kubernetes 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