Install Kong Ingress Controller

Uses: Kong Ingress Controller

Deployment Platform:

Prerequisites

Kong Konnect

If you don’t have a Konnect account, you can get started quickly with our onboarding wizard.

The following Konnect items are required to complete this tutorial:
- Personal access token (PAT): Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.
Set the personal access token as an environment variable:
```
export KONNECT_TOKEN='YOUR KONNECT TOKEN'
```

Enable the Gateway API (Optional)

Install the Gateway API CRDs before installing Kong Ingress Controller.

kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.3.0/standard-install.yaml

Create a Gateway and GatewayClass instance to use.

echo "
apiVersion: v1
kind: Namespace
metadata:
  name: kong
---
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: kong
  annotations:
    konghq.com/gatewayclass-unmanaged: 'true'
spec:
  controllerName: konghq.com/kic-gateway-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: kong
spec:
  gatewayClassName: kong
  listeners:
  - name: proxy
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
         from: All
" | kubectl apply -n kong -f -

Konnect setup

For UI setup instructions to install Kong Ingress Controller on Konnect, use the Gateway Manager setup UI.

To create a Kong Ingress Controller in Konnect deployment, you need the following items:

A Kong Ingress Controller Control Plane, including the Control Plane URL
An mTLS certificate for Kong Ingress Controller to talk to Konnect

Create a KIC in Konnect Control Plane

Use the Konnect API to create a new CLUSTER_TYPE_K8S_INGRESS_CONTROLLER Control Plane:

CONTROL_PLANE_DETAILS=$( curl -X POST "https://us.api.konghq.com/v2/control-planes" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "My KIC CP",
       "cluster_type": "CLUSTER_TYPE_K8S_INGRESS_CONTROLLER"
     }')

We’ll need the id and telemetry_endpoint for the values.yaml file later. Save them as environment variables:

CONTROL_PLANE_ID=$(echo $CONTROL_PLANE_DETAILS | jq -r .id)
CONTROL_PLANE_TELEMETRY=$(echo $CONTROL_PLANE_DETAILS | jq -r '.config.telemetry_endpoint | sub("https://";"")')

Create mTLS certificates

Kong Ingress Controller talks to Konnect over a connected secured with TLS certificates.

Generate a new certificate using openssl:

openssl req -new -x509 -nodes -newkey rsa:2048 -subj "/CN=kongdp/C=US" -keyout ./tls.key -out ./tls.crt

The certificate needs to be a single line string to send it to the Konnect API with curl. Use awk to format the certificate:

export CERT=$(awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' tls.crt);

Next, upload the certificate to Konnect:

 curl -X POST "https://us.api.konghq.com/v2/control-planes/$CONTROL_PLANE_ID/dp-client-certificates" \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "cert": "'$CERT'"
     }'

Finally, store the certificate in a Kubernetes secret so that Kong Ingress Controller can read it:

kubectl create namespace kong -o yaml --dry-run=client | kubectl apply -f -
kubectl create secret tls konnect-client-tls -n kong --cert=./tls.crt --key=./tls.key

Create a values.yaml

Kong Ingress Controller must be configured to send it’s configuration to Konnect. Create a values.yaml file by copying and pasting the following command into your terminal:

echo 'controller:
  ingressController:
    image:
      tag: "3.4"
    env:
      feature_gates: "FillIDs=true"
    konnect:
      license:
        enabled: true
      enabled: true
      controlPlaneID: "'$CONTROL_PLANE_ID'"
      tlsClientCertSecretName: konnect-client-tls
      apiHostname: "us.kic.api.konghq.com"

gateway:
  image:
    repository: kong/kong-gateway
    tag: "3.11"
  env:
    konnect_mode: 'on'
    vitals: "off"
    cluster_mtls: pki
    cluster_telemetry_endpoint: "'$CONTROL_PLANE_TELEMETRY':443"
    cluster_telemetry_server_name: "'$CONTROL_PLANE_TELEMETRY'"
    cluster_cert: /etc/secrets/konnect-client-tls/tls.crt
    cluster_cert_key: /etc/secrets/konnect-client-tls/tls.key
    lua_ssl_trusted_certificate: system
    proxy_access_log: "off"
    dns_stale_ttl: "3600"
  resources:
    requests:
      cpu: 1
      memory: "2Gi"
  secretVolumes:
    - konnect-client-tls' > values.yaml

Install Kong

Kong provides Helm charts to install Kong Ingress Controller. Add the Kong charts repo and update to the latest version:

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

The default values file installs Kong Ingress Controller in Gateway Discovery mode with a DB-less Kong Gateway. This is the recommended deployment topology.

Run the following command to install Kong Ingress Controller:

helm upgrade --install kong kong/ingress -n kong --values ./values.yaml

helm install kong kong/ingress -n kong --create-namespace

Test connectivity to Kong

Call the proxy IP:

export PROXY_IP=$(kubectl get svc --namespace kong kong-gateway-proxy -o jsonpath='{range .status.loadBalancer.ingress[0]}{@.ip}{@.hostname}{end}')
curl -i $PROXY_IP

You will receive an HTTP 404 response as there are no routes configured:

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Content-Length: 48
X-Kong-Response-Latency: 0
Server: kong/3.9.1

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

FAQs

Why is my KIC instance read-only in Konnect?

Because Kubernetes resources are the source of truth for configuring Kong Gateway in Kubernetes, the KIC instance configuration in Konnect is marked as read-only. This prevents configuration drift in Kong Gateway caused by changes made outside the Ingress or Kubernetes Gateway API.

For example, if a Route is created via the Kubernetes Gateway API and then modified in Kong Gateway, those changes wouldn’t be reflected in the CRD and would conflict with the desired state defined in the CRD.

Next → 2. Services and Routes