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

Running the Kong Ingress Controller with Istio

This guide walks you through deploying Kong Gateway with Kong Ingress Controller as the gateway for Istio as your service mesh solution.

See the version compatibility reference for the tested compatible versions of Kong Ingress Controller and Istio.

Overview

Istio is a popular service mesh that enables traffic management, security, and observability features for Kubernetes clusters.

With Kong Gateway and Istio, you can combine the mesh features of Istio inside your cluster with Kong’s rich feature set for ingress traffic from outside the cluster.

This guide shows how to:

Install Istio and Kong Gateway with Kong Ingress Controller in your cluster.
Deploy an example Istio-enabled application.
Deploy an Ingress customized with a Kong plugin for the example application.
Make requests to the sample application via Kong and Istio.
Explore the observability features of Istio to visualize cluster traffic.

Prerequisites

A Kubernetes cluster v1.19 or later
kubectl v1.19 or later
Helm v3.5 or later
cURL version 7.x.x

You can use a managed cluster from a cloud provider, such as AWS (EKS), Google Cloud (GKE), or Azure (AKS), or you can work locally with tools such as Minikube or Microk8s.

Your Kubernetes cluster must provision LoadBalancer type Services. Cloud providers generally automate LoadBalancer type Service provisioning with their default settings, but if you run your cluster elsewhere you might need to check the relevant documentation for details. See also the Kubernetes documentation
for external load balancers.

Some of the kubectl calls in this guide assume your test cluster is the current default cluster context. To check, or for more information, see the Kubernetes documentation on configuring access to multiple clusters.

Download and verify Istio

This guide shows how to install with istioctl, because it’s the community recommended method. The Istio installation guides explain alternative deployment mechanisms.

You can also explore the Istio FAQ for more information about the differences between methods. However, if you choose another installation method, you might need to adjust the examples in this guide.

Download the istioctl command-line utility for your platform:
```
curl -s -L https://istio.io/downloadIstio | ISTIO_VERSION=1.11.2 sh -
```
The response includes instructions to set up the istioctl program locally and perform pre-check validation of the Istio installation.
Make sure to add istioctl to your shell’s path:
```
export PATH="$PATH:$PWD/istio-1.11.2/bin"
```
Verify that istioctl is working, and run checks on your Kubernetes cluster to ensure Istio will deploy to it properly:
```
istioctl x precheck
```

Deploy Istio

Istio provides configuration profiles to let you customize your Istio deployment, and default profiles are included with the installation. This guide works with the demo profile, which is meant for testing and evaluation.

Deploy Istio with the demo profile:

istioctl install --set profile=demo -y

Create an Istio-enabled namespace for Kong Ingress Controller

To integrate Istio’s mesh functionality in any given Kubernetes Pod, a namespace must be labeled with the istio-injection=enabled label to instruct IstioD – the main control program for Istio – to manage the pods and add them to the mesh network.

Create the Istio-enabled namespace:
```
kubectl create namespace kong-istio
```

Enable the namespace for the Istio mesh:

kubectl label namespace kong-istio istio-injection=enabled

Deploy Kong Gateway and Kong Ingress Controller

The Kong Helm Chart deploys a Pod that includes containers for Kong Gateway and Kong Ingress Controller. Here’s how to deploy it to the Istio-enabled kong-istio namespace.

Make sure you have the Kong Helm repository configured locally:

helm repo add kong https://charts.konghq.com && helm repo update

Deploy the chart:

helm install -n kong-istio kong-istio kong/kong

Verify that Kong containers are deployed and the Istio sidecar container is injected properly:

kubectl describe pod -n kong-istio -l app.kubernetes.io/instance=kong-istio

The output should look like:

