Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Ingress Controller
2.2.x
  • Home icon
  • Kong Ingress Controller
  • Guides
  • Getting started with the Kong Ingress Controller
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.11.x (latest)
  • 2.10.x
  • 2.9.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • 2.5.x
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.3.x
  • 1.2.x
  • 1.1.x
  • 1.0.x
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Installation
  • Testing connectivity to Kong
  • Set up an echo-server
  • Basic proxy
  • Using plugins in Kong
  • Using plugins on Services
  • Result
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
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023