Events:
  Type     Reason     From               Message
  ----     ------     ----               -------
  Normal   Scheduled  default-scheduler  Successfully assigned kong-istio/kong-istio-kong-8f875f9fd-qsv4p to gke-istio-testing-default-pool-403b2219-l5ns
  Normal   Pulled     kubelet            Container image "docker.io/istio/proxyv2:1.11.2" already present on machine
  Normal   Created    kubelet            Created container istio-init
  Normal   Started    kubelet            Started container istio-init
  Normal   Pulling    kubelet            Pulling image "kong/kubernetes-ingress-controller:1.3"
  Normal   Pulled     kubelet            Successfully pulled image "kong/kubernetes-ingress-controller:1.3" in 2.645390171s
  Normal   Created    kubelet            Created container ingress-controller
  Normal   Started    kubelet            Started container ingress-controller
  Normal   Pulling    kubelet            Pulling image "kong:2.5"
  Normal   Pulled     kubelet            Successfully pulled image "kong:2.5" in 3.982679281s
  Normal   Created    kubelet            Created container proxy
  Normal   Started    kubelet            Started container proxy
  Normal   Pulled     kubelet            Container image "docker.io/istio/proxyv2:1.11.2" already present on machine
  Normal   Created    kubelet            Created container istio-proxy
  Normal   Started    kubelet            Started container istio-proxy

See also the Kubernetes documentation on using kubectl to fetch pod details.

Deploy BookInfo example application

The Istio BookInfo application provides a basic example that lets you explore and evaluate Istio’s mesh features.

As in previous steps, you create a namespace, add the appropriate label, and then deploy.

Create the namespace:
```
kubectl create namespace bookinfo
```

Label the namespace for Istio injection:

kubectl label namespace bookinfo istio-injection=enabled

Deploy the BookInfo app from the Istio bundle:

kubectl -n bookinfo apply -f istio-1.11.2/samples/bookinfo/platform/kube/bookinfo.yaml

The response should look like:

service/details created
serviceaccount/bookinfo-details created
deployment.apps/details-v1 created
service/ratings created
serviceaccount/bookinfo-ratings created
deployment.apps/ratings-v1 created
service/reviews created
serviceaccount/bookinfo-reviews created
deployment.apps/reviews-v1 created
deployment.apps/reviews-v2 created
deployment.apps/reviews-v3 created
service/productpage created
serviceaccount/bookinfo-productpage created
deployment.apps/productpage-v1 created

Wait until the application is up:

kubectl -n bookinfo wait --timeout 120s --for=condition=Available deployment productpage-v1

Access BookInfo externally through Kong Gateway

At this point the BookInfo application is available only internally. Here’s how to expose it as a service with Ingress.

Save the following as bookinfo-ingress.yaml:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: productpage
  namespace: bookinfo
spec:
  ingressClassName: kong
  rules:
  - http:
      paths:
      - path: /
        pathType: ImplementationSpecific
        backend:
          service:
            name: productpage
            port:
              number: 9080

Apply the manifest:
```
kubectl apply -f bookinfo-ingress.yaml
```
To make HTTP requests using Kong Gateway as ingress, you need the IP address of the load balancer. Get the LoadBalancer address and store it in a local PROXY_IP environment variable:
```
export PROXY_IP=$(kubectl -n kong-istio get svc kong-istio-kong-proxy -o=jsonpath='{.status.loadBalancer.ingress[0].ip}')
```
If you’re running your cluster on AWS, specify .hostname instead of .ip. This is because the AWS load balancer provides only a DNS name. This can also happen with other cluster providers.

Make sure to check that the value of $PROXY_IP is the value of the external host. You can check with kubectl get svc kong-istio-kong-proxy.

Make an external connection request:

curl -s -v http://$PROXY_IP | head -4

The response should look like:

curl -s -v http://$PROXY_IP | head -4
*   Trying 127.0.0.1:80...
* Connected to 127.0.0.1 (127.0.0.1) port 80 (#0)
> GET / HTTP/1.1
> Host: 127.0.0.1
> User-Agent: curl/7.76.1
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< content-type: text/html; charset=utf-8
< content-length: 1683
< server: istio-envoy
< x-envoy-upstream-service-time: 6
< x-kong-upstream-latency: 4
< x-kong-proxy-latency: 1
< via: kong/2.5.0
< x-envoy-decorator-operation: kong-istio-kong-proxy.kong-istio.svc.cluster.local:80/*
<
{ [1079 bytes data]
* Connection #0 to host 127.0.0.1 left intact
<!DOCTYPE html>
<html>
  <head>
    <title>Simple Bookstore App</title>

Note the following in the response:

<title>Simple Bookstore App</title> - connected to the BookInfo app as expected.
server: istio-envoy - the Istio mesh network is in use for the BookInfo product page.
via: kong/2.5.0 - Kong Gateway provides the connection to the backend BookInfo service.

Configure rate limiting with a Kong plugin

To demonstrate Kong features for Istio enabled services, you can create a KongPlugin to enforce Kong rate-limiting on ingress requests to the BookInfo service. The plugin adds rate limiting to the BookInfo application and limits outside access to 30 requests per minute.

Save the following as bookinfo-ratelimiter.yaml:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: rate-limit
  namespace: bookinfo
plugin: rate-limiting
config:
  minute: 30
  policy: local

Apply the manifest:

kubectl apply -f bookinfo-ratelimiter.yaml

Add an annotation to the Ingress resource to attach rate limiting:

kubectl -n bookinfo patch ingress productpage -p '{"metadata":{"annotations":{"konghq.com/plugins":"rate-limit"}}}'

Inspect the headers in the response from the BookInfo product page:

curl -s -v http://$PROXY_IP 2>&1 | grep ratelimit

The response should look like:

< x-ratelimit-remaining-minute: 26
< x-ratelimit-limit-minute: 30
< ratelimit-remaining: 26
< ratelimit-limit: 30
< ratelimit-reset: 2

For more examples of Kong features to add to your environment, see the available guides.

Mesh network observability with Kiali

For observability, Istio includes a web console called Kiali that can provide topology, health, and other features to provide insights into your application traffic.

You also need a Prometheus metrics server, and Grafana for visualization dashboards. Istio includes these as addons. Here’s what to do:

Install Prometheus:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.11/samples/addons/prometheus.yaml

The response should look like:

serviceaccount/prometheus created
configmap/prometheus created
clusterrole.rbac.authorization.k8s.io/prometheus created
clusterrolebinding.rbac.authorization.k8s.io/prometheus created
service/prometheus created
deployment.apps/prometheus created

Install Grafana:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.11/samples/addons/grafana.yaml

The response should look like:

serviceaccount/grafana created
configmap/grafana created
service/grafana created
deployment.apps/grafana created
configmap/istio-grafana-dashboards created
configmap/istio-services-grafana-dashboards created

Install Kiali:

kubectl apply -f https://raw.githubusercontent.com/istio/istio/release-1.11/samples/addons/kiali.yaml

The response should look like:

serviceaccount/kiali created
configmap/kiali created
clusterrole.rbac.authorization.k8s.io/kiali-viewer created
clusterrole.rbac.authorization.k8s.io/kiali created
clusterrolebinding.rbac.authorization.k8s.io/kiali created
role.rbac.authorization.k8s.io/kiali-controlplane created
rolebinding.rbac.authorization.k8s.io/kiali-controlplane created
service/kiali created
deployment.apps/kiali created

Generate traffic for the BookInfo application, to create traffic metrics to view in Kiali:

COUNT=25 ; until [ $COUNT -le 0 ]; do curl -s -o /dev/null http://$PROXY_IP ; ((COUNT--)); done

In a production environment, you’d access the Kiali dashboard through the Kong ingress. But this sample version of Kiali is meant for exploring only internal traffic on the cluster. You can instead use the port-forwarding functionality that istioctl provides.

In a new terminal, run:
```
istioctl dashboard kiali
```
This runs a port-forward to Kiali in the background and opens it in your web browser. The response should look like:
```
http://localhost:20001/kiali
```
If http://localhost:20001/kiali doesn’t open automatically in your browser, navigate manually to the address.

You’re now connected to Kiali and have a window into the traffic moving across your mesh network. Familiarize yourself with Kiali and graphically view the topology for your BookInfo application’s web requests:

Choose Workloads from the menu on the left.
Select bookinfo in the Namespace drop-down menu.
Select the productpage-v1 service name.
In the top-right corner change the Last <time> dropdown to Last 1h.
Select the three dots button in the top-right corner of Graph Overview and select Show full graph.
Select kong-istio alongside bookinfo in the Namespace diagram.

You should see a connection graph that shows connections from the Kong Gateway deployed at the edge of your cluster down to the backend BookInfo application. The graph demonstrates some of the fundamental capabilities of Istio, and you can explore further with Kiali. For more information, see the Kiali Documentation.

The Istio Task Documentation also provides guides for other Istio features.